Import Polish translation of the FreeBSD Handbook. While some

chapters are not translated now, they will be updated soon.

Submitted by:	Cezary Morga <cezarym@data.pl>

82 files changed, 74976 insertions, 0 deletions

diff --git a/pl_PL.ISO8859-2/books/Makefile b/pl_PL.ISO8859-2/books/Makefile
new file mode 100644
index 0000000000..9860667d73
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/Makefile
@@ -0,0 +1,18 @@
+# $FreeBSD$
+# Original revision: 1.14
+
+#SUBDIR+= arch-handbook
+#SUBDIR+= corp-net-guide
+#SUBDIR+= design-44bsd
+#SUBDIR+= dev-model
+#SUBDIR+= developers-handbook
+#SUBDIR+= faq
+#SUBDIR+= fdp-primer
+SUBDIR = handbook
+#SUBDIR+= pmake
+#SUBDIR+= porters-handbook
+
+ROOT_SYMLINKS= faq handbook
+
+DOC_PREFIX?= ${.CURDIR}/../..
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
diff --git a/pl_PL.ISO8859-2/books/Makefile.inc b/pl_PL.ISO8859-2/books/Makefile.inc
new file mode 100644
index 0000000000..9b0603ff02
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/Makefile.inc
@@ -0,0 +1,6 @@
+# 
+# $FreeBSD$
+# Original revision: 1.4
+#
+
+DESTDIR?=	${DOCDIR}/pl_PL.ISO8859-2/books/${.CURDIR:T}
diff --git a/pl_PL.ISO8859-2/books/handbook/Makefile b/pl_PL.ISO8859-2/books/handbook/Makefile
new file mode 100644
index 0000000000..505f8e1c82
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/Makefile
@@ -0,0 +1,256 @@
+# The FreeBSD Polish Documentation Project
+#
+# $FreeBSD$
+# Original revision: 1.100
+#
+# Build the FreeBSD Handbook.
+#
+
+# ------------------------------------------------------------------------
+#
+# Handbook-specific variables
+#
+#	WITH_PGPKEYS	The print version of the handbook only prints PGP
+#			fingerprints by default.  If you would like for the
+#			entire key to be displayed, then set this variable.
+#			This option has no affect on the HTML formats.
+#			
+# Handbook-specific targets
+#
+#       pgpkeyring      This target will read the contents of
+#                       pgpkeys/chapter.sgml and will extract all of
+#                       the pgpkeys to standard out.  This output can then
+#                       be redirected into a file and distributed as a 
+#                       public keyring of FreeBSD developers that can
+#                       easily be imported into PGP/GPG.
+#
+# ------------------------------------------------------------------------
+
+.PATH: ${.CURDIR}/../../share/sgml/glossary
+
+MAINTAINER=	doc@FreeBSD.org
+
+DOC?= book
+
+FORMATS?= html-split
+
+HAS_INDEX= true
+USE_PS2PDF=	yes
+
+INSTALL_COMPRESSED?= gz
+INSTALL_ONLY_COMPRESSED?=
+
+IMAGES_EN = advanced-networking/isdn-bus.eps
+IMAGES_EN+= advanced-networking/isdn-twisted-pair.eps
+IMAGES_EN+= advanced-networking/natd.eps
+IMAGES_EN+= advanced-networking/net-routing.pic
+IMAGES_EN+= advanced-networking/static-routes.pic
+IMAGES_EN+= geom/striping.pic
+IMAGES_EN+= install/adduser1.scr
+IMAGES_EN+= install/adduser2.scr
+IMAGES_EN+= install/adduser3.scr
+IMAGES_EN+= install/boot-mgr.scr
+IMAGES_EN+= install/console-saver1.scr
+IMAGES_EN+= install/console-saver2.scr
+IMAGES_EN+= install/console-saver3.scr
+IMAGES_EN+= install/console-saver4.scr
+IMAGES_EN+= install/desktop.scr
+IMAGES_EN+= install/disklabel-auto.scr
+IMAGES_EN+= install/disklabel-ed1.scr
+IMAGES_EN+= install/disklabel-ed2.scr
+IMAGES_EN+= install/disklabel-fs.scr
+IMAGES_EN+= install/disklabel-root1.scr
+IMAGES_EN+= install/disklabel-root2.scr
+IMAGES_EN+= install/disklabel-root3.scr
+IMAGES_EN+= install/disk-layout.eps
+IMAGES_EN+= install/dist-set.scr
+IMAGES_EN+= install/dist-set2.scr
+IMAGES_EN+= install/docmenu1.scr
+IMAGES_EN+= install/ed0-conf.scr
+IMAGES_EN+= install/ed0-conf2.scr
+IMAGES_EN+= install/edit-inetd-conf.scr
+IMAGES_EN+= install/fdisk-drive1.scr
+IMAGES_EN+= install/fdisk-drive2.scr
+IMAGES_EN+= install/fdisk-edit1.scr
+IMAGES_EN+= install/fdisk-edit2.scr
+IMAGES_EN+= install/ftp-anon1.scr
+IMAGES_EN+= install/ftp-anon2.scr
+IMAGES_EN+= install/hdwrconf.scr
+IMAGES_EN+= install/keymap.scr
+IMAGES_EN+= install/main1.scr
+IMAGES_EN+= install/mainexit.scr
+IMAGES_EN+= install/main-std.scr
+IMAGES_EN+= install/main-options.scr
+IMAGES_EN+= install/main-doc.scr
+IMAGES_EN+= install/main-keymap.scr
+IMAGES_EN+= install/media.scr
+IMAGES_EN+= install/mouse1.scr
+IMAGES_EN+= install/mouse2.scr
+IMAGES_EN+= install/mouse3.scr
+IMAGES_EN+= install/mouse4.scr
+IMAGES_EN+= install/mouse5.scr
+IMAGES_EN+= install/mouse6.scr
+IMAGES_EN+= install/mta-main.scr
+IMAGES_EN+= install/net-config-menu1.scr
+IMAGES_EN+= install/net-config-menu2.scr
+IMAGES_EN+= install/nfs-server-edit.scr
+IMAGES_EN+= install/ntp-config.scr
+IMAGES_EN+= install/options.scr
+IMAGES_EN+= install/pkg-cat.scr
+IMAGES_EN+= install/pkg-confirm.scr
+IMAGES_EN+= install/pkg-install.scr
+IMAGES_EN+= install/pkg-sel.scr
+IMAGES_EN+= install/probstart.scr
+IMAGES_EN+= install/routed.scr
+IMAGES_EN+= install/security.scr
+IMAGES_EN+= install/sysinstall-exit.scr
+IMAGES_EN+= install/timezone1.scr
+IMAGES_EN+= install/timezone2.scr
+IMAGES_EN+= install/timezone3.scr
+IMAGES_EN+= install/userconfig.scr
+IMAGES_EN+= install/userconfig2.scr
+IMAGES_EN+= install/xf86setup.scr
+IMAGES_EN+= mail/mutt1.scr
+IMAGES_EN+= mail/mutt2.scr
+IMAGES_EN+= mail/mutt3.scr
+IMAGES_EN+= mail/pine1.scr
+IMAGES_EN+= mail/pine2.scr
+IMAGES_EN+= mail/pine3.scr
+IMAGES_EN+= mail/pine4.scr
+IMAGES_EN+= mail/pine5.scr
+
+IMAGES_EN+= install/example-dir1.eps
+IMAGES_EN+= install/example-dir2.eps
+IMAGES_EN+= install/example-dir3.eps
+IMAGES_EN+= install/example-dir4.eps
+IMAGES_EN+= install/example-dir5.eps
+IMAGES_EN+= security/ipsec-network.pic
+IMAGES_EN+= security/ipsec-crypt-pkt.pic
+IMAGES_EN+= security/ipsec-encap-pkt.pic
+IMAGES_EN+= security/ipsec-out-pkt.pic
+IMAGES_EN+= vinum/vinum-concat.pic
+IMAGES_EN+= vinum/vinum-mirrored-vol.pic
+IMAGES_EN+= vinum/vinum-raid10-vol.pic
+IMAGES_EN+= vinum/vinum-raid5-org.pic
+IMAGES_EN+= vinum/vinum-simple-vol.pic
+IMAGES_EN+= vinum/vinum-striped-vol.pic
+IMAGES_EN+= vinum/vinum-striped.pic
+
+# Images from the cross-document image library
+IMAGES_LIB=  callouts/1.png
+IMAGES_LIB+= callouts/2.png
+IMAGES_LIB+= callouts/3.png
+IMAGES_LIB+= callouts/4.png
+IMAGES_LIB+= callouts/5.png
+IMAGES_LIB+= callouts/6.png
+IMAGES_LIB+= callouts/7.png
+IMAGES_LIB+= callouts/8.png
+IMAGES_LIB+= callouts/9.png
+IMAGES_LIB+= callouts/10.png
+
+# 
+# SRCS lists the individual SGML files that make up the document. Changes
+# to any of these files will force a rebuild
+#
+
+# SGML content
+SRCS+= audit/chapter.sgml
+SRCS+= book.sgml
+SRCS+= colophon.sgml
+SRCS+= freebsd-glossary.sgml
+SRCS+= advanced-networking/chapter.sgml
+SRCS+= basics/chapter.sgml
+SRCS+= bibliography/chapter.sgml
+SRCS+= boot/chapter.sgml
+SRCS+= config/chapter.sgml
+SRCS+= cutting-edge/chapter.sgml
+SRCS+= desktop/chapter.sgml
+SRCS+= disks/chapter.sgml
+SRCS+= eresources/chapter.sgml
+SRCS+= firewalls/chapter.sgml
+SRCS+= geom/chapter.sgml
+SRCS+= install/chapter.sgml
+SRCS+= introduction/chapter.sgml
+SRCS+= kernelconfig/chapter.sgml
+SRCS+= l10n/chapter.sgml
+SRCS+= linuxemu/chapter.sgml
+SRCS+= mac/chapter.sgml
+SRCS+= mail/chapter.sgml
+SRCS+= mirrors/chapter.sgml
+SRCS+= multimedia/chapter.sgml
+SRCS+= network-servers/chapter.sgml
+SRCS+= pgpkeys/chapter.sgml
+SRCS+= ports/chapter.sgml
+SRCS+= ppp-and-slip/chapter.sgml
+SRCS+= preface/preface.sgml
+SRCS+= printing/chapter.sgml
+SRCS+= security/chapter.sgml
+SRCS+= serialcomms/chapter.sgml
+SRCS+= users/chapter.sgml
+SRCS+= vinum/chapter.sgml
+SRCS+= x11/chapter.sgml
+
+# Entities
+SRCS+= chapters.ent 
+
+SYMLINKS=	${DESTDIR} index.html handbook.html
+
+# Turn on all the chapters.
+CHAPTERS?= ${SRCS:M*chapter.sgml}
+
+SGMLFLAGS+= ${CHAPTERS:S/\/chapter.sgml//:S/^/-i chap./}
+SGMLFLAGS+= -i chap.freebsd-glossary
+
+pgpkeyring: pgpkeys/chapter.sgml
+	@${JADE} -V nochunks ${OTHERFLAGS} ${JADEOPTS} -d ${DSLPGP} -t sgml ${MASTERDOC}
+
+#
+# Handbook-specific variables
+#
+.if defined(WITH_PGPKEYS)
+JADEFLAGS+=	-V withpgpkeys
+.endif
+
+URL_RELPREFIX?=	../../../..
+DOC_PREFIX?=	${.CURDIR}/../../..
+
+#
+# rules generating lists of mirror site from XML database.
+#
+XMLDOCS=	mirrors-ftp:::mirrors.sgml.ftp.inc.tmp \
+		mirrors-cvsup:::mirrors.sgml.cvsup.inc.tmp \
+		eresources:::eresources.sgml.www.inc.tmp
+DEPENDSET.DEFAULT=	transtable mirror
+XSLT.DEFAULT=		${XSL_MIRRORS}
+XML.DEFAULT=		${XML_MIRRORS}
+NO_TIDY.DEFAULT=	yes
+
+PARAMS.mirrors-ftp+=	--param 'type' "'ftp'" \
+			--param 'proto' "'ftp'" \
+			--param 'target' "'handbook/mirrors/chapter.sgml'"
+PARAMS.mirrors-cvsup+=	--param 'type' "'cvsup'" \
+			--param 'proto' "'cvsup'" \
+			--param 'target' "'handbook/mirrors/chapter.sgml'"
+PARAMS.eresources+=	--param 'type' "'www'" \
+			--param 'proto' "'http'" \
+			--param 'target' "'handbook/eresources/chapter.sgml'"
+
+SRCS+=		mirrors.sgml.ftp.inc \
+		mirrors.sgml.cvsup.inc \
+		eresources.sgml.www.inc
+
+CLEANFILES+=	mirrors.sgml.ftp.inc mirrors.sgml.ftp.inc.tmp \
+		mirrors.sgml.cvsup.inc mirrors.sgml.cvsup.inc.tmp \
+		eresources.sgml.www.inc eresources.sgml.www.inc.tmp
+
+.include "${DOC_PREFIX}/share/mk/doc.project.mk"
+
+.for p in ftp cvsup
+mirrors.sgml.${p}.inc: mirrors.sgml.${p}.inc.tmp
+	${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2></\1>,;s,</anchor>,,'\
+	    < $@.tmp > $@ || (${RM} -f $@ && false)
+.endfor
+
+eresources.sgml.www.inc: eresources.sgml.www.inc.tmp
+	${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2></\1>,;s,</anchor>,,'\
+	    < $@.tmp > $@ || (${RM} -f $@ && false)
diff --git a/pl_PL.ISO8859-2/books/handbook/advanced-networking/Makefile b/pl_PL.ISO8859-2/books/handbook/advanced-networking/Makefile
new file mode 100644
index 0000000000..eb62e4335c
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/advanced-networking/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	advanced-networking/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/advanced-networking/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/advanced-networking/chapter.sgml
new file mode 100644
index 0000000000..e8d3947de3
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/advanced-networking/chapter.sgml
@@ -0,0 +1,4707 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="advanced-networking">
+  <title>Advanced Networking</title>
+
+  <sect1 id="advanced-networking-synopsis">
+    <title>Synopsis</title>
+
+    <para>This chapter will cover a number of advanced networking
+      topics.</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 set up IEEE 802.11 and &bluetooth; devices.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to make FreeBSD act as a bridge.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up network booting on a diskless machine.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up network address translation.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to connect two computers via PLIP.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up IPv6 on a FreeBSD machine.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure ATM.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand the basics of the <filename>/etc/rc</filename> scripts.</para>
+      </listitem>
+
+      <listitem>
+	<para>Be familiar with basic network terminology.</para>
+      </listitem>
+
+      <listitem>
+        <para>Know how to configure and install a new FreeBSD kernel
+          (<xref linkend="kernelconfig">).</para>
+      </listitem>
+
+      <listitem>
+      <para>Know how to install additional third-party
+        software (<xref linkend="ports">).</para>
+      </listitem>
+
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="network-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="network-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 <hostid role="ipaddr">224</hostid>) 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" pgwide="1">
+	<tgroup cols="2">
+	  <colspec colwidth="1*">
+	  <colspec colwidth="4*">
+
+	  <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="network-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>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="advanced-networking/net-routing">
+	</imageobject>
+
+	<textobject>
+	  <literallayout class="monospaced">
+[Local2]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
+      </literallayout>
+	</textobject>
+      </mediaobject>
+
+      <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" pgwide="1">
+	<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>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" pgwide="1">
+	<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>
+
+      <para>You can easily define the default route via the
+	<filename>/etc/rc.conf</filename> file.  In our example, on the
+	<hostid>Local2</hostid> machine, we added the following line
+	in <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>defaultrouter="10.20.30.1"</programlisting>
+
+      <para>It is also possible to do it directly from the command
+	line with the &man.route.8; command:</para>
+
+      <screen>&prompt.root; <userinput>route add default 10.20.30.1</userinput></screen>
+
+      <para>For more information on manual manipulation of network
+	routing tables, consult &man.route.8; manual page.</para>
+    </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.  See the next section for more details on how
+	to do this.</para>
+    </sect2>
+
+    <sect2 id="network-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.  Support for BGP v4, OSPF v2, and other
+	sophisticated routing protocols is available with the
+	<filename role="package">net/zebra</filename> package.
+	Commercial products such as <application>&gated;</application> are also available for more
+	complex network routing solutions.</para>
+
+<indexterm><primary>BGP</primary></indexterm>
+<indexterm><primary>RIP</primary></indexterm>
+<indexterm><primary>OSPF</primary></indexterm>
+    </sect2>
+
+    <sect2>
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Al</firstname>
+	    <surname>Hoang</surname>
+	    <contrib>Contributed by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+      <!-- Feb 2004 -->
+      <title>Setting Up Static Routes</title>
+
+      <sect3>
+	<title>Manual Configuration</title>
+
+	<para>Let us assume we have a network as follows:</para>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="advanced-networking/static-routes">
+	  </imageobject>
+
+	  <textobject>
+	<literallayout class="monospaced">
+    INTERNET
+      | (10.0.0.1/24) Default Router to Internet
+      |
+      |Interface xl0
+      |10.0.0.10/24
+   +------+
+   |      | RouterA
+   |      | (FreeBSD gateway)
+   +------+
+      | Interface xl1
+      | 192.168.1.1/24
+      |
+  +--------------------------------+
+   Internal Net 1      | 192.168.1.2/24
+                       |
+                   +------+
+                   |      | RouterB
+                   |      |
+                   +------+
+                       | 192.168.2.1/24
+                       |
+                     Internal Net 2
+	</literallayout>
+	  </textobject>
+	</mediaobject>
+
+	<para>In this scenario, <hostid>RouterA</hostid> is our &os;
+	  machine that is acting as a router to the rest of the
+	  Internet.  It has a default route set to <hostid
+	  role="ipaddr">10.0.0.1</hostid> which allows it to connect
+	  with the outside world.  We will assume that
+	  <hostid>RouterB</hostid> is already configured properly and
+	  knows how to get wherever it needs to go.  (This is simple
+	  in this picture.  Just add a default route on
+	  <hostid>RouterB</hostid> using <hostid
+	  role="ipaddr">192.168.1.1</hostid> as the gateway.)</para>
+
+	<para>If we look at the routing table for
+	  <hostid>RouterA</hostid> we would see something like the
+	  following:</para>
+
+	<screen>&prompt.user; <userinput>netstat -nr</userinput>
+Routing tables
+
+Internet:
+Destination        Gateway            Flags    Refs      Use  Netif  Expire
+default            10.0.0.1           UGS         0    49378    xl0
+127.0.0.1          127.0.0.1          UH          0        6    lo0
+10.0.0/24          link#1             UC          0        0    xl0
+192.168.1/24       link#2             UC          0        0    xl1</screen>
+
+	<para>With the current routing table  <hostid>RouterA</hostid>
+	  will not be able to reach our Internal Net 2.  It does not
+	  have a route for <hostid
+	  role="ipaddr">192.168.2.0/24</hostid>.  One way to alleviate
+	  this is to manually add the route.  The following command
+	  would add the Internal Net 2 network to
+	  <hostid>RouterA</hostid>'s routing table using <hostid
+	  role="ipaddr">192.168.1.2</hostid> as the next hop:</para>
+
+	<screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>
+
+	<para>Now <hostid>RouterA</hostid> can reach any hosts on the
+	  <hostid role="ipaddr">192.168.2.0/24</hostid>
+	  network.</para>
+      </sect3>
+
+      <sect3>
+	<title>Persistent Configuration</title>
+
+	<para>The above example is perfect for configuring a static
+	  route on a running system.  However, one problem is that the
+	  routing information will not persist if you reboot your &os;
+	  machine.  The way to handle the addition of a static route
+	  is to put it in your <filename>/etc/rc.conf</filename>
+	  file:</para>
+
+	<programlisting># Add Internal Net 2 as a static route
+static_routes="internalnet2"
+route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting>
+
+	<para>The <literal>static_routes</literal> configuration
+	  variable is a list of strings separated by a space.  Each
+	  string references to a route name.  In our above example we
+	  only have one string in <literal>static_routes</literal>.
+	  This string is <replaceable>internalnet2</replaceable>.  We
+	  then add a configuration variable called
+	  <literal>route_<replaceable>internalnet2</replaceable></literal>
+	  where we put all of the configuration parameters we would
+	  give to the &man.route.8; command.  For our example above we
+	  would have used the command:</para>
+
+	  <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>
+
+	  <para>so we need <literal>"-net 192.168.2.0/24 192.168.1.2"</literal>.</para>
+
+	<para>As said above, we can have more than one string in
+	  <literal>static_routes</literal>.  This allows us to
+	  create multiple static routes.  The following lines shows
+	  an example of adding static routes for the <hostid
+	  role="ipaddr">192.168.0.0/24</hostid> and <hostid
+	  role="ipaddr">192.168.1.0/24</hostid> networks on an imaginary
+	  router:</para>
+
+        <programlisting>static_routes="net1 net2"
+route_net1="-net 192.168.0.0/24 192.168.0.1"
+route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
+      </sect3>
+    </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>
+
+    <sect2>
+      <title>Multicast Routing</title>
+      <indexterm>
+	<primary>multicast routing</primary>
+      </indexterm>
+      <indexterm>
+	<primary>kernel options</primary>
+	<secondary>MROUTING</secondary>
+      </indexterm>
+      <para>FreeBSD supports both multicast applications and multicast
+	routing natively.  Multicast applications do not require any
+	special configuration of FreeBSD; applications will generally
+	run out of the box.  Multicast routing
+	requires that support be compiled into the kernel:</para>
+
+      <programlisting>options MROUTING</programlisting>
+
+      <para>In addition, the multicast routing daemon, &man.mrouted.8;
+	must be configured to set up tunnels and <acronym>DVMRP</acronym> via
+	<filename>/etc/mrouted.conf</filename>.  More details on
+	multicast configuration may be found in the manual page for
+	&man.mrouted.8;.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-wireless">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <othername>Loader</othername>
+	</author>
+
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Fonvieille</surname>
+	</author>
+
+	<author>
+	  <firstname>Murray</firstname>
+	  <surname>Stokely</surname>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Wireless Networking</title>
+
+    <indexterm><primary>wireless networking</primary></indexterm>
+    <indexterm>
+      <primary>802.11</primary>
+      <see>wireless networking</see>
+    </indexterm>
+
+    <sect2>
+      <title>Wireless Networking Basics</title>
+
+      <para>Most wireless networks are based on the IEEE 802.11
+	standards.  A basic wireless network consists of multiple
+	stations communicating with radios that broadcast in either
+	the 2.4GHz or 5GHz band (though this varies according to the
+	locale and is also changing to enable communication in the
+	2.3GHz and 4.9GHz ranges).</para>
+
+      <para>802.11 networks are organized in two ways: in
+	<emphasis>infrastructure mode</emphasis> one station acts as a
+	master with all the other stations associating to it; the
+	network is known as a BSS and the master station is termed an
+	access point (AP).  In a BSS all communication passes through
+	the AP; even when one station wants to communicate with
+	another wireless station messages must go through the AP.  In
+	the second form of network there is no master and stations
+	communicate directly.  This form of network is termed an IBSS
+	and is commonly known as an <emphasis>ad-hoc
+	network</emphasis>.</para>
+
+      <para>802.11 networks were first deployed in the 2.4GHz band
+	using protocols defined by the IEEE 802.11 and 802.11b
+	standard.  These specifications include the operating
+	frequencies, MAC layer characteristics including framing and
+	transmission rates (communication can be done at various
+	rates).  Later the 802.11a standard defined operation in the
+	5GHz band, including different signalling mechanisms and
+	higher transmission rates.  Still later the 802.11g standard
+	was defined to enable use of 802.11a signalling and
+	transmission mechanisms in the 2.4GHz band in such a way as to
+	be backwards compatible with 802.11b networks.</para>
+
+      <para>Separate from the underlying transmission techniques
+	802.11 networks have a variety of security mechanisms.  The
+	original 802.11 specifications defined a simple security
+	protocol called WEP. This protocol uses a fixed pre-shared key
+	and the RC4 cryptographic cipher to encode data transmitted on
+	a network.  Stations must all agree on the fixed key in order
+	to communicate.  This scheme was shown to be easily broken and
+	is now rarely used except to discourage transient users from
+	joining networks.  Current security practice is given by the
+	IEEE 802.11i specification that defines new cryptographic
+	ciphers and an additional protocol to authenticate stations to
+	an access point and exchange keys for doing data
+	communication.  Further, cryptographic keys are periodically
+	refreshed and there are mechanisms for detecting intrusion
+	attempts (and for countering intrusion attempts).  Another
+	security protocol specification commonly used in wireless
+	networks is termed WPA.  This was a precursor to 802.11i
+	defined by an industry group as an interim measure while
+	waiting for 802.11i to be ratified.  WPA specifies a subset of
+	the requirements found in 802.11i and is designed for
+	implementation on legacy hardware.  Specifically WPA requires
+	only the TKIP cipher that is derived from the original WEP
+	cipher.  802.11i permits use of TKIP but also requires support
+	for a stronger cipher, AES-CCM, for encrypting data.  (The AES
+	cipher was not required in WPA because it was deemed too
+	computationally costly to be implemented on legacy
+	hardware.)</para>
+
+      <para>Other than the above protocol standards the other
+	important standard to be aware of is 802.11e.  This defines
+	protocols for deploying multi-media applications such as
+	streaming video and voice over IP (VoIP) in an 802.11 network.
+	Like 802.11i, 802.11e also has a precursor specification
+	termed WME (later renamed WMM) that has been defined by an
+	industry group as a subset of 802.11e that can be deployed now
+	to enable multi-media applications while waiting for the final
+	ratification of 802.11e.  The most important thing to know
+	about 802.11e and WME/WMM is that it enables prioritized
+	traffic use of a wireless network through Quality of Service
+	(QoS) protocols and enhanced media access protocols.  Proper
+	implementation of these protocols enable high speed bursting
+	of data and prioritized traffic flow.</para>
+
+      <para>Since the 6.0 version, &os; supports networks that operate
+	using 802.11a, 802.11b, and 802.11g.  The WPA and 802.11i
+	security protocols are likewise supported (in conjunction with
+	any of 11a, 11b, and 11g) and QoS and traffic prioritization
+	required by the WME/WMM protocols are supported for a limited
+	set of wireless devices.</para>
+    </sect2>
+
+    <sect2 id="network-wireless-basic">
+      <title>Basic Setup</title>
+
+      <sect3>
+	<title>Kernel Configuration</title>
+
+	<para>To use wireless networking you need a wireless
+	  networking card and to configure the kernel with the
+	  appropriate wireless networking support.  The latter is
+	  separated into multiple modules so that you only need to
+	  configure the software you are actually going to use.</para>
+
+	<para>The first thing you need is a wireless device.  The most
+	  commonly used devices are those that use parts made by
+	  Atheros.  These devices are supported by the &man.ath.4;
+	  driver and require the following line to be added to the
+	  <filename>/boot/loader.conf</filename> file:</para>
+
+	<programlisting>if_ath_load="YES"</programlisting>
+
+	<para>The Atheros driver is split up into three separate
+	  pieces: the driver proper (&man.ath.4;), the hardware
+	  support layer that handles chip-specific functions
+	  (&man.ath.hal.4;), and an algorithm for selecting which of
+	  several possible rates for transmitting frames
+	  (ath_rate_sample here).  When you load this support as
+	  modules these dependencies are automatically handled for
+	  you.  If instead of an Atheros device you had another device
+	  you would select the module for that device; e.g.:</para>
+
+	<programlisting>if_wi_load="YES"</programlisting>
+
+	<para>for devices based on the Intersil Prism parts
+	  (&man.wi.4; driver).</para>
+
+	<note>
+	  <para>In the rest of this document, we will use an
+	    &man.ath.4; device, the device name in the examples must
+	    be changed according to your configuration.  A list of
+	    available wireless drivers can be found at the beginning
+	    of the &man.wlan.4; manual page.  If a native &os; driver
+	    for your wireless device does not exist, it may be
+	    possible to directly use the &windows; driver with the
+	    help of the <link
+	    linkend="config-network-ndis">NDIS</link> driver
+	    wrapper.</para>
+	</note>
+
+	<para>With a device driver configured you need to also bring
+	  in the 802.11 networking support required by the driver.
+	  For the &man.ath.4; driver this is at least the &man.wlan.4;
+	  module; this module is automatically loaded with the
+	  wireless device driver.  With that you will need the modules
+	  that implement cryptographic support for the security
+	  protocols you intend to use.  These are intended to be
+	  dynamically loaded on demand by the &man.wlan.4; module but
+	  for now they must be manually configured.  The following
+	  modules are available: &man.wlan.wep.4;, &man.wlan.ccmp.4;
+	  and &man.wlan.tkip.4;.  Both &man.wlan.ccmp.4; and
+	  &man.wlan.tkip.4; drivers are only needed if you intend to
+	  use the WPA and/or 802.11i security protocols.  If your
+	  network is to run totally open (i.e., with no encryption)
+	  then you do not even need the &man.wlan.wep.4; support.  To
+	  load these modules at boot time, add the following lines to
+	  <filename>/boot/loader.conf</filename>:</para>
+
+	<programlisting>wlan_wep_load="YES"
+wlan_ccmp_load="YES"
+wlan_tkip_load="YES"</programlisting>
+
+	<para>With this information in the system bootstrap
+	  configuration file (i.e.,
+	  <filename>/boot/loader.conf</filename>), you have to reboot
+	  your &os; box.  If you do not want to reboot your machine
+	  for the moment, you can just load the modules by hand using
+	  &man.kldload.8;.</para>
+
+	<note>
+	  <para>If you do not want to use modules, it is possible to
+	    compile these drivers into the kernel by adding the
+	    following lines to your kernel configuration file:</para>
+
+	  <programlisting>device ath               # Atheros IEEE 802.11 wireless network driver
+device ath_hal           # Atheros Hardware Access Layer
+device ath_rate_sample   # John Bicket's SampleRate control algorithm.
+device wlan              # 802.11 support (Required)
+device wlan_wep          # WEP crypto support for 802.11 devices
+device wlan_ccmp         # AES-CCMP crypto support for 802.11 devices
+device wlan_tkip         # TKIP and Michael crypto support for 802.11 devices</programlisting>
+
+	  <para>With this information in the kernel configuration
+	    file, recompile the kernel and reboot your &os;
+	    machine.</para>
+	</note>
+
+	<para>When the system is up, we could find some information
+	  about the wireless device in the boot messages, like
+	  this:</para>
+
+	<screen>ath0: &lt;Atheros 5212&gt; mem 0xff9f0000-0xff9fffff irq 17 at device 2.0 on pci2
+ath0: Ethernet address: 00:11:95:d5:43:62
+ath0: mac 7.9 phy 4.5 radio 5.6</screen>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Infrastructure Mode</title>
+
+      <para>The infrastructure mode or BSS mode is the mode that is
+	typically used.  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.  Wireless clients connect to the wireless access
+	points.</para>
+
+      <sect3>
+	<title>&os; Clients</title>
+
+	<sect4>
+	  <title>How to Find Access Points</title>
+
+	  <para>To scan for networks, use the
+	    <command>ifconfig</command> command.  This request may
+	    take a few moments to complete as it requires that the
+	    system switches to each available wireless frequency and
+	    probes for available access points.  Only the super-user
+	    can initiate such a scan:</para>
+
+	  <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput>
+SSID            BSSID              CHAN RATE  S:N   INT CAPS
+dlinkap         00:13:46:49:41:76    6   54M 29:0   100 EPS  WPA WME
+freebsdap       00:11:95:c3:0d:ac    1   54M 22:0   100 EPS  WPA</screen>
+
+	  <note>
+	    <para>You must mark the interface <option>up</option>
+	      before you can scan.  Subsequent scan requests do not
+	      require you to mark the interface up again.</para>
+	  </note>
+
+	  <para>The output of a scan request lists each BSS/IBSS
+	    network found.  Beside the name of the network,
+	    <literal>SSID</literal>, we find the
+	    <literal>BSSID</literal> which is the MAC address of the
+	    access point.  The <literal>CAPS</literal> field
+	    identifies the type of each network and the capabilities
+	    of the stations operating there:</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><literal>E</literal></term>
+
+	      <listitem>
+		<para>Extended Service Set (ESS).  Indicates that the
+		  station is part of an infrastructure network (in
+		  contrast to an IBSS/ad-hoc network).</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>I</literal></term>
+
+	      <listitem>
+		<para>IBSS/ad-hoc network.  Indicates that the station
+		  is part of an ad-hoc network (in contrast to an ESS
+		  network).</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>P</literal></term>
+
+	      <listitem>
+		<para>Privacy.  Data confidentiality is required for
+		  all data frames exchanged within the BSS.  This means
+		  that this BSS requires the station to use
+		  cryptographic means such as WEP, TKIP or AES-CCMP to
+		  encrypt/decrypt data frames being exchanged with
+		  others.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>S</literal></term>
+
+	      <listitem>
+		<para>Short Preamble.  Indicates that the network is
+		  using short preambles (defined in 802.11b High
+		  Rate/DSSS PHY, short preamble utilizes a 56 bit sync
+		  field in contrast to a 128 bit field used in long
+		  preamble mode).</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>s</literal></term>
+
+	      <listitem>
+		<para>Short slot time.  Indicates that the 802.11g
+		  network is using a short slot time because there are
+		  no legacy (802.11b) stations present.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+
+	  <para>One can also display the current list of known
+	    networks with:</para>
+
+	  <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> list scan</userinput></screen>
+
+	  <para>This information may be updated automatically by the
+	    adapter or manually with a <option>scan</option> request.
+	    Old data is automatically removed from the cache, so over
+	    time this list may shrink unless more scans are
+	    done.</para>
+	</sect4>
+
+	<sect4>
+	  <title>Basic Settings</title>
+
+	  <para>This section provides a simple example of how to make
+	    the wireless network adapter work in &os; without
+	    encryption.  After you are familiar with these concepts,
+	    we strongly recommend using <link
+	    linkend="network-wireless-wpa">WPA</link> to set up your
+	    wireless network.</para>
+
+	  <para>There are three basic steps to configure a wireless
+	    network: selecting an access point, authenticating your
+	    station, and configuring an IP address.  The following
+	    sections discuss each step.</para>
+
+	  <sect5>
+	    <title>Selecting an Access Point</title>
+
+	    <para>Most of time it is sufficient to let the system
+	      choose an access point using the builtin heuristics.
+	      This is the default behaviour when you mark an interface
+	      up or otherwise configure an interface by listing it in
+	      <filename>/etc/rc.conf</filename>, e.g.:</para>
+
+	    <programlisting>ifconfig_ath0="DHCP"</programlisting>
+
+	    <para>If there are multiple access points and you want to
+	      select a specific one, you can select it by its
+	      SSID:</para>
+
+	    <programlisting>ifconfig_ath0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>
+
+	    <para>In an environment where there are multiple access
+	      points with the same SSID (often done to simplify
+	      roaming) it may be necessary to associate to one
+	      specific device.  In this case you can also specify the
+	      BSSID of the access point (you can also leave off the
+	      SSID):</para>
+
+	    <programlisting>ifconfig_ath0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting>
+
+	    <para>There are other ways to constrain the choice of an
+	      access point such as limiting the set of frequencies the
+	      system will scan on.  This may be useful if you have a
+	      multi-band wireless card as scanning all the possible
+	      channels can be time-consuming.  To limit operation to a
+	      specific band you can use the <option>mode</option>
+	      parameter; e.g.:</para>
+
+	    <programlisting>ifconfig_ath0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>
+
+	    <para>will force the card to operate in 802.11g which is
+	      defined only for 2.4GHz frequencies so any 5GHz channels
+	      will not be considered.  Other ways to do this are the
+	      <option>channel</option> parameter, to lock operation to
+	      one specific frequency, and the
+	      <option>chanlist</option> parameter, to specify a list
+	      of channels for scanning.  More information about these
+	      parameters can be found in the &man.ifconfig.8; manual
+	      page.</para>
+	  </sect5>
+
+	  <sect5>
+	    <title>Authentication</title>
+
+	    <para>Once you have selected an access point your station
+	      needs to authenticate before it can pass data.
+	      Authentication can happen in several ways.  The most
+	      common scheme used is termed open authentication and
+	      allows any station to join the network and communicate.
+	      This is the authentication you should use for test
+	      purpose the first time you set up a wireless network.
+	      Other schemes require cryptographic handshakes be
+	      completed before data traffic can flow; either using
+	      pre-shared keys or secrets, or more complex schemes that
+	      involve backend services such as RADIUS.  Most users
+	      will use open authentication which is the default
+	      setting.  Next most common setup is WPA-PSK, also known
+	      as WPA Personal, which is described <link
+	      linkend="network-wireless-wpa-wpa-psk">below</link>.</para>
+
+	    <note>
+	      <para>If you have an &apple; &airport; Extreme base
+		station for an access point you may need to configure
+		shared-key authentication together with a WEP key.
+		This can be done in the
+		<filename>/etc/rc.conf</filename> file or using the
+		&man.wpa.supplicant.8; program.  If you have a single
+		&airport; base station you can setup access with
+		something like:</para>
+
+	      <programlisting>ifconfig_ath0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting>
+
+	      <para>In general shared key authentication is to be
+		avoided because it uses the WEP key material in a
+		highly-constrained manner making it even easier to
+		crack the key.  If WEP must be used (e.g., for
+		compatibility with legacy devices) it is better to use
+		WEP with <literal>open</literal> authentication.  More
+		information regarding WEP can be found in the <xref
+		linkend="network-wireless-wep">.</para>
+	    </note>
+	  </sect5>
+
+	  <sect5>
+	    <title>Getting an IP Address with DHCP</title>
+
+	    <para>Once you have selected an access point and set the
+	      authentication parameters, you will have to get an IP
+	      address to communicate.  Most of time you will obtain
+	      your wireless IP address via DHCP.  To achieve that,
+	      simply edit <filename>/etc/rc.conf</filename> and add
+	      <literal>DHCP</literal> to the configuration for your
+	      device as shown in various examples above:</para>
+
+	    <programlisting>ifconfig_ath0="DHCP"</programlisting>
+
+	    <para>At this point, you are ready to bring up the
+	      wireless interface:</para>
+
+	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput></screen>
+
+	    <para>Once the interface is running, use
+	      <command>ifconfig</command> to see the status of the
+	      interface <devicename>ath0</devicename>:</para>
+
+	    <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+        inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+        inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
+        ether 00:11:95:d5:43:62
+        media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps)
+        status: associated
+        ssid dlinkap channel 6 bssid 00:13:46:49:41:76
+        authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen>
+
+	    <para>The <literal>status: associated</literal> means you
+	      are connected to the wireless network (to the
+	      <literal>dlinkap</literal> network in our case).  The
+	      <literal>bssid 00:13:46:49:41:76</literal> part is the
+	      MAC address of your access point; the
+	      <literal>authmode</literal> line informs you that the
+	      communication is not encrypted
+	      (<literal>OPEN</literal>).</para>
+	  </sect5>
+
+	  <sect5>
+	    <title>Static IP Address</title>
+
+	    <para>In the case you cannot obtain an IP address from a
+	      DHCP server, you can set a fixed IP address.  Replace
+	      the <literal>DHCP</literal> keyword shown above with the
+	      address information.  Be sure to retain any other
+	      parameters you have set up for selecting an access
+	      point:</para>
+
+	    <programlisting>ifconfig_ath0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting>
+	  </sect5>
+
+	<sect4 id="network-wireless-wpa">
+	  <title>WPA</title>
+
+	  <para>WPA (Wi-Fi Protected Access) is a security protocol
+	    used together with 802.11 networks to address the lack of
+	    proper authentication and the weakness of <link
+	    linkend="network-wireless-wep">WEP</link>.  WPA leverages
+	    the 802.1X authentication protocol and uses one of several
+	    ciphers instead of WEP for data integrity.  The only
+	    cipher required by WPA is TKIP (Temporary Key Integrity
+	    Protocol) which is a cipher that extends the basic RC4
+	    cipher used by WEP by adding integrity checking, tamper
+	    detection, and measures for responding to any detected
+	    intrusions.  TKIP is designed to work on legacy hardware
+	    with only software modification; it represents a
+	    compromise that improves security but is still not
+	    entirely immune to attack.  WPA also specifies the
+	    AES-CCMP cipher as an alternative to TKIP and that is
+	    preferred when possible; for this specification the term
+	    WPA2 (or RSN) is commonly used.</para>
+
+	  <para>WPA defines authentication and encryption protocols.
+	    Authentication is most commonly done using one of two
+	    techniques: by 802.1X and a backend authentication service
+	    such as RADIUS, or by a minimal handshake between the
+	    station and the access point using a pre-shared secret.
+	    The former is commonly termed WPA Enterprise with the
+	    latter known as WPA Personal.  Since most people will not
+	    set up a RADIUS backend server for wireless network,
+	    WPA-PSK is by far the most commonly encountered
+	    configuration for WPA.</para>
+
+	  <para>The control of the wireless connection and the
+	    authentication (key negotiation or authentication with a
+	    server) is done with the &man.wpa.supplicant.8; utility.
+	    This program requires a configuration file,
+	    <filename>/etc/wpa_supplicant.conf</filename>, to run.
+	    More information regarding this file can be found in the
+	    &man.wpa.supplicant.conf.5; manual page.</para>
+
+	  <sect5 id="network-wireless-wpa-wpa-psk">
+	    <title>WPA-PSK</title>
+
+	    <para>WPA-PSK also known as WPA-Personal is based on a
+	      pre-shared key (PSK) generated from a given password and
+	      that will be used as the master key in the wireless
+	      network.  This means every wireless user will share the
+	      same key.  WPA-PSK is intended for small networks where
+	      the use of an authentication server is not possible or
+	      desired.</para>
+
+	    <warning>
+	      <para>Always use strong passwords that are
+		sufficiently long and made from a rich alphabet so
+		they will not be guessed and/or attacked.</para>
+	    </warning>
+
+	    <para>The first step is the configuration of the
+	      <filename>/etc/wpa_supplicant.conf</filename> file with
+	      the SSID and the pre-shared key of your network:</para>
+
+	    <programlisting>network={
+  ssid="freebsdap"
+  psk="freebsdmall"
+}</programlisting>
+
+	    <para>Then, in <filename>/etc/rc.conf</filename>, we
+	      indicate that the wireless device configuration will be
+	      done with WPA and the IP address will be obtained with
+	      DHCP:</para>
+
+	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>
+
+	    <para>Then, we can bring up the interface:</para>
+
+	    <screen>&prompt.root; <userinput><filename>/etc/rc.d/netif</filename> start</userinput>
+Starting wpa_supplicant.
+DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 5
+DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 6
+DHCPOFFER from 192.168.0.1
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPACK from 192.168.0.1
+bound to 192.168.0.254 -- renewal in 300 seconds.
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
+      ether 00:11:95:d5:43:62
+      media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps)
+      status: associated
+      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
+      authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
+      protmode CTS roaming MANUAL bintval 100</screen>
+
+	    <para>Or you can try to configure it manually using the
+	      same <filename>/etc/wpa_supplicant.conf</filename> <link
+	      linkend="network-wireless-wpa-wpa-psk">above</link>, and
+	      run:</para>
+
+	    <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>ath0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
+Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz)
+Associated with 00:11:95:c3:0d:ac
+WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=TKIP GTK=TKIP]</screen>
+
+	    <para>The next operation is the launch of the
+	      <command>dhclient</command> command to get the IP
+	      address from the DHCP server:</para>
+
+	    <screen>&prompt.root; <userinput>dhclient <replaceable>ath0</replaceable></userinput>
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPACK from 192.168.0.1
+bound to 192.168.0.254 -- renewal in 300 seconds.
+&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
+      ether 00:11:95:d5:43:62
+      media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/48Mbps)
+      status: associated
+      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
+      authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
+      protmode CTS roaming MANUAL bintval 100</screen>
+
+	    <note>
+	      <para>If the <filename>/etc/rc.conf</filename> is set up
+		with the line <literal>ifconfig_ath0="DHCP"</literal>
+		then it is no need to run the
+		<command>dhclient</command> command manually,
+		<command>dhclient</command> will be launched after
+		<command>wpa_supplicant</command> plumbs the
+		keys.</para>
+	    </note>
+
+	    <para>In the case where the use of DHCP is not possible,
+	      you can set a static IP address after
+	      <command>wpa_supplicant</command> has authenticated the
+	      station:</para>
+
+	    <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput>
+&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+      inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255
+      ether 00:11:95:d5:43:62
+      media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps)
+      status: associated
+      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
+      authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
+      protmode CTS roaming MANUAL bintval 100</screen>
+
+	    <para>When DHCP is not used, you also have to manually set
+	      up the default gateway and the nameserver:</para>
+
+	    <screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput>
+&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" &gt;&gt; /etc/resolv.conf</userinput></screen>
+	  </sect5>
+
+	  <sect5 id="network-wireless-wpa-eap-tls">
+	    <title>WPA with EAP-TLS</title>
+
+	    <para>The second way to use WPA is with an 802.1X backend
+	      authentication server, in this case WPA is called
+	      WPA-Enterprise to make difference with the less secure
+	      WPA-Personal with its pre-shared key.  The
+	      authentication in WPA-Enterprise is based on EAP
+	      (Extensible Authentication Protocol).</para>
+
+	    <para>EAP does not come with an encryption method, it was
+	      decided to embed EAP inside an encrypted tunnel.  Many
+	      types of EAP authentication methods have been designed,
+	      the most common methods are EAP-TLS, EAP-TTLS and
+	      EAP-PEAP.</para>
+
+	    <para>EAP-TLS (EAP with Transport Layer Security) is a
+	      very well-supported authentication protocol in the
+	      wireless world since it was the first EAP method to be
+	      certified by the <ulink
+	      url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>.
+	      EAP-TLS will require three certificates to run: the CA
+	      certificate (installed on all machines), the server
+	      certificate for your authentication server, and one
+	      client certificate for each wireless client.  In this
+	      EAP method, both authentication server and wireless
+	      client authenticate each other in presenting their
+	      respective certificates, and they verify that these
+	      certificates were signed by your organization's
+	      certificate authority (CA).</para>
+
+	    <para>As previously, the configuration is done via
+	      <filename>/etc/wpa_supplicant.conf</filename>:</para>
+
+	    <programlisting>network={
+  ssid="freebsdap" <co id="co-tls-ssid">
+  proto=RSN  <co id="co-tls-proto">
+  key_mgmt=WPA-EAP <co id="co-tls-kmgmt">
+  eap=TLS <co id="co-tls-eap">
+  identity="loader" <co id="co-tls-id">
+  ca_cert="/etc/certs/cacert.pem" <co id="co-tls-cacert">
+  client_cert="/etc/certs/clientcert.pem" <co id="co-tls-clientcert">
+  private_key="/etc/certs/clientkey.pem" <co id="co-tls-pkey">
+  private_key_passwd="freebsdmallclient" <co id="co-tls-pwd">
+}</programlisting>
+
+	    <calloutlist>
+	      <callout arearefs="co-tls-ssid">
+		<para>This field indicates the network name
+		  (SSID).</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-proto">
+		<para>Here, we use RSN (IEEE 802.11i) protocol, i.e.,
+		  WPA2.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-kmgmt">
+		<para>The <literal>key_mgmt</literal> line refers to
+		  the key management protocol we use.  In our case it
+		  is WPA using EAP authentication:
+		  <literal>WPA-EAP</literal>.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-eap">
+		<para>In this field, we mention the EAP method for our
+		  connection.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-id">
+		<para>The <literal>identity</literal> field contains
+		  the identity string for EAP.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-cacert">
+		<para>The <literal>ca_cert</literal> field indicates
+		  the pathname of the CA certificate file.  This file
+		  is needed to verify the server certificat.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-clientcert">
+		<para>The <literal>client_cert</literal> line gives
+		  the pathname to the client certificate file.  This
+		  certificate is unique to each wireless client of the
+		  network.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-pkey">
+		<para>The <literal>private_key</literal> field is the
+		  pathname to the client certificate private key
+		  file.</para>
+	      </callout>
+
+	      <callout arearefs="co-tls-pwd">
+		<para>The <literal>private_key</literal> field
+		  contains the passphrase for the private key.</para>
+	      </callout>
+	    </calloutlist>
+
+	    <para>Then add the following line to
+	      <filename>/etc/rc.conf</filename>:</para>
+
+	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>
+
+	    <para>The next step is to bring up the interface with the
+	      help of the <filename>rc.d</filename> facility:</para>
+
+	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
+Starting wpa_supplicant.
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPACK from 192.168.0.20
+bound to 192.168.0.254 -- renewal in 300 seconds.
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
+      ether 00:11:95:d5:43:62
+      media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
+      status: associated
+      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
+      authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
+      txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen>
+
+	    <para>As previously shown, it is also possible to bring up
+	      the interface manually with both
+	      <command>wpa_supplicant</command> and
+	      <command>ifconfig</command> commands.</para>
+	  </sect5>
+
+	  <sect5 id="network-wireless-wpa-eap-ttls">
+	    <title>WPA with EAP-TTLS</title>
+
+	    <para>With EAP-TLS both the authentication server and the
+	      client need a certificate, with EAP-TTLS (EAP-Tunneled
+	      Transport Layer Security) a client certificate is
+	      optional.  This method is close to what some secure web
+	      sites do , where the web server can create a secure SSL
+	      tunnel even if the visitors do not have client-side
+	      certificates.  EAP-TTLS will use the encrypted TLS
+	      tunnel for safe transport of the authentication
+	      data.</para>
+
+	    <para>The configuration is done via the
+	      <filename>/etc/wpa_supplicant.conf</filename>
+	      file:</para>
+
+	    <programlisting>network={
+  ssid="freebsdap"
+  proto=RSN
+  key_mgmt=WPA-EAP
+  eap=TTLS <co id="co-ttls-eap">
+  identity="test" <co id="co-ttls-id">
+  password="test" <co id="co-ttls-passwd">
+  ca_cert="/etc/certs/cacert.pem" <co id="co-ttls-cacert">
+  phase2="auth=MD5" <co id="co-ttls-pha2">
+}</programlisting>
+
+	    <calloutlist>
+	      <callout arearefs="co-ttls-eap">
+		<para>In this field, we mention the EAP method for our
+		  connection.</para>
+	      </callout>
+
+	      <callout arearefs="co-ttls-id">
+		<para>The <literal>identity</literal> field contains
+		  the identity string for EAP authentication inside
+		  the encrypted TLS tunnel.</para>
+	      </callout>
+
+	      <callout arearefs="co-ttls-passwd">
+		<para>The <literal>password</literal> field contains
+		  the passphrase for the EAP authentication.</para>
+	      </callout>
+
+	      <callout arearefs="co-ttls-cacert">
+		<para>The <literal>ca_cert</literal> field indicates
+		  the pathname of the CA certificate file.  This file
+		  is needed to verify the server certificat.</para>
+	      </callout>
+
+	      <callout arearefs="co-ttls-pha2">
+		<para>In this field, we mention the authentication
+		  method used in the encrypted TLS tunnel.  In our
+		  case, EAP with MD5-Challenge has been used.  The
+		  <quote>inner authentication</quote> phase is often
+		  called <quote>phase2</quote>.</para>
+	      </callout>
+	    </calloutlist>
+
+	    <para>You also have to add the following line to
+	      <filename>/etc/rc.conf</filename>:</para>
+
+	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>
+
+	    <para>The next step is to bring up the interface:</para>
+
+	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
+Starting wpa_supplicant.
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPACK from 192.168.0.20
+bound to 192.168.0.254 -- renewal in 300 seconds.
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
+      ether 00:11:95:d5:43:62
+      media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
+      status: associated
+      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
+      authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
+      txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen>
+	  </sect5>
+
+	  <sect5 id="network-wireless-wpa-eap-peap">
+	    <title>WPA with EAP-PEAP</title>
+
+	    <para>PEAP (Protected EAP) has been designed as an
+	      alternative to EAP-TTLS.  There are two types of PEAP
+	      methods, the most common one is PEAPv0/EAP-MSCHAPv2.  In
+	      the rest of this document, we will use the PEAP term to
+	      refers to that EAP method.  PEAP is the most used EAP
+	      standard after EAP-TLS, in other words if you have a
+	      network with mixed OSes, PEAP should be the most
+	      supported standard after EAP-TLS.</para>
+
+	    <para>PEAP is similar to EAP-TTLS: it uses a server-side
+	      certificate to authenticate clients by creating an
+	      encrypted TLS tunnel between the client and the
+	      authentication server, which protects the ensuing
+	      exchange of authentication information.  In term of
+	      security the difference between EAP-TTLS and PEAP is
+	      that PEAP authentication broadcasts the username in
+	      clear, only the password is sent in the encrypted TLS
+	      tunnel.  EAP-TTLS will use the TLS tunnel for both
+	      username and password.</para>
+
+	    <para>We have to edit the
+	      <filename>/etc/wpa_supplicant.conf</filename> file and
+	      add the EAP-PEAP related settings:</para>
+
+	    <programlisting>network={
+  ssid="freebsdap"
+  proto=RSN
+  key_mgmt=WPA-EAP
+  eap=PEAP <co id="co-peap-eap">
+  identity="test" <co id="co-peap-id">
+  password="test" <co id="co-peap-passwd">
+  ca_cert="/etc/certs/cacert.pem" <co id="co-peap-cacert">
+  phase1="peaplabel=0" <co id="co-peap-pha1">
+  phase2="auth=MSCHAPV2" <co id="co-peap-pha2">
+}</programlisting>
+
+	    <calloutlist>
+	      <callout arearefs="co-peap-eap">
+		<para>In this field, we mention the EAP method for our
+		  connection.</para>
+	      </callout>
+
+	      <callout arearefs="co-peap-id">
+		<para>The <literal>identity</literal> field contains
+		  the identity string for EAP authentication inside
+		  the encrypted TLS tunnel.</para>
+	      </callout>
+
+	      <callout arearefs="co-peap-passwd">
+		<para>The <literal>password</literal> field contains
+		  the passphrase for the EAP authentication.</para>
+	      </callout>
+
+	      <callout arearefs="co-peap-cacert">
+		<para>The <literal>ca_cert</literal> field indicates
+		  the pathname of the CA certificate file.  This file
+		  is needed to verify the server certificat.</para>
+	      </callout>
+
+	      <callout arearefs="co-peap-pha1">
+		<para>This field contains the parameters for the
+		  first phase of the authentication (the TLS
+		  tunnel).  According to the authentication server
+		  used, you will have to specify a specific label
+		  for the authentication.  Most of time, the label
+		  will be <quote>client EAP encryption</quote> which
+		  is set by using <literal>peaplabel=0</literal>.
+		  More information can be found in the
+		  &man.wpa.supplicant.conf.5; manual page.</para>
+	      </callout>
+
+	      <callout arearefs="co-peap-pha2">
+		<para>In this field, we mention the authentication
+		  protocol used in the encrypted TLS tunnel.  In the
+		  case of PEAP, it is
+		  <literal>auth=MSCHAPV2</literal>.</para>
+	      </callout>
+	    </calloutlist>
+
+	    <para>The following must be added to
+	      <filename>/etc/rc.conf</filename>:</para>
+
+	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>
+
+	    <para>Then, we can bring up the interface:</para>
+
+	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
+Starting wpa_supplicant.
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPREQUEST on ath0 to 255.255.255.255 port 67
+DHCPACK from 192.168.0.20
+bound to 192.168.0.254 -- renewal in 300 seconds.
+ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
+      ether 00:11:95:d5:43:62
+      media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
+      status: associated
+      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
+      authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
+      txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen>
+	  </sect5>
+	</sect4>
+
+	<sect4 id="network-wireless-wep">
+	  <title>WEP</title>
+
+	  <para>WEP (Wired Equivalent Privacy) is part of the original
+	    802.11 standard.  There is no authentication mechanism,
+	    only a weak form of access control, and it is easily to be
+	    cracked.</para>
+
+	  <para>WEP can be set up with
+	    <command>ifconfig</command>:</para>
+
+	  <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid my_net \
+	    wepmode on weptxkey 3 wepkey 3:0x3456789012</userinput></screen>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para>The <literal>weptxkey</literal> means which WEP
+		key will be used in the transmission.  Here we used the
+		third key.  This must match the setting in the access
+		point.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>The <literal>wepkey</literal> means setting the
+		selected WEP key.  It should in the format
+		<replaceable>index:key</replaceable>, if the index is
+		not given, key <literal>1</literal> is set.  That is
+		to say we need to set the index if we use keys other
+		than the first key.</para>
+
+	      <note>
+		<para>You must replace
+		  the <literal>0x3456789012</literal> with the key
+		  configured for use on the access point.</para>
+	      </note>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>You are encouraged to read &man.ifconfig.8; manual
+	    page for further information.</para>
+
+	  <para>The <command>wpa_supplicant</command> facility also
+	    can be used to configure your wireless interface with WEP.
+	    The example above can be set up by adding the following
+	    lines to
+	    <filename>/etc/wpa_supplicant.conf</filename>:</para>
+
+	  <programlisting>network={
+  ssid="my_net"
+  key_mgmt=NONE
+  wep_key3=3456789012
+  wep_tx_keyidx=3
+}</programlisting>
+
+	  <para>Then:</para>
+
+	  <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>ath0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
+Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz)
+Associated with 00:13:46:49:41:76</screen>
+	</sect4>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Ad-hoc Mode</title>
+
+      <para>IBSS mode, also called ad-hoc mode, is designed for point
+	to point connections.  For example, to establish an ad-hoc
+	network between the machine <hostid>A</hostid> and the machine
+	<hostid>B</hostid> we will just need to choose two IP adresses
+	and a SSID.</para>
+
+      <para>On the box <hostid>A</hostid>:</para>
+
+      <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mediaopt adhoc</userinput>
+&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
+  ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
+	  inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
+	  ether 00:11:95:c3:0d:ac
+	  media: IEEE 802.11 Wireless Ethernet autoselect &lt;adhoc&gt; (autoselect &lt;adhoc&gt;)
+	  status: associated
+	  ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac
+	  authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen>
+
+      <para>The <literal>adhoc</literal> parameter indicates the
+	interface is running in the IBSS mode.</para>
+
+      <para>On <hostid>B</hostid>, we should be able to detect
+	<hostid>A</hostid>:</para>
+
+      <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput>
+  SSID            BSSID              CHAN RATE  S:N   INT CAPS
+  freebsdap       02:11:95:c3:0d:ac    2   54M 19:0   100 IS</screen>
+
+      <para>The <literal>I</literal> in the output confirms the
+	machine <hostid>A</hostid> is in ad-hoc mode.  We just have to
+	configure <hostid>B</hostid> with a different IP
+	address:</para>
+
+      <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mediaopt adhoc</userinput>
+&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
+  ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
+	  inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
+	  inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
+	  ether 00:11:95:d5:43:62
+	  media: IEEE 802.11 Wireless Ethernet autoselect &lt;adhoc&gt; (autoselect &lt;adhoc&gt;)
+	  status: associated
+	  ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac
+	  authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen>
+
+	  <para>Both <hostid>A</hostid> and <hostid>B</hostid> are now
+	    ready to exchange informations.</para>
+    </sect2>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <para>If you are having trouble with wireless networking, there
+	are a number of steps you can take to help troubleshoot the
+	problem.</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>If you do not see the access point listed when
+	    scanning be sure you have not configured your wireless
+	    device to a limited set of channels.</para>
+	</listitem>
+
+	<listitem>
+	  <para>If you cannot associate to an access point verify the
+	    configuration of your station matches the one of the
+	    access point.  This includes the authentication scheme and
+	    any security protocols.  Simplify your configuration as
+	    much as possible.  If you are using a security protocol
+	    such as WPA or WEP configure the access point for open
+	    authentication and no security to see if you can get
+	    traffic to pass.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Once you can associate to the access point diagnose
+	    any security configuration using simple tools like
+	    &man.ping.8;.</para>
+
+	  <para>The <command>wpa_supplicant</command> has much
+	    debugging support; try running it manually with the
+	    <option>-dd</option> option and look at the system
+	    logs.</para>
+	</listitem>
+
+	<listitem>
+	  <para>There are also many lower-level debugging tools.  You
+	    can enable debugging messages in the 802.11 protocol
+	    support layer using the <command>wlandebug</command>
+	    program found in
+	    <filename>/usr/src/tools/tools/net80211</filename>.  For
+	    example:</para>
+
+	  <screen>&prompt.root; <userinput>wlandebug -i <replaceable>ath0</replaceable> +scan+auth+debug+assoc</userinput>
+  net.wlan.0.debug: 0 =&gt; 0xc80000&lt;assoc,auth,scan&gt;</screen>
+
+	  <para>can be used to enable console messages related to
+	    scanning for access points and doing the 802.11 protocol
+	    handshakes required to arrange communication.</para>
+
+	  <para>There are also many useful statistics maintained by
+	    the 802.11 layer; the <command>wlanstats</command> tool
+	    will dump these informations.  These statistics should
+	    identify all errors identified by the 802.11 layer.
+	    Beware however that some errors are identified in the
+	    device drivers that lie below the 802.11 layer so they may
+	    not show up.  To diagnose device-specific problems you
+	    need to refer to the drivers' documentation.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>If the above information does not help to clarify the
+	problem, please submit a problem report and include output
+	from the above tools.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-bluetooth">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Pav</firstname>
+          <surname>Lucistnik</surname>
+          <contrib>Written by </contrib>
+          <affiliation>
+	    <address><email>pav@FreeBSD.org</email></address>
+          </affiliation>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>Bluetooth</title>
+
+    <indexterm><primary>Bluetooth</primary></indexterm>
+    <sect2>
+      <title>Introduction</title>
+      <para>Bluetooth is a wireless technology for creating personal networks
+        operating in the 2.4 GHz unlicensed band, with a range of 10 meters.
+        Networks are usually formed ad-hoc from portable devices such as
+        cellular phones, handhelds and laptops. Unlike the other popular
+        wireless technology, Wi-Fi, Bluetooth offers higher level service
+        profiles, e.g. FTP-like file servers, file pushing, voice transport,
+        serial line emulation, and more.</para>
+
+      <para>The Bluetooth stack in &os; is implemented using the Netgraph
+        framework (see &man.netgraph.4;). A broad variety of Bluetooth USB
+        dongles is supported by the &man.ng.ubt.4; driver. The Broadcom BCM2033
+        chip based Bluetooth devices are supported via the &man.ubtbcmfw.4; and
+        &man.ng.ubt.4; drivers. The 3Com Bluetooth PC Card 3CRWB60-A is
+        supported by the &man.ng.bt3c.4; driver. Serial and UART based
+        Bluetooth devices are supported via &man.sio.4;, &man.ng.h4.4;
+        and &man.hcseriald.8;. This section describes the use of the USB
+        Bluetooth dongle.</para>
+    </sect2>
+
+    <sect2>
+      <title>Plugging in the Device</title>
+      <para>By default Bluetooth device drivers are available as kernel modules.
+        Before attaching a device, you will need to load the driver into the
+        kernel:</para>
+
+      <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>
+
+      <para>If the Bluetooth device is present in the system during system
+        startup, load the module from
+        <filename>/boot/loader.conf</filename>:</para>
+
+      <programlisting>ng_ubt_load="YES"</programlisting>
+
+      <para>Plug in your USB dongle. The output similar to the following will
+        appear on the console (or in syslog):</para>
+
+      <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
+ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
+ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
+      wMaxPacketSize=49, nframes=6, buffer size=294</screen>
+
+      <note>
+	<para>The Bluetooth stack has to be started manually on &os; 6.0, and
+	  on &os; 5.X before 5.5.  It is done automatically from &man.devd.8;
+	  on &os; 5.5, 6.1 and newer.</para>
+
+      <para>Copy
+        <filename>/usr/share/examples/netgraph/bluetooth/rc.bluetooth</filename>
+        into some convenient place, like <filename>/etc/rc.bluetooth</filename>.
+        This script is used to start and stop the Bluetooth stack. It is a good
+        idea to stop the stack before unplugging the device, but it is not
+        (usually) fatal. When starting the stack, you will receive output similar
+        to the following:</para>
+
+      <screen>&prompt.root; <userinput>/etc/rc.bluetooth start ubt0</userinput>
+BD_ADDR: 00:02:72:00:d4:1a
+Features: 0xff 0xff 0xf 00 00 00 00 00
+&lt;3-Slot&gt; &lt;5-Slot&gt; &lt;Encryption&gt; &lt;Slot offset&gt;
+&lt;Timing accuracy&gt; &lt;Switch&gt; &lt;Hold mode&gt; &lt;Sniff mode&gt;
+&lt;Park mode&gt; &lt;RSSI&gt; &lt;Channel quality&gt; &lt;SCO link&gt;
+&lt;HV2 packets&gt; &lt;HV3 packets&gt; &lt;u-law log&gt; &lt;A-law log&gt; &lt;CVSD&gt;
+&lt;Paging scheme&gt; &lt;Power control&gt; &lt;Transparent SCO data&gt;
+Max. ACL packet size: 192 bytes
+Number of ACL packets: 8
+Max. SCO packet size: 64 bytes
+Number of SCO packets: 8</screen>
+      </note>
+
+    </sect2>
+
+    <indexterm><primary>HCI</primary></indexterm>
+    <sect2>
+      <title>Host Controller Interface (HCI)</title>
+
+      <para>Host Controller Interface (HCI) provides a command interface to the
+        baseband controller and link manager, and access to hardware status and
+        control registers. This interface provides a uniform method of accessing
+        the Bluetooth baseband capabilities. HCI layer on the Host exchanges
+        data and commands with the HCI firmware on the Bluetooth hardware.
+        The Host Controller Transport Layer (i.e. physical bus) driver provides
+        both HCI layers with the ability to exchange information with each
+        other.</para>
+
+      <para>A single Netgraph node of type <emphasis>hci</emphasis> is
+        created for a single Bluetooth device. The HCI node is normally
+        connected to the Bluetooth device driver node (downstream) and
+        the L2CAP node (upstream). All HCI operations must be performed
+        on the HCI node and not on the device driver node. Default name
+        for the HCI node is <quote>devicehci</quote>.
+        For more details refer to the &man.ng.hci.4; manual page.</para>
+
+      <para>One of the most common tasks is discovery of Bluetooth devices in
+        RF proximity. This operation is called <emphasis>inquiry</emphasis>.
+        Inquiry and other HCI related operations are done with the
+        &man.hccontrol.8; utility. The example below shows how to find out
+        which Bluetooth devices are in range. You should receive the list of
+        devices in a few seconds. Note that a remote device will only answer
+        the inquiry if it put into <emphasis>discoverable</emphasis>
+        mode.</para>
+
+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
+Inquiry result, num_responses=1
+Inquiry result #0
+       BD_ADDR: 00:80:37:29:19:a4
+       Page Scan Rep. Mode: 0x1
+       Page Scan Period Mode: 00
+       Page Scan Mode: 00
+       Class: 52:02:04
+       Clock offset: 0x78ef
+Inquiry complete. Status: No error [00]</screen>
+
+      <para><literal>BD_ADDR</literal> is unique address of a Bluetooth
+        device, similar to MAC addresses of a network card. This address
+        is needed for further communication with a device. It is possible
+        to assign human readable name to a BD_ADDR.
+        The <filename>/etc/bluetooth/hosts</filename> file contains information
+        regarding the known Bluetooth hosts. The following example shows how
+        to obtain human readable name that was assigned to the remote
+        device:</para>
+
+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput>
+BD_ADDR: 00:80:37:29:19:a4
+Name: Pav's T39</screen>
+
+      <para>If you perform an inquiry on a remote Bluetooth device, it will
+        find your computer as <quote>your.host.name (ubt0)</quote>. The name
+        assigned to the local device can be changed at any time.</para>
+
+      <para>The Bluetooth system provides a point-to-point connection (only two
+        Bluetooth units involved), or a point-to-multipoint connection. In the
+        point-to-multipoint connection the connection is shared among several
+        Bluetooth devices. The following example shows how to obtain the list
+        of active baseband connections for the local device:</para>
+
+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
+Remote BD_ADDR    Handle Type Mode Role Encrypt Pending Queue State
+00:80:37:29:19:a4     41  ACL    0 MAST    NONE       0     0 OPEN</screen>
+
+      <para>A <emphasis>connection handle</emphasis> is useful when termination
+        of the baseband connection is required. Note, that it is normally not
+        required to do it by hand. The stack will automatically terminate
+        inactive baseband connections.</para>
+
+      <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput>
+Connection handle: 41
+Reason: Connection terminated by local host [0x16]</screen>
+
+      <para>Refer to <command>hccontrol help</command> for a complete listing
+        of available HCI commands. Most of the HCI commands do not require
+        superuser privileges.</para>
+
+    </sect2>
+
+    <indexterm><primary>L2CAP</primary></indexterm>
+    <sect2>
+      <title>Logical Link Control and Adaptation Protocol (L2CAP)</title>
+
+      <para>Logical Link Control and Adaptation Protocol (L2CAP) provides
+        connection-oriented and connectionless data services to upper layer
+        protocols with protocol multiplexing capability and segmentation and
+        reassembly operation. L2CAP permits higher level protocols and
+        applications to transmit and receive L2CAP data packets up to 64
+        kilobytes in length.</para>
+
+      <para>L2CAP is based around the concept of <emphasis>channels</emphasis>.
+        Channel is a logical connection on top of baseband connection. Each
+        channel is bound to a single protocol in a many-to-one fashion. Multiple
+        channels can be bound to the same protocol, but a channel cannot be
+        bound to multiple protocols. Each L2CAP packet received on a channel is
+        directed to the appropriate higher level protocol. Multiple channels
+        can share the same baseband connection.</para>
+
+      <para>A single Netgraph node of type <emphasis>l2cap</emphasis> is
+        created for a single Bluetooth device. The L2CAP node is normally
+        connected to the Bluetooth HCI node (downstream) and Bluetooth sockets
+        nodes (upstream). Default name for the L2CAP node is
+        <quote>devicel2cap</quote>. For more details refer to the
+        &man.ng.l2cap.4; manual page.</para>
+
+      <para>A useful command is &man.l2ping.8;, which can be used to ping
+        other devices. Some Bluetooth implementations might not return all of
+        the data sent to them, so <literal>0 bytes</literal> in the following
+        example is normal.</para>
+
+      <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
+0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
+0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
+0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
+0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>
+
+      <para>The &man.l2control.8; utility is used to perform various operations
+        on L2CAP nodes. This example shows how to obtain the list of logical
+        connections (channels) and the list of baseband connections for the
+        local device:</para>
+
+      <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
+L2CAP channels:
+Remote BD_ADDR     SCID/ DCID   PSM  IMTU/ OMTU State
+00:07:e0:00:0b:ca    66/   64     3   132/  672 OPEN
+&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput>
+L2CAP connections:
+Remote BD_ADDR    Handle Flags Pending State
+00:07:e0:00:0b:ca     41 O           0 OPEN</screen>
+
+      <para>Another diagnostic tool is &man.btsockstat.1;. It does a job
+        similar to as &man.netstat.1; does, but for Bluetooth network-related
+        data structures. The example below shows the same logical connection as
+        &man.l2control.8; above.</para>
+
+      <screen>&prompt.user; <userinput>btsockstat</userinput>
+Active L2CAP sockets
+PCB      Recv-Q Send-Q Local address/PSM       Foreign address   CID   State
+c2afe900      0      0 00:02:72:00:d4:1a/3     00:07:e0:00:0b:ca 66    OPEN
+Active RFCOMM sessions
+L2PCB    PCB      Flag MTU   Out-Q DLCs State
+c2afe900 c2b53380 1    127   0     Yes  OPEN
+Active RFCOMM sockets
+PCB      Recv-Q Send-Q Local address     Foreign address   Chan DLCI State
+c2e8bc80      0    250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3    6    OPEN</screen>
+
+    </sect2>
+
+    <indexterm><primary>RFCOMM</primary></indexterm>
+    <sect2>
+      <title>RFCOMM Protocol</title>
+
+      <para>The RFCOMM protocol provides emulation of serial ports over the
+        L2CAP protocol. The protocol is based on the ETSI standard TS 07.10.
+        RFCOMM is a simple transport protocol, with additional provisions for
+        emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The
+        RFCOMM protocol supports up to 60 simultaneous connections (RFCOMM
+        channels) between two Bluetooth devices.</para>
+
+      <para>For the purposes of RFCOMM, a complete communication path involves
+        two applications running on different devices (the communication
+        endpoints) with a communication segment between them. RFCOMM is intended
+        to cover applications that make use of the serial ports of the devices
+        in which they reside. The communication segment is a Bluetooth link from
+        one device to another (direct connect).</para>
+
+      <para>RFCOMM is only concerned with the connection between the devices in
+        the direct connect case, or between the device and a modem in the
+        network case. RFCOMM can support other configurations, such as modules
+        that communicate via Bluetooth wireless technology on one side and
+        provide a wired interface on the other side.</para>
+
+      <para>In &os; the RFCOMM protocol is implemented at the Bluetooth sockets
+        layer.</para>
+    </sect2>
+
+    <indexterm><primary>pairing</primary></indexterm>
+    <sect2>
+      <title>Pairing of Devices</title>
+
+      <para>By default, Bluetooth communication is not authenticated, and any
+        device can talk to any other device. A Bluetooth device (for example,
+        cellular phone) may choose to require authentication to provide a
+        particular service (for example, Dial-Up service). Bluetooth
+        authentication is normally done with <emphasis>PIN codes</emphasis>.
+        A PIN code is an ASCII string up to 16 characters in length. User is
+        required to enter the same PIN code on both devices. Once user has
+        entered the PIN code, both devices will generate a
+        <emphasis>link key</emphasis>. After that the link key can be stored
+        either in the devices themselves or in a persistent storage. Next time
+        both devices will use previously generated link key. The described
+        above procedure is called <emphasis>pairing</emphasis>. Note that if
+        the link key is lost by any device then pairing must be repeated.</para>
+
+      <para>The &man.hcsecd.8; daemon is responsible for handling of all
+        Bluetooth authentication requests. The default configuration file is
+        <filename>/etc/bluetooth/hcsecd.conf</filename>. An example section for
+        a cellular phone with the PIN code arbitrarily set to
+        <quote>1234</quote> is shown below:</para>
+
+      <programlisting>device {
+        bdaddr  00:80:37:29:19:a4;
+        name    "Pav's T39";
+        key     nokey;
+        pin     "1234";
+      }</programlisting>
+
+      <para>There is no limitation on PIN codes (except length). Some devices
+        (for example Bluetooth headsets) may have a fixed PIN code built in.
+        The <option>-d</option> switch forces the &man.hcsecd.8; daemon to stay
+        in the foreground, so it is easy to see what is happening. Set the
+        remote device to receive pairing and initiate the Bluetooth connection
+        to the remote device. The remote device should say that pairing was
+        accepted, and request the PIN code. Enter the same PIN code as you
+        have in <filename>hcsecd.conf</filename>. Now your PC and the remote
+        device are paired. Alternatively, you can initiate pairing on the remote
+        device.</para>
+
+      <para>On &os; 5.5, 6.1 and newer, the following line can be added to the
+	<filename>/etc/rc.conf</filename> file to have
+	<application>hcsecd</application> started automatically on system
+	start:</para>
+
+      <programlisting>hcsecd_enable="YES"</programlisting>
+
+      <para>The following is a sample of the
+        <application>hcsecd</application> daemon output:</para>
+
+<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
+hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
+hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
+hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
+hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
+hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting>
+
+    </sect2>
+
+    <indexterm><primary>SDP</primary></indexterm>
+    <sect2>
+      <title>Service Discovery Protocol (SDP)</title>
+      <para>The Service Discovery Protocol (SDP) provides the means for client
+        applications to discover the existence of services provided by server
+        applications as well as the attributes of those services. The attributes
+        of a service include the type or class of service offered and the
+        mechanism or protocol information needed to utilize the service.</para>
+
+      <para>SDP involves communication between a SDP server and a SDP client.
+        The server maintains a list of service records that describe the
+        characteristics of services associated with the server. Each service
+        record contains information about a single service. A client may 
+        retrieve information from a service record maintained by the SDP server
+        by issuing a SDP request. If the client, or an application associated
+        with the client, decides to use a service, it must open a separate
+        connection to the service provider in order to utilize the service.
+        SDP provides a mechanism for discovering services and their attributes,
+        but it does not provide a mechanism for utilizing those services.</para>
+
+      <para>Normally, a SDP client searches for services based on some desired
+        characteristics of the services. However, there are times when it is
+        desirable to discover which types of services are described by an SDP
+        server's service records without any a priori information about the
+        services. This process of looking for any offered services is called
+        <emphasis>browsing</emphasis>.</para>
+ 
+      <para>The Bluetooth SDP server &man.sdpd.8; and command line client
+        &man.sdpcontrol.8; are included in the standard &os; installation.
+        The following example shows how to perform a SDP browse query.</para>
+
+      <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput>
+Record Handle: 00000000
+Service Class ID List:
+        Service Discovery Server (0x1000)
+Protocol Descriptor List:
+        L2CAP (0x0100)
+                Protocol specific parameter #1: u/int/uuid16 1
+                Protocol specific parameter #2: u/int/uuid16 1
+
+Record Handle: 0x00000001
+Service Class ID List:
+        Browse Group Descriptor (0x1001)
+
+Record Handle: 0x00000002
+Service Class ID List:
+        LAN Access Using PPP (0x1102)
+Protocol Descriptor List:
+        L2CAP (0x0100)
+        RFCOMM (0x0003)
+                Protocol specific parameter #1: u/int8/bool 1
+Bluetooth Profile Descriptor List:
+        LAN Access Using PPP (0x1102) ver. 1.0
+</screen>
+
+      <para>... and so on. Note that each service has a list of attributes
+        (RFCOMM channel for example). Depending on the service you might need to
+        make a note of some of the attributes. Some Bluetooth implementations do
+        not support service browsing and may return an empty list. In this case
+        it is possible to search for the specific service. The example below
+        shows how to search for the OBEX Object Push (OPUSH) service:</para>
+
+      <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen>
+
+      <para>Offering services on &os; to Bluetooth clients is done with the
+	&man.sdpd.8; server. On &os; 5.5, 6.1 and newer, the following line can
+	be added to the <filename>/etc/rc.conf</filename> file:</para>
+
+      <programlisting>sdpd_enable="YES"</programlisting>
+
+      <para>Then the <application>sdpd</application> daemon can be started with:</para>
+
+      <screen>&prompt.root; <userinput>/etc/rc.d/sdpd start</userinput></screen>
+
+      <para>On &os; 6.0, and on &os; 5.X before 5.5,
+	<application>sdpd</application> is not integrated into the system
+	startup scripts.  It has to be started manually with:</para>
+
+      <screen>&prompt.root; <userinput>sdpd</userinput></screen>
+
+      <para>The local server application that wants to provide Bluetooth
+        service to the remote clients will register service with the local
+        SDP daemon. The example of such application is &man.rfcomm.pppd.8;.
+        Once started it will register Bluetooth LAN service with the local
+        SDP daemon.</para>
+
+      <para>The list of services registered with the local SDP server can be
+        obtained by issuing SDP browse query via local control channel:</para>
+
+      <screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen>
+
+    </sect2>
+
+    <sect2>
+      <title>Dial-Up Networking (DUN) and Network Access with PPP (LAN)
+        Profiles</title>
+
+      <para>The Dial-Up Networking (DUN) profile is mostly used with modems
+        and cellular phones. The scenarios covered by this profile are the
+        following:</para>
+
+      <itemizedlist>
+        <listitem><para>use of a cellular phone or modem by a computer as
+          a wireless modem for connecting to a dial-up Internet access server,
+          or using other dial-up services;</para></listitem>
+
+        <listitem><para>use of a cellular phone or modem by a computer to
+          receive data calls.</para></listitem>
+      </itemizedlist>
+
+      <para>Network Access with PPP (LAN) profile can be used in the following
+        situations:</para>
+
+      <itemizedlist>
+        <listitem><para>LAN access for a single Bluetooth device;
+           </para></listitem>
+
+        <listitem><para>LAN access for multiple Bluetooth devices;
+          </para></listitem>
+
+        <listitem><para>PC to PC (using PPP networking over serial cable
+          emulation).</para></listitem>
+      </itemizedlist>
+
+      <para>In &os; both profiles are implemented with &man.ppp.8; and
+        &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth
+        connection into something PPP can operate with. Before any profile
+        can be used, a new PPP label in the <filename>/etc/ppp/ppp.conf</filename>
+        must be created. Consult &man.rfcomm.pppd.8; manual page for examples.
+      </para>
+
+      <para>In the following example &man.rfcomm.pppd.8; will be used to open
+        RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on
+        DUN RFCOMM channel. The actual RFCOMM channel number will be obtained
+        from the remote device via SDP. It is possible to specify RFCOMM channel
+        by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP
+        query. Use &man.sdpcontrol.8; to find out RFCOMM
+        channel on the remote device.</para>
+
+      <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>
+
+      <para>In order to provide Network Access with PPP (LAN) service the
+        &man.sdpd.8; server must be running. A new entry for LAN clients must
+        be created in the <filename>/etc/ppp/ppp.conf</filename> file. Consult
+        &man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP
+        server on valid RFCOMM channel number. The RFCOMM PPP server will
+        automatically register Bluetooth LAN service with the local SDP daemon.
+        The example below shows how to start RFCOMM PPP server.</para>
+
+      <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>
+
+    </sect2>
+
+    <indexterm><primary>OBEX</primary></indexterm>
+    <sect2>
+      <title>OBEX Object Push (OPUSH) Profile</title>
+      <para>OBEX is a widely used protocol for simple file transfers between
+        mobile devices. Its main use is in infrared communication, where it is
+        used for generic file transfers between notebooks or PDAs,
+        and for sending business cards or calendar entries between cellular
+        phones and other devices with PIM applications.</para>
+
+      <para>The OBEX server and client are implemented as a third-party package
+        <application>obexapp</application>, which is available as
+	<filename role="package">comms/obexapp</filename> port.</para>
+
+      <para>OBEX client is used to push and/or pull objects from the OBEX server.
+        An object can, for example, be a business card or an appointment.
+        The OBEX client can obtain RFCOMM channel number from the remote device
+        via SDP. This can be done by specifying service name instead of RFCOMM
+        channel number. Supported service names are: IrMC, FTRN and OPUSH.
+        It is possible to specify RFCOMM channel as a number. Below is an
+        example of an OBEX session, where device information object is pulled
+        from the cellular phone, and a new object (business card) is pushed
+        into the phone's directory.</para>
+
+      <screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput>
+obex&gt; get telecom/devinfo.txt devinfo-t39.txt
+Success, response: OK, Success (0x20)
+obex&gt; put new.vcf
+Success, response: OK, Success (0x20)
+obex&gt; di
+Success, response: OK, Success (0x20)</screen>
+
+      <para>In order to provide OBEX Object Push service,
+        &man.sdpd.8; server must be running. A root folder, where all incoming
+        objects will be stored, must be created. The default path to the root
+        folder is <filename>/var/spool/obex</filename>. Finally, start OBEX
+        server on valid RFCOMM channel number. The OBEX server will
+        automatically register OBEX Object Push service with the local SDP
+        daemon. The example below shows how to start OBEX server.</para>
+
+      <screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Serial Port Profile (SPP)</title>
+      <para>The Serial Port Profile (SPP) allows Bluetooth devices to perform
+        RS232 (or similar) serial cable emulation. The scenario covered by this
+        profile deals with legacy applications using Bluetooth as a cable
+        replacement, through a virtual serial port abstraction.</para>
+
+      <para>The &man.rfcomm.sppd.1; utility implements the Serial Port profile.
+        A pseudo tty is used as a virtual serial port abstraction. The example
+        below shows how to connect to a remote device Serial Port service.
+        Note that you do not have to specify a RFCOMM channel -
+        &man.rfcomm.sppd.1; can obtain it from the remote device via SDP.
+        If you would like to override this, specify a RFCOMM channel on the
+        command line.</para>
+
+      <screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6</userinput>
+rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>
+
+      <para>Once connected, the pseudo tty can be used as serial port:</para>
+
+      <screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen>
+
+    </sect2>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <sect3>
+        <title>A remote device cannot connect</title>
+        <para>Some older Bluetooth devices do not support role switching.
+          By default, when &os; is accepting a new connection, it tries to
+          perform a role switch and become master. Devices, which do not
+          support this will not be able to connect. Note that role switching is
+          performed when a new connection is being established, so it is not
+          possible to ask the remote device if it does support role switching.
+          There is a HCI option to disable role switching on the local
+          side:</para>
+
+        <screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>
+
+      </sect3>
+
+      <sect3>
+        <title>Something is going wrong, can I see what exactly is happening?</title>
+        <para>Yes, you can.  Use the third-party package
+          <application>hcidump</application>, which is available as
+	  <filename role="package">comms/hcidump</filename> port.
+          The <application>hcidump</application> utility is similar to
+          &man.tcpdump.1;. It can be used to display the content of the Bluetooth
+          packets on the terminal and to dump the Bluetooth packets to a
+          file.</para>
+      </sect3>
+
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="network-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 <hostid>A</hostid> for file service, and the Production users
+	  are on server <hostid>B</hostid>.  An Ethernet network 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>NAT</primary></indexterm>
+
+	<para>The second common situation is where firewall functionality is
+	  needed without network address translation (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
+	  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 options</primary>
+	  <secondary>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 <literal>IPFIREWALL</literal> 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 a 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.enable=1</programlisting>
+
+      <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
+	runtime, and the line:</para>
+
+      <programlisting>net.link.ether.bridge.config=<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>
+
+      <para>For versions prior to &os;&nbsp;5.2-RELEASE, use instead the following
+	lines:</para>
+
+      <programlisting>net.link.ether.bridge=1
+net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable>
+net.link.ether.bridge_ipfw=1</programlisting>
+
+    </sect2>
+    
+    <sect2>
+      <title>Other Information</title>
+
+      <para>If you want to be able to &man.ssh.1; into the bridge from the network,
+	it is correct 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>
+
+      <para>A bridge can add latency to your &man.ping.8; times, especially for
+        traffic from one segment to another.</para>
+      
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-diskless">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Jean-Fran&ccedil;ois</firstname>
+          <surname>Dock&egrave;s</surname>
+          <contrib>Updated by </contrib>
+        </author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Alex</firstname>
+	  <surname>Dupre</surname>
+	  <contrib>Reorganized and enhanced by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Diskless Operation</title>
+
+    <indexterm><primary>diskless workstation</primary></indexterm>
+    <indexterm><primary>diskless operation</primary></indexterm>
+
+    <para>A FreeBSD machine can boot over the network and operate without a
+      local disk, using file systems mounted from an <acronym>NFS</acronym> server.  No system
+      modification is necessary, beyond standard configuration files.
+      Such a system is relatively 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><acronym>PXE</acronym>: The &intel; 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>The <application>Etherboot</application>
+	      port (<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 file system
+	  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 <acronym>NFS</acronym> 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 variations on 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>/</filename> file system, and a shared
+	  read-only <filename>/usr</filename>.</para>
+	<para>The root file system is a copy of a
+	  standard FreeBSD root (typically the server's), with some
+	  configuration files overridden by ones specific to diskless
+	  operation or, possibly, to the workstation they belong to.</para>
+	<para>The parts of the root which have to be
+	  writable are overlaid with &man.md.4; file systems.  Any changes
+	  will be lost when the system reboots.</para>
+      </listitem>
+      <listitem>
+	<para>The kernel is transferred and loaded either with
+	  <application>Etherboot</application> or <acronym>PXE</acronym>
+	  as some situations may mandate the use of either method.</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>
+
+    <para>All the information in this section has been tested
+      using &os; 5.2.1-RELEASE.</para>
+
+    <sect2>
+      <title>Background Information</title>
+
+      <para>Setting up diskless workstations is both relatively
+	straightforward and prone to errors.  These are sometimes
+	difficult to diagnose for a number of reasons.  For example:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Compile time options may determine different behaviors at
+	    runtime.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Error messages are often cryptic or totally absent.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>In this context, having some knowledge of the background
+	mechanisms involved is very useful to solve the problems that
+	may arise.</para>
+
+      <para>Several operations need to be performed for a successful
+	bootstrap:</para>
+        
+      <itemizedlist>
+	<listitem>
+	  <para>The machine needs to obtain initial parameters such as its IP
+	    address, executable filename, server name, root path.  This is
+	    done using the <acronym>DHCP</acronym> or BOOTP protocols.
+	    <acronym>DHCP</acronym> is a compatible extension of BOOTP, and
+	    uses the same port numbers and basic packet format.</para>
+
+	  <para>It is possible to configure a system to use only BOOTP.
+	    The &man.bootpd.8; server program is included in the base &os;
+	    system.</para>
+
+	  <para>However, <acronym>DHCP</acronym> has a number of advantages
+	    over BOOTP (nicer configuration files, possibility of using
+	    <acronym>PXE</acronym>, plus many others not directly related to
+	    diskless operation), and we will describe mainly a
+	    <acronym>DHCP</acronym> configuration, with equivalent examples
+	    using &man.bootpd.8; when possible.  The sample configuration will
+	    use the <application>ISC DHCP</application> software package
+	    (release 3.0.1.r12 was installed on the test server).</para>
+	</listitem>
+
+	<listitem>
+	  <para>The machine needs to transfer one or several programs to local
+	    memory.  Either <acronym>TFTP</acronym> or <acronym>NFS</acronym>
+	    are used.  The choice between <acronym>TFTP</acronym> and
+	    <acronym>NFS</acronym> is a compile time option in several places.
+	    A common source of error is to specify filenames for the wrong
+	    protocol: <acronym>TFTP</acronym> typically transfers all files from
+	    a single directory on the server, and would expect filenames
+	    relative to this directory.  <acronym>NFS</acronym> needs absolute
+	    file paths.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The possible intermediate bootstrap programs and the kernel
+	    need to be initialized and executed.  There are several important
+	    variations in this area:</para>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para><acronym>PXE</acronym> will load &man.pxeboot.8;, which is
+		a modified version of the &os; third stage loader.  The
+		&man.loader.8; will obtain most parameters necessary to system
+		startup, and leave them in the kernel environment before
+		transferring control.  It is possible to use a
+		<filename>GENERIC</filename> kernel in this case.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para><application>Etherboot</application>, will directly
+		load the kernel, with less preparation.  You will need to
+		build a kernel with specific options.</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para><acronym>PXE</acronym> and <application>Etherboot</application>
+	    work equally well; however, because kernels
+	    normally let the &man.loader.8; do more work for them,
+	    <acronym>PXE</acronym> is the preferred method.</para>
+
+	  <para>If your <acronym>BIOS</acronym> and network cards support
+	    <acronym>PXE</acronym>, you should probably use it.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Finally, the machine needs to access its file systems.
+	    <acronym>NFS</acronym> is used in all cases.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>See also &man.diskless.8; manual page.</para>
+    </sect2>
+
+    <sect2>
+      <title>Setup Instructions</title>
+
+      <sect3>
+	  <title>Configuration Using <application>ISC DHCP</application></title>
+	  <indexterm>
+	    <primary>DHCP</primary>
+	    <secondary>diskless operation</secondary>
+	  </indexterm>
+
+	  <para>The <application>ISC DHCP</application> server can answer
+	    both BOOTP and <acronym>DHCP</acronym> requests.</para>
+
+	  <para><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-server</filename> port or the
+	    corresponding package.</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, where host <hostid>margaux</hostid>
+	    uses <application>Etherboot</application> and host
+	    <hostid>corbieres</hostid> uses <acronym>PXE</acronym>:</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 "/data/misc/kernel.diskless"; <co id="co-dhcp-filename">
+    option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path">
+  }
+  host corbieres {
+    hardware ethernet 00:02:b3:27:62:df;
+    fixed-address corbieres.example.com;
+    next-server 192.168.4.4;
+    filename "pxeboot";
+    option root-path "192.168.4.4:/data/misc/diskless";
+  }
+}
+          </programlisting>
+
+	  <calloutlist>
+	    <callout arearefs="co-dhcp-host-name"><para>This option tells
+		<application>dhcpd</application> 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
+		<literal>host</literal> declarations.</para>
+	    </callout>
+
+	    <callout arearefs="co-dhcp-next-server"><para>The
+		<literal>next-server</literal> directive designates
+		the <acronym>TFTP</acronym> or <acronym>NFS</acronym> server to
+		use for loading loader or kernel file (the default is to use
+		the same host as the
+		<acronym>DHCP</acronym> server).</para>
+	    </callout>
+
+	    <callout arearefs="co-dhcp-filename"><para>The
+		<literal>filename</literal> directive defines the file that
+		<application>Etherboot</application> or <acronym>PXE</acronym>
+		will load for the next execution step.  It must be specified
+		according to the transfer method used.
+		<application>Etherboot</application> can be compiled to use
+		<acronym>NFS</acronym> or <acronym>TFTP</acronym>.  The &os;
+		port configures <acronym>NFS</acronym> by default.
+		<acronym>PXE</acronym> uses <acronym>TFTP</acronym>, which is
+		why a relative filename is used here (this may depend on the
+		<acronym>TFTP</acronym> server configuration, but would be
+		fairly typical).  Also, <acronym>PXE</acronym> loads
+		<filename>pxeboot</filename>, not the kernel.  There are other
+		interesting possibilities, like loading
+		<filename>pxeboot</filename> from a &os; CD-ROM
+		<filename role="directory">/boot</filename> directory (as
+		&man.pxeboot.8; can load a <filename>GENERIC</filename> kernel,
+		this makes it possible to use <acronym>PXE</acronym> to boot
+		from a remote CD-ROM).</para>
+	    </callout>
+
+	    <callout arearefs="co-dhcp-root-path"><para>The
+		<literal>root-path</literal> option defines the path to
+		the root file system, in usual <acronym>NFS</acronym> notation.
+		When using <acronym>PXE</acronym>, it is possible to leave off
+		the host's IP as long as you do not enable the kernel option
+		BOOTP.  The <acronym>NFS</acronym> server will then be
+		the same as the <acronym>TFTP</acronym> one.</para>
+	    </callout>
+	  </calloutlist>
+
+      </sect3>
+      <sect3>
+	  <title>Configuration Using BOOTP</title>
+	  <indexterm>
+	    <primary>BOOTP</primary>
+	    <secondary>diskless operation</secondary>
+	  </indexterm>
+
+	  <para>Here follows an equivalent <application>bootpd</application>
+	    configuration (reduced to one client).  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 <acronym>PXE</acronym> <emphasis>needs</emphasis> <acronym>DHCP</acronym>.  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>
+      </sect3>
+
+      <sect3>
+	<title>Preparing a Boot Program with
+	  <application>Etherboot</application></title>
+
+	<indexterm>
+	  <primary>Etherboot</primary>
+	</indexterm>
+
+	<para><ulink url="http://etherboot.sourceforge.net">Etherboot's Web
+	  site</ulink> contains
+	  <ulink url="http://etherboot.sourceforge.net/doc/html/userman/t1.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.</para>
+
+	<para>You can change the <application>Etherboot</application>
+	  configuration (i.e. to use <acronym>TFTP</acronym> instead of
+	  <acronym>NFS</acronym>) by editing the <filename>Config</filename>
+	  file in the <application>Etherboot</application> source
+	  directory.</para>
+
+	<para>For our setup, we shall use a boot floppy.  For other methods
+	  (PROM, or &ms-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>Booting with <acronym>PXE</acronym></title>
+
+	<para>By default, the &man.pxeboot.8; loader loads the kernel via
+	  <acronym>NFS</acronym>.  It can be compiled to use
+	  <acronym>TFTP</acronym> instead by specifying the
+	  <literal>LOADER_TFTP_SUPPORT</literal> option in
+	  <filename>/etc/make.conf</filename>.  See the comments in
+	  <filename>/usr/share/examples/etc/make.conf</filename>
+	  for instructions.</para>
+
+	<para>There are two other undocumented <filename>make.conf</filename>
+	  options which may be useful for setting up a serial console diskless
+	  machine: <literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and
+	  <literal>BOOT_PXELDR_ALWAYS_SERIAL</literal>.</para>
+
+	<para>To use <acronym>PXE</acronym> when the machine starts, you will
+	  usually need to select the <literal>Boot from network</literal>
+	  option in your <acronym>BIOS</acronym> setup, or type a function key
+	  during the PC initialization.</para>
+      </sect3>
+
+      <sect3>
+	<title>Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers</title>
+
+	<indexterm>
+	  <primary>TFTP</primary>
+	  <secondary>diskless operation</secondary>
+	</indexterm>
+	<indexterm>
+	  <primary>NFS</primary>
+	  <secondary>diskless operation</secondary>
+	</indexterm>
+
+	<para>If you are using <acronym>PXE</acronym> or
+	  <application>Etherboot</application> configured to use
+	  <acronym>TFTP</acronym>, you need to enable
+	  <application>tftpd</application> on the file server:</para>
+        <procedure>
+          <step>
+            <para>Create a directory from which <application>tftpd</application>
+            will serve the files, e.g. <filename>/tftpboot</filename>.</para>
+          </step>
+
+          <step>
+            <para>Add this line to your
+	      <filename>/etc/inetd.conf</filename>:</para>
+
+	    <programlisting>tftp	dgram	udp	wait	root	/usr/libexec/tftpd	tftpd -l -s /tftpboot</programlisting>
+
+	    <note><para>It appears that at least some <acronym>PXE</acronym> versions want
+		the <acronym>TCP</acronym> version of <acronym>TFTP</acronym>.  In this case, add a second line,
+		replacing <literal>dgram udp</literal> with <literal>stream
+		tcp</literal>.</para>
+	    </note>
+          </step>
+	  <step>
+	    <para>Tell <application>inetd</application> to reread its configuration
+	      file.  The <option>inetd_enable="YES"</option> must be in
+	      the <filename>/etc/rc.conf</filename> file for this
+	      command to execute correctly:</para>
+	    <screen>&prompt.root; <userinput>/etc/rc.d/inetd restart</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>In all cases, you also need to enable <acronym>NFS</acronym> and export the
+	  appropriate file system on the <acronym>NFS</acronym> 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 file system 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 corbieres</replaceable>
+	      with the names of the diskless workstations):</para>
+
+	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
+          </step>
+	  <step>
+	    <para>Tell <application>mountd</application> to reread its configuration
+	      file.  If you actually needed to enable <acronym>NFS</acronym> in
+	      <filename>/etc/rc.conf</filename>
+	      at the first step, you probably want to reboot instead.</para>
+	    <screen>&prompt.root; <userinput>/etc/rc.d/mountd restart</userinput></screen>
+	  </step>
+        </procedure>
+
+      </sect3>
+
+      <sect3>
+	<title>Building a Diskless Kernel</title>
+
+	<indexterm>
+	  <primary>diskless operation</primary>
+	  <secondary>kernel configuration</secondary>
+	</indexterm>
+
+	<para>If using <application>Etherboot</application>, you need to
+	  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 file system using BOOTP info
+	</programlisting>
+
+	<para>You may also want to use <literal>BOOTP_NFSV3</literal>,
+	  <literal>BOOT_COMPAT</literal> and <literal>BOOTP_WIRED_TO</literal>
+	  (refer to <filename>NOTES</filename>).</para>
+
+	<para>These option names are historical and slightly misleading as
+	  they actually enable indifferent use of <acronym>DHCP</acronym> and
+	  BOOTP inside the kernel (it is also possible to force strict BOOTP
+	  or <acronym>DHCP</acronym> use).</para>
+
+	<para>Build the kernel (see <xref linkend="kernelconfig">),
+	  and copy it to the place specified
+	  in <filename>dhcpd.conf</filename>.</para>
+
+	<note>
+	  <para>When using <acronym>PXE</acronym>, building a kernel with the
+	  above options is not strictly necessary (though suggested).
+	  Enabling them will cause more <acronym>DHCP</acronym> requests to be
+	  issued during kernel startup, with a small risk of inconsistency
+	  between the new values and those retrieved by &man.pxeboot.8; in some
+	  special cases.  The advantage of using them is that the host name
+	  will be set as a side effect.  Otherwise you will need to set the
+	  host name by another method, for example in a client-specific
+	  <filename>rc.conf</filename> file.</para>
+	</note>
+
+	<note>
+	  <para>In order to be loadable with
+	    <application>Etherboot</application>, a kernel needs to have
+	    the device hints compiled in.  You would typically set the
+	    following option in the configuration file (see the
+	    <filename>NOTES</filename> configuration comments file):</para>
+
+	  <programlisting>hints		"GENERIC.hints"</programlisting>
+	</note>
+
+      </sect3>
+
+      <sect3>
+	  <title>Preparing the Root Filesystem</title>
+
+	<indexterm>
+	  <primary>root file system</primary>
+	  <secondary>diskless operation</secondary>
+	</indexterm>
+
+	<para>You need to create a root file system for the diskless
+	  workstations, in the location listed as
+	  <literal>root-path</literal> in
+	  <filename>dhcpd.conf</filename>.</para>
+
+	<sect4>
+	  <title>Using <command>make world</command> to populate root</title>
+
+	  <para>This method is quick and
+	    will install a complete virgin system (not only the root file system)
+	    into <envar>DESTDIR</envar>.
+	    All you have to do is simply execute the following script:</para>
+
+	  <programlisting>#!/bin/sh
+export DESTDIR=/data/misc/diskless
+mkdir -p ${DESTDIR}
+cd /usr/src; make buildworld &amp;&amp; make buildkernel
+cd /usr/src/etc; make distribution</programlisting>
+
+	  <para>Once done, you may need to customize your
+	    <filename>/etc/rc.conf</filename> and
+	    <filename>/etc/fstab</filename> placed into
+	    <envar>DESTDIR</envar> according to your needs.</para>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<title>Configuring Swap</title>
+
+	<para>If needed, a swap file located on the server can be
+	  accessed via <acronym>NFS</acronym>.</para>
+
+	<sect4>
+	  <title><acronym>NFS</acronym> Swap</title>
+
+	  <para>The kernel does not support enabling <acronym>NFS</acronym>
+	    swap at boot time.  Swap must be enabled by the startup scripts,
+	    by mounting a writable file system and creating and enabling a
+	    swap file.  To create a swap file of appropriate size, you can do
+	    like this:</para>
+
+	  <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen>
+
+	  <para>To enable it you have to add the following line to your
+	    <filename>rc.conf</filename>:</para>
+
+	  <programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting>
+        </sect4>
+      </sect3>
+
+      <sect3>
+	<title>Miscellaneous Issues</title>
+
+
+	<sect4>
+	  <title>Running with a Read-only <filename>/usr</filename></title>
+
+	  <indexterm>
+	    <primary>diskless operation</primary>
+	    <secondary>/usr read-only</secondary>
+	  </indexterm>
+
+	    <para>If the diskless workstation is configured to run X, you
+	    will have to adjust the <application>XDM</application> 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 file system is not running FreeBSD,
+	    you will have to create the root file system on a
+	    FreeBSD machine, then copy it to its destination, using
+	    <command>tar</command> or <command>cpio</command>.</para>
+	  <para>In this situation, there are sometimes
+	    problems with the special files in <filename>/dev</filename>,
+	    due to differing major/minor integer sizes.  A solution to this
+	    problem is to export a directory from the non-FreeBSD server,
+	    mount this directory onto a FreeBSD machine, and
+	    use &man.devfs.5; to allocate device nodes transparently for
+	    the user.</para>
+
+	</sect4>
+
+      </sect3>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-isdn">
+    <title>ISDN</title>
+
+    <indexterm>
+      <primary>ISDN</primary>
+    </indexterm>
+
+    <para>A good resource for information on ISDN technology and hardware is
+      <ulink url="http://www.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="network-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.  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>The <application>isdn4bsd</application> software 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 <literal>isppp</literal>, a
+	modified &man.sppp.4; 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
+	&a.isdn.name; mailing list is available.</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 set up.  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 <link
+	  linkend="userppp">userland PPP</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="&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 synchronous card/TA v.s. stand-alone router is largely a
+	religious issue.  There has been some discussion of this in
+	the mailing lists.  We suggest you search the <ulink
+	url="&url.base;/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 section, 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
+|
+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="network-natd">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Chern</firstname>
+          <surname>Lee</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>Network Address Translation</title>
+
+    <sect2 id="network-natoverview">
+      <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.  &man.natd.8; 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>NAT</primary></indexterm>
+      <para>The most common use of NAT is to perform what is commonly known as
+        Internet Connection Sharing.</para>
+    </sect2>
+
+    <sect2 id="network-natsetup">
+      <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&mdash;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>
+
+      <note>
+	<para>There are many ways to get a LAN connected to the Internet
+	  through a &os; gateway.   This example will only cover a
+	  gateway with at least two NICs.</para>
+      </note>
+
+      <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="network-natdkernconfiguration">
+      <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" <co id="co-natd-gateway-enable">
+firewall_enable="YES" <co id="co-natd-firewall-enable">
+firewall_type="OPEN" <co id="co-natd-firewall-type">
+natd_enable="YES"
+natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface">
+natd_flags="" <co id="co-natd-natd-flags"></programlisting>
+
+      <calloutlist>
+        <callout arearefs="co-natd-gateway-enable">
+          <para>Sets up the machine to act as a gateway.  Running
+            <command>sysctl net.inet.ip.forwarding=1</command> would
+            have the same effect.</para>
+	</callout>
+
+        <callout arearefs="co-natd-firewall-enable">
+          <para>Enables the firewall rules in
+            <filename>/etc/rc.firewall</filename> at boot.</para>
+	</callout>
+
+        <callout arearefs="co-natd-firewall-type">
+          <para>This specifies a predefined firewall ruleset that
+            allows anything in.  See
+            <filename>/etc/rc.firewall</filename> for additional
+            types.</para>
+	</callout>
+
+        <callout arearefs="co-natd-natd-interface">
+          <para>Indicates which interface to forward packets through
+            (the interface connected to the Internet).</para>
+	</callout>
+
+        <callout arearefs="co-natd-natd-flags">
+          <para>Any additional configuration options passed to
+            &man.natd.8; on boot.</para>
+	</callout>
+      </calloutlist>
+
+      <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>
+
+      <note>
+	<para>It is also possible to use a configuration file for
+	  &man.natd.8; when there are too many options to pass.  In this
+	  case, the configuration file must be defined by adding the
+	  following line to <filename>/etc/rc.conf</filename>:</para>
+
+	<programlisting>natd_flags="-f /etc/natd.conf"</programlisting>
+
+	<para>The <filename>/etc/natd.conf</filename> file will
+	  contain a list of configuration options, one per line.  For
+	  example the next section case would use the following
+	  file:</para>
+
+	<programlisting>redirect_port tcp 192.168.0.2:6667 6667
+redirect_port tcp 192.168.0.3:80 80</programlisting>
+
+	<para>For more information about the configuration file,
+	  consult the &man.natd.8; manual page about the
+	  <option>-f</option> option.</para>
+      </note>
+
+      <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 <application>natd</application> 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 <application>natd</application> machine, <hostid
+        role="ipaddr">192.168.0.1</hostid>.  The <application>natd</application> machine's
+        external, or Internet interface does not require any special
+        modification for &man.natd.8; to work.</para>
+    </sect2>
+
+    <sect2 id="network-natdport-redirection">
+      <title>Port Redirection</title>
+
+      <para>The drawback with &man.natd.8; 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
+        <application>natd</application> machine to a LAN client.
+      </para>
+
+      <para>For example, an IRC server runs on client <hostid>A</hostid>, and a web server runs
+        on client <hostid>B</hostid>.  For this to work properly, connections received on ports
+        6667 (IRC) and 80 (web) must be redirected to the respective machines.
+      </para>
+
+      <para>The <option>-redirect_port</option> must be passed to
+        &man.natd.8; with the proper options.  The syntax is as follows:</para>
+      <programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
+                 [aliasIP:]aliasPORT[-aliasPORT]
+                 [remoteIP[:remotePORT[-remotePORT]]]</programlisting>
+
+      <para>In the above example, the argument should be:</para>
+
+        <programlisting>    -redirect_port tcp 192.168.0.2:6667 6667
+    -redirect_port tcp 192.168.0.3:80 80</programlisting>
+
+      <para>
+        This will redirect the proper <emphasis>tcp</emphasis> ports to the
+        LAN client machines.
+      </para>
+
+      <para>The <option>-redirect_port</option> 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 <hostid>A</hostid>.</para>
+
+      <para>These options can be used when directly running
+        &man.natd.8;, placed within the
+        <literal>natd_flags=""</literal> option in
+        <filename>/etc/rc.conf</filename>,
+	or passed via a configuration file.</para>
+
+      <para>For further configuration options, consult &man.natd.8;</para>
+    </sect2>
+
+    <sect2 id="network-natdaddress-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 <application>natd</application> gateway
+        machine.  <hostid role="ipaddr">128.1.1.1</hostid> can be used
+        as the <application>natd</application> 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 <hostid>A</hostid> and <hostid>B</hostid>.</para>
+
+      <para>The <option>-redirect_address</option> syntax is as follows:</para>
+
+      <programlisting>-redirect_address localIP publicIP</programlisting>
+
+
+      <informaltable frame="none" pgwide="1">
+        <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>
+
+      <programlisting>-redirect_address 192.168.0.2 128.1.1.2
+-redirect_address 192.168.0.3 128.1.1.3</programlisting>
+
+      <para>Like <option>-redirect_port</option>, these arguments are also placed within
+        the <literal>natd_flags=""</literal> option of <filename>/etc/rc.conf</filename>, or passed via a configuration file.  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 <application>natd</application> machine must be active and aliased
+        to the external interface.  Look at &man.rc.conf.5; to do so.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-plip">
+    <title>Parallel Line IP (PLIP)</title>
+
+    <indexterm><primary>PLIP</primary></indexterm>
+    <indexterm>
+      <primary>Parallel Line IP</primary>
+      <see>PLIP</see>
+    </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="network-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 frame="none">
+	<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="network-plip-setup">
+      <title>Setting Up PLIP</title>
+
+      <para>First, you have to get a laplink cable.
+	Then, confirm that both computers have a kernel with &man.lpt.4; driver
+	support:</para>
+
+      <screen>&prompt.root; <userinput>grep lp /var/run/dmesg.boot</userinput>
+lpt0: &lt;Printer&gt; on ppbus0
+lpt0: Interrupt-driven port</screen>
+
+      <para>The parallel port must be an interrupt driven port,
+	you should have lines similar to the
+	following in your in the
+	<filename>/boot/device.hints</filename> file:</para>
+
+      <programlisting>hint.ppc.0.at="isa"
+hint.ppc.0.irq="7"</programlisting>
+
+      <para>Then check if the kernel configuration file has a
+	<literal>device plip</literal> line or if the
+	<filename>plip.ko</filename> kernel module is loaded.  In both
+	cases the parallel networking interface should appear when you
+	use the &man.ifconfig.8; command to display it:</para>
+
+      <screen>&prompt.root; <userinput>ifconfig plip0</userinput>
+plip0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500</screen>
+
+      <para>Plug the laplink cable into the parallel interface on
+	both computers.</para>
+
+      <para>Configure the network interface parameters on both
+	sites as <username>root</username>.  For example, if you want to connect
+	the host <hostid>host1</hostid> with another machine <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 plip0 10.0.0.1 10.0.0.2</userinput></screen>
+
+      <para>Configure the interface on <hostid>host2</hostid> by doing:</para>
+
+      <screen>&prompt.root; <userinput>ifconfig plip0 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 plip0</userinput>
+plip0: 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          0       0       plip0
+&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="network-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>
+      <authorgroup>
+   <author>
+      <firstname>Brad</firstname>
+      <surname>Davis</surname>
+      <contrib>Extended 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 KAME 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 RFC1918 private address space
+	  (<hostid role="ipaddr">10.0.0.0/8</hostid>,
+	  <hostid role="ipaddr">172.16.0.0/12</hostid>, and
+	  <hostid role="ipaddr">192.168.0.0/16</hostid>)
+	  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 (<ulink
+	  url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>)</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>IPv6-to-IPv4 transition mechanisms</para>
+      </listitem>
+    </itemizedlist>
+
+
+    <para>For more information see:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>IPv6 overview at <ulink url="http://playground.sun.com/pub/ipng/html/ipng-main.html">playground.sun.com</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 <hostid role="ipaddr">xxx.xxx.xxx.255</hostid>) is expressed
+	  by multicast addresses in IPv6.</para></note>
+
+      <table frame="none">
+	<title>Reserved IPv6 addresses</title>
+
+	<tgroup cols="4">
+	  <thead>
+	    <row>
+	      <entry>IPv6 address</entry>
+	      <entry>Prefixlength (Bits)</entry>
+	      <entry>Description</entry>
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><hostid role="ip6addr">::</hostid></entry>
+	      <entry>128 bits</entry>
+	      <entry>unspecified</entry>
+	      <entry>cf. <hostid role="ipaddr">0.0.0.0</hostid> in
+		IPv4</entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid role="ip6addr">::1</hostid></entry>
+	      <entry>128 bits</entry>
+	      <entry>loopback address</entry>
+	      <entry>cf. <hostid role="ipaddr">127.0.0.1</hostid> in
+		IPv4</entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid
+		role="ip6addr">::00:xx:xx:xx:xx</hostid></entry>
+	      <entry>96 bits</entry>
+	      <entry>embedded IPv4</entry>
+	      <entry>The lower 32 bits are the IPv4 address.  Also
+		called <quote>IPv4 compatible IPv6
+		address</quote></entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid
+		role="ip6addr">::ff:xx:xx:xx:xx</hostid></entry>
+	      <entry>96 bits</entry>
+	      <entry>IPv4 mapped IPv6 address</entry>
+	      <entry>The lower 32 bits are the IPv4 address.
+		For hosts which do not support IPv6.</entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid role="ip6addr">fe80::</hostid> - <hostid
+		role="ip6addr">feb::</hostid></entry>
+	      <entry>10 bits</entry>
+	      <entry>link-local</entry>
+	      <entry>cf. loopback address in IPv4</entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid role="ip6addr">fec0::</hostid> - <hostid
+		role="ip6addr">fef::</hostid></entry>
+	      <entry>10 bits</entry>
+	      <entry>site-local</entry>
+	      <entry>&nbsp;</entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid role="ip6addr">ff::</hostid></entry>
+	      <entry>8 bits</entry>
+	      <entry>multicast</entry>
+	      <entry>&nbsp;</entry>
+	    </row>
+
+	    <row>
+	      <entry><hostid role="ip6addr">001</hostid> (base
+		2)</entry>
+	      <entry>3 bits</entry>
+	      <entry>global unicast</entry>
+	      <entry>All global unicast addresses are assigned from
+		this pool.  The first 3 bits are
+		<quote>001</quote>.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+    <sect2>
+      <title>Reading IPv6 Addresses</title>
+      <para>The canonical form is represented as: <hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, 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 one such substring per address can be abbreviated by <quote>::</quote>.
+	Also up to three leading <quote>0</quote>s per hexquad can be omitted.
+	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:0a00:0001</hostid>
+	which in turn is equivalent to
+	writing <hostid role="ip6addr">2002::a00: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 is generated from the MAC
+	address as part of the auto configuration.</para>
+
+      <para>For further information on the structure of IPv6 addresses
+	see <ulink
+	url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</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 (<ulink
+	    url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para>
+	</listitem>
+
+	<listitem>
+	  <para>Use the <filename role="package">net/freenet6</filename> 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 <ulink url="http://www.6bone.net/">6bone</ulink> 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 MY_IPv4_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable></userinput>
+&prompt.root; <userinput>ifconfig gif0 inet6 alias <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR MY_IPv6_REMOTE_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 <hostid role="ip6addr">ff02::1%gif0</hostid>.  You should receive two ping replies.</para>
+
+	<note><para>In case you are intrigued by the address <hostid role="ip6addr">ff02:1%gif0</hostid>, this is a
+	  multicast address.  <literal>%gif0</literal> states that the multicast address at network
+	  interface <devicename>gif0</devicename> 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 &mdash; that is if you have a IPv6 enabled browser such as
+	<filename role="package">www/mozilla</filename>, <application>Konqueror</application>,
+	which is part of <filename role="package">x11/kdebase3</filename>,
+	or <filename role="package">www/epiphany</filename>.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>DNS in the IPv6 World</title>
+
+      <para>There used to be two types of DNS records for IPv6.  The IETF
+	has declared A6 records obsolete.  AAAA records are the standard
+	now.</para>
+
+      <para>Using AAAA records is straightforward.  Assign your hostname to the new
+	IPv6 address you just received 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)
+	and <filename role="package">dns/djbdns</filename> (with the IPv6 patch)
+	support AAAA records.</para>
+    </sect2>
+
+    <sect2>
+      <title>Applying the needed changes to <filename>/etc/rc.conf</filename></title>
+
+      <sect3>
+	<title>IPv6 Client Settings</title>
+
+	<para>These settings will help you configure a machine that will be on
+	  your LAN and act as a client, not a router.  To have &man.rtsol.8;
+	  autoconfigure your interface on boot all you need to add is:</para>
+
+	<programlisting>ipv6_enable="YES"</programlisting>
+
+	<para>To statically assign an IP address such as <hostid role="ip6addr">
+	  2001:471:1f11:251:290:27ff:fee0:2093</hostid>, to your
+	  <devicename>fxp0</devicename> interface, add:</para>
+
+	<programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting>
+
+	<para>To assign a default router of
+	  <hostid role="ip6addr">2001:471:1f11:251::1</hostid>
+	  add the following to <filename>/etc/rc.conf</filename>:</para>
+
+	<programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting>
+
+      </sect3>
+
+      <sect3>
+	<title>IPv6 Router/Gateway Settings</title>
+
+	<para>This will help you take the directions that your tunnel provider,
+	  such as the <ulink url="http://www.6bone.net/">6bone</ulink>, has
+	  given you and convert it into settings that will persist through reboots.
+	  To restore your tunnel on startup use something like the following in
+	  <filename>/etc/rc.conf</filename>:</para>
+
+	<para>List the Generic Tunneling interfaces that will be configured, for
+	  example <devicename>gif0</devicename>:</para>
+
+	<programlisting>gif_interfaces="gif0"</programlisting>
+
+	<para>To configure the interface with a local endpoint of
+	  <replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint of
+	  <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para>
+
+	<programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>
+
+	<para>To apply the IPv6 address you have been assigned for use as your
+	  IPv6 tunnel endpoint, add:</para>
+
+	<programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
+
+	<para>Then all you have to do is set the default route for IPv6.  This is
+	  the other side of the IPv6 tunnel:</para>
+
+	<programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
+
+      </sect3>
+
+      <sect3>
+	<title>IPv6 Tunnel Settings</title>
+
+	<para>If the server is to route IPv6 between the rest of your network
+	  and the world, the following <filename>/etc/rc.conf</filename>
+	  setting will also be needed:</para>
+
+	<programlisting>ipv6_gateway_enable="YES"</programlisting>
+
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Router Advertisement and Host Auto Configuration</title>
+
+      <para>This section will help you setup &man.rtadvd.8; to advertise the
+	IPv6 default route.</para>
+
+      <para>To enable &man.rtadvd.8; you will need the following in your
+	<filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>rtadvd_enable="YES"</programlisting>
+
+      <para>It is important that you specify the interface on which to do
+	IPv6 router solicitation.  For example to tell &man.rtadvd.8; to use
+	<devicename>fxp0</devicename>:</para>
+
+      <programlisting>rtadvd_interfaces="fxp0"</programlisting>
+
+      <para>Now we must create the configuration file,
+	<filename>/etc/rtadvd.conf</filename>.  Here is an example:</para>
+
+      <programlisting>fxp0:\
+	:addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting>
+
+      <para>Replace <devicename>fxp0</devicename> with the interface you
+	are going to be using.</para>
+
+      <para>Next, replace <hostid role="ip6addr">2001:471:1f11:246::</hostid>
+	with the prefix of your allocation.</para>
+
+      <para>If you are dedicated a <hostid role="netmask">/64</hostid> subnet
+	you will not need to change anything else.  Otherwise, you will need to
+	change the <literal>prefixlen#</literal> to the correct value.</para>
+
+   </sect2>
+  </sect1>
+
+  <sect1 id="network-atm">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Harti</firstname>
+	  <surname>Brandt</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Asynchronous Transfer Mode (ATM)</title>
+
+    <sect2>
+      <title>Configuring classical IP over ATM (PVCs)</title>
+
+      <para>Classical IP over ATM (<acronym>CLIP</acronym>) is the
+	simplest method to use Asynchronous Transfer Mode (ATM)
+	with IP.  It can be used with
+	switched connections (SVCs) and with permanent connections
+	(PVCs).  This section describes how to set up a network based
+	on PVCs.</para>
+
+      <sect3>
+	<title>Fully meshed configurations</title>
+
+	<para>The first method to set up a <acronym>CLIP</acronym> with
+	  PVCs is to connect each machine to each other machine in the
+	  network via a dedicated PVC.  While this is simple to
+	  configure it tends to become impractical for a larger number
+	  of machines.  The example supposes that we have four
+	  machines in the network, each connected to the <acronym role="Asynchronous Transfer Mode">ATM</acronym> network
+	  with an <acronym role="Asynchronous Transfer Mode">ATM</acronym> adapter card.  The first step is the planning of
+	  the IP addresses and the <acronym role="Asynchronous
+	  Transfer Mode">ATM</acronym> connections between the
+	  machines.  We use the following:</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+	    <colspec colwidth="1*">
+	    <colspec colwidth="1*">
+	    <thead>
+	      <row>
+		<entry>Host</entry>
+		<entry>IP Address</entry>
+	      </row>
+	    </thead>
+
+	    <tbody>
+	      <row>
+		<entry><hostid>hostA</hostid></entry>
+		<entry><hostid role="ipaddr">192.168.173.1</hostid></entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostB</hostid></entry>
+		<entry><hostid role="ipaddr">192.168.173.2</hostid></entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostC</hostid></entry>
+		<entry><hostid role="ipaddr">192.168.173.3</hostid></entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostD</hostid></entry>
+		<entry><hostid role="ipaddr">192.168.173.4</hostid></entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+
+	<para>To build a fully meshed net we need one ATM connection
+	  between each pair of machines:</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+	    <colspec colwidth="1*">
+	    <colspec colwidth="1*">
+	    <thead>
+	      <row>
+		<entry>Machines</entry>
+		<entry>VPI.VCI couple</entry>
+	      </row>
+	    </thead>
+
+	    <tbody>
+	      <row>
+		<entry><hostid>hostA</hostid> - <hostid>hostB</hostid></entry>
+		<entry>0.100</entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostA</hostid> - <hostid>hostC</hostid></entry>
+		<entry>0.101</entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostA</hostid> - <hostid>hostD</hostid></entry>
+		<entry>0.102</entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostB</hostid> - <hostid>hostC</hostid></entry>
+		<entry>0.103</entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostB</hostid> - <hostid>hostD</hostid></entry>
+		<entry>0.104</entry>
+	      </row>
+
+	      <row>
+		<entry><hostid>hostC</hostid> - <hostid>hostD</hostid></entry>
+		<entry>0.105</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+
+	<para>The VPI and VCI values at each end of the connection may
+	  of course differ, but for simplicity we assume that they are
+	  the same.  Next we need to configure the ATM interfaces on
+	  each host:</para>
+
+	<screen>hostA&prompt.root; <userinput>ifconfig hatm0 192.168.173.1 up</userinput>
+hostB&prompt.root; <userinput>ifconfig hatm0 192.168.173.2 up</userinput>
+hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput>
+hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen>
+
+	<para>assuming that the ATM interface is
+	  <devicename>hatm0</devicename> on all hosts.  Now the PVCs
+	  need to be configured on <hostid>hostA</hostid> (we assume that
+	  they are already configured on the ATM switches, you need to
+	  consult the manual for the switch on how to do this).</para>
+
+	<screen>hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr</userinput>
+hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr</userinput>
+hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr</userinput>
+
+hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr</userinput>
+hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr</userinput>
+hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr</userinput>
+
+hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr</userinput>
+hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr</userinput>
+hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr</userinput>
+
+hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr</userinput>
+hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr</userinput>
+hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</userinput></screen>
+
+	<para>Of course other traffic contracts than UBR can be used
+	  given the ATM adapter supports those.  In this case the name
+	  of the traffic contract is followed by the parameters of the
+	  traffic.  Help for the &man.atmconfig.8; tool can be
+	  obtained with:</para>
+
+	<screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen>
+
+	<para>or in the &man.atmconfig.8; manual page.</para>
+
+	<para>The same configuration can also be done via
+	  <filename>/etc/rc.conf</filename>.
+	  For <hostid>hostA</hostid> this would look like:</para>
+
+<programlisting>network_interfaces="lo0 hatm0"
+ifconfig_hatm0="inet 192.168.173.1 up"
+natm_static_routes="hostB hostC hostD"
+route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr"
+route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr"
+route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting>
+
+	<para>The current state of all <acronym>CLIP</acronym> routes
+	  can be obtained with:</para>
+
+	<screen>hostA&prompt.root; <userinput>atmconfig natm show</userinput></screen>
+      </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:
+-->
+<!--  LocalWords:  config mnt www -->
diff --git a/pl_PL.ISO8859-2/books/handbook/appendix.decl b/pl_PL.ISO8859-2/books/handbook/appendix.decl
new file mode 100644
index 0000000000..ddd974539b
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/appendix.decl
@@ -0,0 +1,2 @@
+<!-- $FreeBSD$ -->
+<!DOCTYPE appendix PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN">
diff --git a/pl_PL.ISO8859-2/books/handbook/audit/Makefile b/pl_PL.ISO8859-2/books/handbook/audit/Makefile
new file mode 100644
index 0000000000..84cb9b04ee
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/audit/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	audit/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/audit/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/audit/chapter.sgml
new file mode 100644
index 0000000000..e2455e6a3a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/audit/chapter.sgml
@@ -0,0 +1,570 @@
+<!--
+     The FreeBSD Documentation Project
+     $FreeBSD$
+-->
+
+<!-- Need more documentation on praudit, auditreduce, etc.  Plus more info
+on the triggers from the kernel (log rotation, out of space, etc).
+And the /dev/audit special file if we choose to support that.  Could use
+some coverage of integrating MAC with Event auditing and perhaps discussion
+on how some companies or organizations handle auditing and auditing
+requirements. -->
+
+<chapter id="audit">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Written by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Security Event Auditing</title>
+
+  <sect1 id="audit-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm><primary>AUDIT</primary></indexterm>
+    <indexterm>
+      <primary>Security Event Auditing</primary>
+      <see>MAC</see>
+    </indexterm>
+
+    <para>The &os;&nbsp;7-CURRENT development branch includes
+      support for Event Auditing based on the &posix;.1e draft and
+      Sun's published <acronym>BSM</acronym> API and file format.
+      Event auditing permits the selective logging of security-relevant
+      system events for the purposes of post-mortem analysis, system
+      monitoring, and intrusion detection.  After some settling time in
+      &os;&nbsp;7-CURRENT, this support will be merged to &os;&nbsp;6-STABLE
+      and appear in subsequent releases.</para>
+
+    <warning>
+      <para>The audit facility in FreeBSD is considered experimental, and
+	production deployment should occur only after careful consideration
+	of the risks of deploying experimental software.</para>
+    </warning>
+
+    <para>This chapter will focus mainly on the installation and
+      configuration of Event Auditing.  Explanation of audit policies,
+      and an example configuration will be provided for the
+      convenience of the reader.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>What Event Auditing is and how it works.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure Event Auditing on &os; for users
+	  and processes.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand &unix; and &os; basics
+	  (<xref linkend="basics">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Be familiar with the basics of kernel
+	  configuration/compilation
+	  (<xref linkend="kernelconfig">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Have some familiarity with security and how it
+	  pertains to &os; (<xref linkend="security">).</para>
+      </listitem>
+    </itemizedlist>
+
+    <warning>
+      <para>Event auditing can generate a great deal of log file
+	data, exceeding gigabytes a week in some configurations.  An
+	administrator should read this chapter in its entirety to avoid
+	possible self-inflicted <acronym>DoS</acronym> attacks due to
+	improper configuration.</para>
+    </warning>
+
+    <para>The implementation of Event Auditing in &os; is similar to
+      that of the &sun; Basic Security Module, or <acronym>BSM</acronym>
+      library.  Thus, the configuration is almost completely
+      interchangeable with &solaris; and Mac OS X/Darwin operating
+      systems.</para>
+  </sect1>
+
+  <sect1 id="audit-inline-glossary">
+    <title>Key Terms - Words to Know</title>
+
+    <para>Before reading this chapter, a few key terms must be
+      explained.  This is intended to clear up any confusion that
+      may occur and to avoid the abrupt introduction of new terms
+      and information.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><emphasis>event</emphasis>: An auditable event is
+	  an event that can be logged using the audit subsystem.  The
+	  administrator can configure which events will be audited.
+	  Examples of security-relevant events include the creation of
+	  a file, the building of a network connection, or the logging
+	  in of a user.  Events are either <quote>attributable</quote>,
+	  meaning that they can be traced back to a user
+	  authentication, or <quote>non-attributable</quote>.  Examples
+	  of non-attributable events are any events that occur before
+	  authentication has succeeded in the login process, such as
+	  failed authentication attempts.</para>
+      </listitem>
+
+      <listitem>
+        <para><emphasis>class</emphasis>: Events may be assigned to
+	  one or more classes, usually based on the general category
+	  of the events, such as <quote>file creation</quote>,
+	  <quote>file access</quote>, or <quote>network</quote>.  Login
+	  and logout events are assigned to the <literal>lo</literal>
+	  class.  The use of classes allows the administrator to
+	  specify high level auditing rules without having to specify
+	  whether each individual auditable operation will be logged.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>record</emphasis>: A record is a log entry
+	  describing a security event.  Records typically have a
+	  record event type, information on the subject (user) associated
+	  with the event, time information, information on any objects,
+	  such as files, and information on whether the event corresponded
+	  to a successful operation.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>trail</emphasis>: An audit trail, or log file,
+	  consists of a series of audit records describing security
+	  events.  Typically, trails are in roughly chronological
+	  order with respect to the time events completed.  Only
+	  authorized processes are allowed to commit records to the
+	  audit trail.</para>
+
+      <listitem>
+	<para><emphasis>prefix</emphasis>: A prefix is considered to
+	  be the configuration element used to toggle auditing for
+	  success and failed events.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="audit-install">
+    <title>Installing Audit Support</title>
+
+    <para>Support for Event Auditing is installed with
+      the normal <maketarget>installworld</maketarget> process.  An
+      administrator may confirm this by viewing the contents
+      of <filename role="directory">/etc/security</filename>.  Files
+      beginning with the word <emphasis>audit</emphasis> should be present.
+      For example, <filename>audit_event</filename>.</para>
+
+    <para>In-kernel support for the framework must also exist.  This
+      may be done by adding the following lines to the local kernel
+      configuration file:</para>
+
+    <programlisting>options	AUDIT</programlisting>
+
+    <para>Rebuild and reinstall
+      the kernel via the normal process explained in
+      <xref linkend="kernelconfig">.</para>
+
+    <para>Once completed, enable the audit daemon by adding the
+      following line to &man.rc.conf.5;:</para>
+
+    <programlisting>auditd_enable="YES"</programlisting>
+
+    <para>Functionality not provided by the default may be added
+      here with the <option>auditd_flags</option> option.</para>
+  </sect1>
+
+  <sect1 id="audit-config">
+    <title>Audit Configuration</title>
+
+    <para>All configuration files for security audit are found in
+      <filename role="directory">/etc/security</filename>.  The following
+      files must be present before the audit daemon is started:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><filename>audit_class</filename> - Contains the
+	  definitions of the audit classes.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_control</filename> - Controls aspects
+	  of the audit subsystem, such as default audit classes,
+	  minimum disk space to leave on the audit log volume,
+	  etc.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_event</filename> - Defines the kernel
+	  audit events.  These map, mostly, to system calls.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_user</filename> - The events to audit
+	  for individual users.  Users not appearing here will be
+	  subject to the default configuration in the control
+	  configuration file.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_warn</filename> - A shell script
+	  used by auditd to generate warning messages in
+	  exceptional situations, such as when space for audit
+	  records is running low.</para>
+      </listitem>
+    </itemizedlist>
+
+    <sect2>
+      <title>Audit File Syntax</title>
+
+      <para>The configuration file syntax is rather arcane, albeit easy
+	to work with.  One thing an administrator must be leery about
+	is overriding system defaults.  This could create potential
+	openings for audit data to not be collected properly.</para>
+
+      <para>The audit subsystem will accept both the short name and
+	long name with regards to configuration syntax.  A syntax
+	map has been included below.</para>
+
+      <para>The following list contains all supported audit
+	classes:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><option>all</option> - <literal>all</literal> - All
+	    audit flags set.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ad</option> - <literal>administrative</literal>
+	    - Administrative actions performed on the system as a
+	    whole.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ap</option> - <literal>application</literal> -
+	    Application defined action.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>cl</option> - <literal>file_close</literal> -
+	    Audit calls to the <function>close</function> system
+	    call.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ex</option> - <literal>exec</literal> - Audit
+	    program or utility execution.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fa</option> - <literal>file_attr_acc</literal>
+	    - Audit the access of object attributes such as
+	    &man.stat.1;, &man.pathconf.2; and similar events.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fc</option> - <literal>file_creation</literal>
+	    - Audit events where a file is created as a result.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fd</option> - <literal>file_deletion</literal>
+	    - Audit events where file deletion occurs.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fm</option> - <literal>file_attr_mod</literal>
+	    - Audit events where file attribute modification occurs,
+	    such as &man.chown.8;, &man.chflags.1;, &man.flock.2;,
+	    etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fr</option> - <literal>file_read</literal>
+	    - Audit events in which data is read, files are opened for
+	    reading, etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fw</option> - <literal>file_write</literal> -
+	    Audit events in which data is written, files are written
+	    or modified, etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>io</option> - <literal>ioctl</literal> - Audit
+	    use of the &man.ioctl.2; system call.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ip</option> - <literal>ipc</literal> - Audit
+	    various forms of Inter-Process Communication, including POSIX
+	    pipes and System V <acronym>IPC</acronym> operations.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>lo</option> - <literal>login_logout</literal> -
+	    Audit &man.login.1; and &man.logout.1; events occurring
+	    on the system.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>na</option> - <literal>non_attrib</literal> -
+	    Audit non-attributable events.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>no</option> - <literal>no_class</literal> -
+	    Null class used to disable event auditing.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>nt</option> - <literal>network</literal> -
+	    Audit events related to network actions, such as
+	    &man.connect.2; and &man.accept.2;.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ot</option> - <literal>other</literal> -
+	    Audit miscellaneous events.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>pc</option> - <literal>process</literal> -
+	    Audit process operations, such as &man.exec.3; and
+	    &man.exit.3;.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Following is a list of all supported audit prefixes:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><literal>none</literal> - Audit both the success
+	    or failure of an event.  For example, just listing a
+	    class will result in the auditing of both success and
+	    failure.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>+</literal> - Audit successful events
+	    only.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>-</literal> - Audit failed events
+	    only.</para>
+	</listitem>
+      </itemizedlist>
+
+      <warning>
+	<para>Using the <option>all</option> class with either the
+	  positive or negative prefix can generate a large amount
+	  of data at an extremely rapid rate.</para>
+      </warning>
+
+      <para>Extra prefixes used to modify the default configuration
+	values:</para>
+<!-- XXX: Perhaps a variable listing here. -->
+      <itemizedlist>
+	<listitem>
+	  <para>^- - Disable auditing of failed events.</para>
+	</listitem>
+
+	<listitem>
+	  <para>^+ - Enable auditing of successful events.</para>
+	</listitem>
+
+	<listitem>
+	  <para>^ - Disable auditing of both successful and failed
+	    events.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Configuration Files</title>
+
+      <para>In most cases, administrators will need to modify only two files
+	when configuring the audit system: <filename>audit_control</filename>
+	and <filename>audit_user</filename>.  The first controls system-wide
+	audit paramaters and defaults for both attributable and
+	non-attributable events.  The second may be used to tune the level
+	and nature of auditing for individual users.</para>
+
+      <sect3 id="audit-auditcontrol">
+        <title>The <filename>audit_control</filename> File</title>
+
+	<para>The <filename>audit_control</filename> file contains some basic
+	  defaults that the administrator may wish to modify.  Perhaps
+	  even set some new ones.  Viewing the contents of this file,
+	  we see the following:</para>
+
+	<programlisting>dir:/var/audit
+flags:lo
+minfree:20
+naflags:lo</programlisting>
+
+	<para>The <option>dir</option> option is used to set the default
+	  directory where audit logs are stored.  Audit is frequently
+	  configured so that audit logs are stored on a dedicated file
+	  system, so as to prevent interference between the audit
+	  subsystem and other subsystems when file systems become full.
+	  </para>
+
+	<para>The <option>flags</option> option is used to set the
+	  system-wide defaults.  The current setting, <option>lo</option>
+	  configures the auditing of all &man.login.1; and &man.logout.1;
+	  actions.  A more complex example,
+	  <option>lo,ad,-all,^-fa,^-fc,^-cl</option> audits all system
+	  &man.login.1; and &man.logout.1; actions, all administrator
+	  actions, all failed events in the system, and finally disables
+	  auditing of failed attempts for <option>fa</option>,
+	  <option>fc</option>, and <option>cl</option>.  Even though
+	  the <option>-all</option> turned on the auditing of all
+	  failed attempts, the <option>^-</option> prefix will override
+	  that for the latter options.</para>
+
+	<para>Notice that the previous paragraph shows the file is
+	  read from left to right.  As such, values further on the
+	  right side may override a previous value specified to
+	  its left.</para>
+
+	<para>The <option>minfree</option> option defines the minimum
+	  percentage of free space for audit file systems.  This
+	  relates to the file system where audit logs are stored.
+	  For example, if the <option>dir</option> specifies
+	  <filename role="directory">/var/audit</filename> and
+	  <option>minfree</option> is set to twenty (20), warning
+	  messages will be generated when the
+	  <filename role="directory">/var</filename> file system grows
+	  to eighty (80) percent full.</para>
+
+	<para>The <option>naflags</option> option specifies audit
+	  classes to be audited for non-attributed events &mdash;
+	  that is, events for which there is no authenticated user.
+	  </para>
+      </sect3>
+
+      <sect3 id="audit-audituser">
+	<title>The <filename>audit_user</filename> File</title>
+
+	<para>The <filename>audit_user</filename> file permits the
+	  administrator to determine which classes of audit events
+	  should be logged for which system users.</para>
+
+	<para>The following is the defaults currently placed in
+	  the <filename>audit_user</filename> file:</para>
+
+	<programlisting>root:lo:no
+audit:fc:no</programlisting>
+
+	<para>Notice how the default is to audit all cases of
+	  <command>login</command>/<command>logout</command>
+	  and disable auditing of all other actions for
+	  <username>root</username>.  This configuration
+	  also audits all file creation and disables all
+	  other auditing for the <username>audit</username>
+	  user.  While event auditing does not require a special
+	  user exist, some configurations, specifically environments
+	  making use of <acronym>MAC</acronym>, may require it.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="audit-administration">
+    <title>Event Audit Administration</title>
+
+    <para>Events written by the kernel audit subsystem cannot
+      be altered or read in plain text.  Data is stored and accessed
+      in a method similar to that of &man.ktrace.1; and &man.kdump.1;,
+      that is, they may only be viewed by dumping them using the
+      <command>praudit</command> command; audit trails may be reduced
+      using the <command>auditreduce</command> command, which selects
+      records from an audit trail based on properties of interest, such
+      as the user, time of the event, and type of operation.</para>
+
+    <para>For example, the <command>praudit</command> utility will dump the
+      entire contents of a specified audit log in plain text.  To dump an
+      audit log in its entirety, use:</para>
+
+    <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen>
+
+    <para>Where <replaceable>AUDITFILE</replaceable> is the audit log
+      of viewing choice.  Since audit logs may contain enormous
+      amounts of data, an administrator may prefer to select records
+      for specific users.  This is made possible with the following
+      command, where <username>trhodes</username> is the user of
+      choice:</para>
+
+    <screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE | praudit</userinput></screen>
+
+    <para>This will select all audit records produced by the user
+      <username>trhodes</username> stored in the
+      <replaceable>AUDITFILE</replaceable> file.</para>
+
+    <para>There are several other options available for reading audit
+      records, see the aforementioned command's manual pages for
+      a more in depth explanation.</para>
+
+    <sect2>
+      <title>Rotating Audit Log Files</title>
+
+      <para>Due to log reliability requirements, audit trails
+	are written to only by the kernel, and managed only by
+	<command>auditd</command>.  Administrators should not
+	attempt to use &man.newsyslog.conf.5; or other tools to
+	directly rotate audit logs.  Instead, the <command>audit</command>
+	management tool should be used to shut down auditing,
+	reconfigure the audit system, and perform log rotation.
+	The following command causes the audit daemon to create a
+	new audit log and signal the kernel to switch to using the
+	new log.  The old log will be terminated and renamed, at
+	which point it may then be manipulated by the administrator.</para>
+
+      <screen>&prompt.root; <userinput>audit -n</userinput></screen>
+
+      <warning>
+	<para>If the <command>auditd</command> daemon is not currently
+	  running, the previous command will fail and an error message
+	  will be produced.</para>
+      </warning>
+
+      <para>Adding the following line to
+	<filename>/etc/crontab</filename> will force the rotation
+	every twelve hours from &man.cron.8;:</para>
+
+      <programlisting>*     */12       *       *       *       root    /usr/sbin/audit -n</programlisting>
+
+      <para>The change will take effect once you have saved the
+	new <filename>/etc/crontab</filename>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Delegating Audit Review Rights</title>
+
+      <para>By default, only the root user has the right to read system audit
+	logs.  However, that right may be delegated to members of the
+	<literal>audit</literal> group, as the audit directory and audit
+	trail files are assigned to that group, and made group-readable.  As
+	the ability to track audit log contents provides significant insight
+	into the behavior of users and processes, it is recommended that the
+	delegation of audit review rights be performed with caution.</para>
+    </sect2>
+  </sect1>
+</chapter>
diff --git a/pl_PL.ISO8859-2/books/handbook/basics/Makefile b/pl_PL.ISO8859-2/books/handbook/basics/Makefile
new file mode 100644
index 0000000000..fea6942368
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	basics/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/basics/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/basics/chapter.sgml
new file mode 100644
index 0000000000..95ab39cf42
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/chapter.sgml
@@ -0,0 +1,2585 @@
+<!--
+     The FreeBSD Polish Documentation Project
+
+     $FreeBSD$
+     Original revision: 1.145
+-->
+
+<chapter id="basics">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+        <firstname>Chris</firstname>
+	<surname>Shumway</surname>
+        <contrib>Rozdzia³ na nowo napisa³ </contrib>
+      </author>
+    </authorgroup>
+    <!-- 10 Mar 2000 -->
+    <authorgroup>
+      <author>
+        <firstname>Micha³</firstname>
+        <surname>Wojciechowski</surname>
+        <contrib>T³umaczy³ </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Podstawy Uniksa</title>
+  
+  <sect1 id="basics-synopsis">
+    <title>Strzeszczenie</title>
+
+    <para>W niniejszym rozdziale omówione zostan± podstawowe polecenia
+      i mo¿liwo¶ci systemu operacyjnego FreeBSD. Wiele informacji dotyczyæ
+      bêdzie ogó³em systemów typu &unix;. Czytelnikom zaznajomionym z t±
+      tematyk± w zupe³no¶ci wystarczy pobie¿ne przejrzenie rozdzia³u.
+      Natomiast ci, którzy dopiero rozpoczynaj± swoj± przygodê z FreeBSD,
+      powinni przeczytaæ go bardzo uwa¿nie.</para>
+
+    <para>Po przeczytaniu tego rozdzia³u bêdziemy wiedzieæ:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Jak korzystaæ z <quote>konsol wirtualnych</quote> FreeBSD.</para>
+      </listitem>
+      <listitem>
+        <para>Jak dzia³aj± prawa dostêpu do plików i flagi plików we &os;.</para>
+      </listitem>
+      <listitem>
+        <para>Jaki jest domy¶lny uk³ad systemu plików &os;.</para>
+      </listitem>
+      <listitem>
+        <para>Jaka jest organizacja dysku we &os;.</para>
+      </listitem>
+      <listitem>
+        <para>Jak montowaæ i odmontowywaæ systemy plików.</para>
+      </listitem>
+      <listitem>
+        <para>Czym s± procesy, demony i sygna³y.</para>
+      </listitem>
+      <listitem>
+        <para>Co to jest pow³oka, oraz jak mo¿na zmieniæ w³asne ¶rodowisko pracy.</para>
+      </listitem>
+      <listitem>
+        <para>Jak pos³ugiwaæ siê prostymi edytorami tekstu.</para>
+      </listitem>
+      <listitem>
+        <para>Jaki jest zwi±zek pomiêdzy urz±dzeniami i plikami wêz³owymi urz±dzeñ.</para>
+      </listitem>
+      <listitem>
+        <para>Jaki format binarny jest wykorzystywany we &os;.</para>
+      </listitem>
+      <listitem>
+        <para>W jaki sposób korzystaæ z dokumentacji systemowej w poszukiwaniu dodatkowych informacji.</para>
+      </listitem>
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="consoles">
+    <title>Konsole wirtualne i terminale</title>
+    <indexterm><primary>konsole wirtualne</primary></indexterm>
+    <indexterm><primary>terminale</primary></indexterm>
+
+    <para>Z systemu FreeBSD korzystaæ mo¿na na ró¿ne sposoby; jednym z
+      nich jest wpisywanie poleceñ w terminalu tekstowym. Wiêkszo¶æ
+      systemów operacyjnych typu &unix; dostêpna jest w³a¶nie poprzez polecenia.
+      W niniejszej czê¶ci dowiemy siê, czym s± <quote>terminale</quote> i
+      <quote>konsole</quote>, oraz jak siê nimi pos³ugiwaæ we FreeBSD.</para>
+
+    <sect2 id="consoles-intro">
+      <title>Konsola</title>
+      <indexterm><primary>konsola</primary></indexterm>
+
+      <para>Je¶li konfiguruj±c FreeBSD nie wybrali¶my, by przy
+        uruchamianiu systemu by³o automatycznie ³adowane ¶rodowisko
+        graficzne, to po uruchomieniu i wykonaniu skryptów startowych
+        system przywita nas komunikatem logowania siê do systemu.
+        Zobaczymy mniej wiêcej co¶ takiego:</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>Na ró¿nych komputerach komunikat ten mo¿e wygl±daæ nieco inaczej,
+        jednak z pewno¶ci± bêdzie podobny. W tej chwili interesuj± nas jego dwa
+        ostatnie wiersze. Wiersz drugi od koñca ma postaæ:</para>
+
+      <programlisting>FreeBSD/i386 (pc3.example.org) (ttyv0)</programlisting>
+
+      <para>Widaæ tu kilka informacji o systemie, który w³a¶nie zosta³
+        uruchomiony. Mamy przed oczami konsolê <quote>FreeBSD</quote>,
+        dzia³aj±c± na komputerze z procesorem firmy Intel (lub kompatybilnym)
+        z rodziny x86<footnote>
+          <para>Takie jest znaczenie symbolu <literal>i386</literal>. Zwróæmy
+            uwagê, ¿e nawet wówczas, gdy FreeBSD dzia³a na procesorze Intela
+            innym ni¿ 386, w tym miejscu znajdzie siê napis <literal>i386</literal>.
+            Nie okre¶la on bowiem typu u¿ywanego procesora, lecz jego
+            <quote>architekturê</quote>.</para>
+        </footnote>.  Komputer ten zosta³ nazwany (ka¿dy komputer uniksowy
+        ma nazwê) <hostid>pc3.example.org</hostid> i w tej chwili widoczna
+        jest jego konsola systemowa &mdash; terminal
+        <devicename>ttyv0</devicename>.</para>
+
+      <para>Ostatni wiersz ma zawsze tak± postaæ:</para>
+
+      <programlisting>login:</programlisting>
+
+      <para>Tu wpisujemy <quote>nazwê u¿ytkownika</quote>, by zalogowaæ
+        siê do systemu.  Opis tej czynno¶ci przedstawiony jest w kolejnej
+        czê¶ci.</para>
+    </sect2>
+
+    <sect2 id="consoles-login">
+      <title>Logowanie siê do FreeBSD</title>
+
+      <para>FreeBSD jest systemem wielou¿ytkownikowym i wielozadaniowym.
+        Tak oficjalnie okre¶la siê system, z którego na jednym komputerze
+        mo¿e korzystaæ wiele ró¿nych osób, uruchamiaj±c jednocze¶nie wiele
+        programów.</para>
+
+      <para>Ka¿dy system wielou¿ytkownikowy musi mieæ mo¿liwo¶æ
+        odró¿nienia jednego <quote>u¿ytkownika</quote> od pozosta³ych.
+        FreeBSD (i wszystkie systemy uniksopodobne) wymaga, aby u¿ytkownik
+        <quote>zalogowa³ siê</quote> do systemu, zanim bêdzie móg³
+        uruchamiaæ programy. Ka¿dy u¿ytkownik ma niepowtarzaln± nazwê
+        (<quote>nazwê u¿ytkownika</quote>) oraz sobie tylko znany klucz
+        (<quote>has³o</quote>). FreeBSD wymaga wpisania jednego i drugiego,
+        zanim zezwoli u¿ytkownikowi na uruchamianie jakichkolwiek
+        programów.</para>
+
+      <indexterm><primary>skrypty startowe</primary></indexterm>
+      <para>Zaraz po za³adowaniu systemu i zakoñczeniu uruchamiania
+        skryptów startowych<footnote>
+          <para>Skrypty startowe to programy uruchamiane automatycznie
+            podczas ³adowania FreeBSD. Ich podstawowym zadaniem jest
+            przygotowanie ¶rodowiska pracy dla innych programów, oraz
+            uruchomienie wybranych us³ug dzia³aj±cych w tle, pe³ni±cych
+            ró¿ne przydatne funkcje.</para>
+        </footnote>, FreeBSD wy¶wietli komunikat z pro¶b± o podanie nazwy
+        u¿ytkownika:</para>
+
+      <screen>login:</screen>
+
+      <para>Dla przyk³adu za³ó¿my, ¿e nasz u¿ytkownik nazywa siê
+        <username>janek</username>. Wpisujemy tutaj <literal>janek</literal>
+        i naciskamy <keycap>Enter</keycap>. Powinni¶my zostaæ poproszeni
+        o podanie <quote>has³a</quote>:</para>
+
+      <screen>login: <userinput>janek</userinput>
+Password:</screen>
+
+      <para>Nastêpnie wpisujemy has³o <username>janka</username>, i naciskamy
+        <keycap>Enter</keycap>. Has³o <emphasis>nie pojawia siê!</emphasis>
+        Na razie nie bêdziemy siê tym zajmowaæ. Wystarczy wiedzieæ, ¿e dzieje
+        siê tak ze wzglêdów bezpieczeñstwa.</para>
+
+      <para>Je¶li podali¶my prawid³owe has³o, powinni¶my byæ ju¿ zalogowani
+        do FreeBSD, i gotowi do eksperymentowania z dostêpnymi poleceniami.</para>
+
+      <para>Powinni¶my zobaczyæ wiadomo¶æ dnia (ang. message of the day
+        <acronym>MOTD</acronym>) oraz znak zachêty (<literal>#</literal>,
+        <literal>$</literal> b±d¼ <literal>%</literal>). Oznacza to, ¿e
+        uda³o nam siê zalogowaæ do FreeBSD.</para>
+    </sect2>
+
+    <sect2 id="consoles-virtual">
+      <title>Konsole wirtualne</title>
+
+      <para>Polecenia uniksowe mo¿na z powodzeniem wpisywaæ na jednej konsoli,
+        jednak FreeBSD potrafi wykonywaæ wiele programów jednocze¶nie.
+        Korzystanie z jednej konsoli do wydawania poleceñ zakrawa na marnotrawstwo,
+        poniewa¿ system zdolny jest obs³u¿yæ w jednej chwili ca³e mnóstwo programów.
+        W wykorzystaniu tej mo¿liwo¶ci bardzo pomocne s± <quote>konsole
+        wirtualne</quote>.</para>
+
+      <para>Konfiguruj±c FreeBSD mo¿emy uaktywniæ wiele konsol wirtualnych.
+        Z dowolnej z nich mo¿emy siê prze³±czyæ na inn± naciskaj±c odpowiedni±
+        kombinacjê klawiszy. Ka¿da konsola ma w³asny kana³ wyj¶ciowy, FreeBSD
+        zajmuje siê odpowiednim przekazywaniem informacji wprowadzanych z
+        klawiatury i wypisywanych na ekranie, gdy dochodzi do prze³±czenia
+        konsoli na inn±.</para>
+
+      <para>Pewne kombinacje klawiszy u¿ywane s± do przechodzenia miêdzy
+        konsolami<footnote>
+          <para>Szczegó³owy opis obecnych we FreeBSD sterowników konsoli
+            i klawiatury mo¿na znale¼æ w dokumentacji systemowej
+            &man.syscons.4;, &man.atkbd.4;, &man.vidcontrol.1; i &man.kbdcontrol.1;.
+            Nie bêdziemy tutaj zajmowaæ siê szczegó³ami, zainteresowani
+            czytelnicy s± jak najbardziej zachêcani do zapoznania siê z
+            dokumentacj± systemow±, w której omawiane teraz zagadnienia opisane
+            s± dok³adniej.</para>
+        </footnote>.  Kombinacje
+        <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>,
+        <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, a¿ do
+        <keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo> s³u¿± do
+        prze³±czania na kolejn± konsolê wirtualn±.</para>
+
+      <para>Przechodz±c z jednej konsoli na inn±, FreeBSD zajmuje siê
+        zachowaniem i odtworzeniem wygl±du ekranu. W efekcie otrzymujemy
+        <quote>z³udzenie</quote> posiadania wielu <quote>wirtualnych</quote>
+        ekranów i klawiatur, które mog± s³u¿yæ do wydawania poleceñ systemowi
+        FreeBSD. Programy uruchomione na jednej z konsol nie przerywaj± swej
+        pracy, gdy ta konsola przestaje byæ widoczna &mdash; po przej¶ciu na
+        inn± konsolê wirtualn± programy kontynuuj± swoje dzia³anie.</para>
+    </sect2>
+
+    <sect2 id="consoles-ttys">
+      <title>Plik <filename>/etc/ttys</filename></title>
+
+      <para>Zgodnie z domy¶ln± konfiguracj± FreeBSD uruchamia osiem konsol
+        wirtualnych. Nie jest to jednak permanentne ustawienie, i mo¿e
+        byæ w ³atwy sposób zmienione, aby konsol wirtualnych by³o wiêcej
+        lub mniej. Plik <filename>/etc/ttys</filename> odpowiedzialny jest
+        za liczbê konsol wirtualnych i ich konfiguracjê.</para>
+
+      <para>Modyfikuj±c plik <filename>/etc/ttys</filename> mo¿emy zmieniaæ
+        konfiguracjê konsol wirtualnych FreeBSD. Ka¿dy nie bêd±cy komentarzem
+        wiersz tego pliku (czyli wiersz nie rozpoczynaj±cy siê znakiem
+        <literal>#</literal>) zawiera ustawienia jednego z terminali lub
+        konsoli wirtualnej. W domy¶lnej wersji tego pliku wystêpuj±cej
+        we FreeBSD skonfigurowanych jest 9 konsol wirtualnych, przy czym 8
+        z nich jest w³±czonych. Za ich konfiguracjê odpowiadaj± wiersze
+        rozpoczynaj±ce siê symbolem <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>Dok³adny opis poszczególnych kolumn tego pliku i opcji,
+        za pomoc± których konfiguruje siê konsole wirtualne, znale¼æ
+        mo¿na w dokumentacji systemowej &man.ttys.5;.</para>
+    </sect2>
+
+    <sect2 id="consoles-singleuser">
+      <title>Konsola trybu jednego u¿ytkownika</title>
+
+      <para><quote>Tryb jednego u¿ytkownika</quote> szczegó³owo
+        opisuje <xref linkend="boot-singleuser">. Istotne jest, ¿e w trybie
+          jednego u¿ytkownika dostêpna jest tylko jedna konsola. Nie jest
+          mo¿liwe korzystanie z konsol wirtualnych. Konfiguracja konsoli
+          trybu jednego u¿ytkownika równie¿ znajduje siê w pliku
+          <filename>/etc/ttys</filename>. Odpowiada jej wiersz rozpoczynaj±cy
+          siê s³owem <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>Zgodnie z informacj± zawart± w komentarzu nad wierszem
+          <literal>console</literal>, wiersz ten mo¿na zmodyfikowaæ,
+          zmieniaj±c parametr <literal>secure</literal> na
+          <literal>insecure</literal>. Je¶li tak zrobimy, FreeBSD
+          po uruchomieniu w trybie jednego u¿ytkownika bêdzie pytaæ
+          o has³o u¿ytkownika <username>root</username>.</para>
+
+        <para><emphasis>Zachowajmy jednak ostro¿no¶æ, je¶li wpisujemy tu
+          <literal>insecure</literal></emphasis>. Je¿eli zdarzy siê nam
+          zapomnieæ has³a u¿ytkownika <username>root</username>, mo¿e
+          okazaæ siê potrzebne uruchomienie trybu jednego u¿ytkownika.
+          Bêdzie to nadal mo¿liwe, mo¿e jednak byæ nieco trudne dla osób
+          nie orientuj±cych siê w procesie uruchamiania FreeBSD i
+          uczestnicz±cych w nim programach.</para>
+      </note>
+    </sect2>
+  </sect1>
+
+  <sect1 id="permissions">
+    <title>Prawa dostêpu</title>
+    <indexterm><primary>UNIX</primary></indexterm>
+
+    <para>FreeBSD, bêd±c bezpo¶rednim potomkiem systemu &unix; BSD,
+      oparte jest na kilku kluczowych za³o¿eniach Uniksa. Najbardziej
+      widocznym z nich jest fakt, ¿e FreeBSD jest systemem wielou¿ytkownikowym
+      &mdash; potrafi jednocze¶nie obs³ugiwaæ wielu u¿ytkowników pracuj±cych
+      niezale¿nie od siebie. System jest odpowiedzialny za w³a¶ciwe zarz±dzanie
+      odwo³aniami do sprzêtu, pamiêci i czasu procesora, po równo dla ka¿dego
+      z u¿ytkowników.</para>
+
+    <para>Ze wzglêdu na obs³ugê wielu u¿ytkowników, zasoby, którymi
+      zarz±dza system, maj± przypisane prawa dostêpu okre¶laj±ce, kto
+      mo¿e czytaæ, zapisywaæ i uruchamiaæ dany zasób. Prawa dostêpu
+      przechowywane s± w postaci dwóch oktetów podzielonych na trzy czê¶ci,
+      z których pierwsza odnosi sie do w³a¶ciciela pliku, druga do
+      grupy posiadaj±cej plik, a trzecia do innych u¿ytkowników.
+      W postaci numerycznej zapisuje siê to nastêpuj±co:</para>
+
+    <indexterm><primary>permissions</primary></indexterm>
+    <indexterm>
+      <primary>file permissions</primary>
+    </indexterm>
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="3">
+	<thead>
+	  <row>
+	    <entry>Warto¶æ</entry>
+	    <entry>Uprawnienia</entry>
+	    <entry>Symbol</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry>0</entry>
+            <entry>Odczyt: nie, zapis: nie, wykonywanie: nie</entry>
+	    <entry><literal>---</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>1</entry>
+            <entry>Odczyt: nie, zapis: nie, wykonywanie: tak</entry>
+	    <entry><literal>--x</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>2</entry>
+            <entry>Odczyt: nie, zapis: tak, wykonywanie: nie</entry>
+	    <entry><literal>-w-</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>3</entry>
+            <entry>Odczyt: nie, zapis: tak, wykonywanie: tak</entry>
+	    <entry><literal>-wx</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>4</entry>
+            <entry>Odczyt: tak, zapis: nie, wykonywanie: nie</entry>
+	    <entry><literal>r--</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>5</entry>
+            <entry>Odczyt: tak, zapis: nie, wykonywanie: tak</entry>
+	    <entry><literal>r-x</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>6</entry>
+            <entry>Odczyt: tak, zapis: tak, wykonywanie: nie</entry>
+	    <entry><literal>rw-</literal></entry>
+	  </row>
+
+	  <row>
+	    <entry>7</entry>
+            <entry>Odczyt: tak, zapis: tak, wykonywanie: tak</entry>
+	    <entry><literal>rwx</literal></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+    <indexterm>
+      <primary><command>ls</command></primary>
+    </indexterm>
+    <indexterm><primary>katalogi</primary></indexterm>
+
+    <para>Korzystaj±c z polecenia &man.ls.1; mo¿emy pos³u¿yæ siê opcj±
+      <option>-l</option>, by zawarto¶æ katalogu zosta³a pokazana
+      w formie szczegó³owej, z uwzglêdnieniem kolumny zawieraj±cej
+      informacjê o prawach dostêpu do pliku dla jego w³a¶ciciela,
+      grupy, oraz wszystkich innych. Przyk³adowy wynik polecenia
+      <command>ls -l</command>:</para>
+
+    <screen>&prompt.user; <userinput>ls -l</userinput>
+total 530
+-rw-r--r--  1 root  wheel     512 Sep  5 12:31 myfile
+-rw-r--r--  1 root  wheel     512 Sep  5 12:31 otherfile
+-rw-r--r--  1 root  wheel    7680 Sep  5 12:31 email.txt
+...</screen>
+
+    <para>Pierwsza kolumna listy plików po wykonaniu polecenia
+      <command>ls -l</command> ma nastêpuj±c± postaæ:</para>
+
+    <screen>-rw-r--r--</screen>
+
+    <para>Pierwszy znak (od lewej) okre¶la, czy plik jest
+      zwyczajnym plikiem, katalogiem, urz±dzeniem znakowym,
+      gniazdem, czy jakimkolwiek innym urz±dzeniem pseudo-plikowym.
+      Widoczny w przyk³adzie znak <literal>-</literal> oznacza
+      zwyk³y plik. Kolejne trzy znaki, w przyk³adzie s± to
+      <literal>rw-</literal>, reprezentuj± prawa dostêpu, którymi
+      dysponuje w³a¶ciciel pliku. Nastêpne trzy znaki <literal>r--</literal>,
+      okre¶laj± prawa dostêpu grupy, do której nale¿y plik. Ostatnia trójka
+      <literal>r--</literal>, oznacza prawa dostêpu dla innych. Minus
+      oznacza brak jednego z praw dostêpu. Plik przedstawiony w
+      przyk³adzie mo¿e byæ wiêc odczytywany i zapisywany przez swojego
+      w³a¶ciciela, oraz jedynie odczytywany przez grupê i innych.
+      Zgodnie z powy¿sz± tabel±, prawa dostêpu do tego pliku maj±
+      warto¶æ <literal>644</literal>, przy czym ka¿da cyfra reprezentuje
+      trzy czê¶ci uprawnieñ.</para>
+
+    <para>W porz±dku, ale w jaki sposób system kontroluje dostêp
+      do urz±dzeñ? Zasadniczo wiêkszo¶æ urz±dzeñ jest traktowana
+      przez FreeBSD jak pliki, które mog± byæ otwierane, odczytywane
+      i zapisywane podobnie jak wszystkie inne pliki. Specjalne pliki
+      urz±dzeñ przechowywane s± w katalogu
+      <filename>/dev</filename>.</para>
+
+    <para>Równie¿ katalogi traktowane s± jak pliki &mdash; te¿ s±
+      im przypisywane prawa odczytu, zapisu i wykonania. Bit wykonania
+      katalogu ma nieco inne znaczenie ni¿ w przypadku pliku.
+      Posiadanie prawa wykonania katalogu oznacza, ¿e mo¿na do niego
+      wej¶æ, czyli pos³u¿yæ siê poleceniem <quote>cd</quote>.
+      Ponadto umo¿liwia to dostêp do zawartych w katalogu plików
+      o znanych nazwach (oczywi¶cie obowi±zuj± tak¿e indywidualne
+      prawa dostêpu do ka¿dego z plików).</para>
+
+    <para>W szczególno¶ci, wy¶wietlenie listy plików katalogu wymaga
+      posiadania prawa do jego odczytu, natomiast do usuniêcia pliku
+      o znanej nazwie potrzebne bêd± prawa do zapisu <emphasis>i</emphasis>
+      wykonania dla katalogu, w którym ów plik siê znajduje.</para>
+
+    <para>Jest jeszcze kilka innych bitów uprawnieñ, jednak s± one
+      stosowane w specjalnych przypadkach, np. do w³±czenia atrybutu
+      SUID, lub <quote>lepkiego</quote> bitu dla katlogu. Wiêcej
+      informacji o prawach dostêpu i o ich przydzielaniu mo¿na
+      znale¼æ w dokumentacji systemowej polecenia &man.chmod.1;.</para>
+
+    <sect2>
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Tom</firstname>
+	    <surname>Rhodes</surname>
+	    <contrib>Napisa³ </contrib>
+	  </author>
+	</authorgroup>
+        <authorgroup>
+          <author>
+            <firstname>Cezary</firstname>
+            <surname>Morga</surname>
+            <contrib>T³umaczy³ </contrib>
+          </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Uprawnienia symboliczne</title>
+      <indexterm><primary>uprawnienia</primary><secondary>symboliczne</secondary></indexterm>
+
+      <para>Uprawnienia symboliczne, okre¶lane równie¿ jako wyra¿enia symboliczne,
+        przy okre¶laniu praw dostêpu do plików lub katalogów wykorzystuj±
+        litery w miejsce warto¶ci liczbowych. Wyra¿enia symboliczne wykorzystuj±
+        sk³adniê: (kto) (akcja) (uprawnienia), przy czym dostêpne s± nastêpuj±ce
+        warto¶ci:</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Opcja</entry>
+	      <entry>Litera</entry>
+              <entry>Znaczenie</entry>
+	    </row>
+	  </thead>
+
+	<tbody>
+	  <row>
+	    <entry>(kto)</entry>
+	    <entry>u</entry>
+            <entry>U¿ytkownik (w³a¶ciciel)</entry>
+	  </row>
+
+	  <row>
+	    <entry>(kto)</entry>
+	    <entry>g</entry>
+            <entry>Grupa</entry>
+	  </row>
+
+	  <row>
+	    <entry>(kto)</entry>
+	    <entry>o</entry>
+	    <entry>Inni</entry>
+	  </row>
+
+	  <row>
+	    <entry>(kto)</entry>
+	    <entry>a</entry>
+            <entry>Wszyscy (<quote>¶wiat</quote>)</entry>
+	  </row>
+
+	  <row>
+	    <entry>(akcja)</entry>
+	    <entry>+</entry>
+            <entry>Dodanie uprawnieñ</entry>
+	  </row>
+
+	  <row>
+	    <entry>(akcja)</entry>
+	    <entry>-</entry>
+            <entry>Usuniêcie uprawnieñ</entry>
+	  </row>
+
+	  <row>
+	    <entry>(akcja)</entry>
+	    <entry>=</entry>
+            <entry>Ustawienie uprawnieñ</entry>
+	  </row>
+
+	  <row>
+	    <entry>(uprawnienia)</entry>
+	    <entry>r</entry>
+            <entry>Odczyt</entry>
+	  </row>
+
+	  <row>
+	    <entry>(uprawnienia)</entry>
+	    <entry>w</entry>
+            <entry>Zapis</entry>
+	  </row>
+
+	  <row>
+	    <entry>(uprawnienia)</entry>
+	    <entry>x</entry>
+            <entry>Wykonywanie</entry>
+	  </row>
+
+	  <row>
+	    <entry>(uprawnienia)</entry>
+	    <entry>t</entry>
+            <entry>Bit <quote>lepki</quote></entry>
+	  </row>
+
+	  <row>
+	    <entry>(uprawnienia)</entry>
+	    <entry>s</entry>
+            <entry>Ustawienie UID lub GID</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+
+    <para>Do ustawienia tych warto¶ci, podobnie jak w przypadku
+      warto¶ci liczbowych, wykorzystywane jest polecenie
+      &man.chmod.1;. Przyk³adowo, by zablokowaæ dostêp
+      innych u¿ytkowników do <replaceable>PLIKU</replaceable>
+      nale¿y wpisaæ:</para>
+
+    <screen>&prompt.user; <userinput>chmod go= PLIK</userinput></screen>
+
+    <para>Gdy musimy wykonaæ wiêcej ni¿ jedn± zmianê uprawnieñ
+      parametry nale¿y oddzieliæ przecinkami. Na przyk³ad,
+      poni¿sze polecenie usunie prawa zapisu do
+      <replaceable>PLIKU</replaceable> grupie i innym.
+      Nastêpnie doda wszystkim prawo wykonywania:</para>
+
+    <screen>&prompt.user; <userinput>chmod go-w,a+x <replaceable>PLIK</replaceable></userinput></screen>
+
+<!--
+    <para>Most users will not notice this, but it should be pointed out
+      that using the octal method will only set or assign permissions to
+      a file; it does not add or delete them.</para>
+-->
+    </sect2>
+
+    <sect2>
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Tom</firstname>
+	    <surname>Rhodes</surname>
+	    <contrib>Napisa³ </contrib>
+	  </author>
+	</authorgroup>
+        <authorgroup>
+          <author>
+            <firstname>Cezary</firstname>
+            <surname>Morga</surname>
+            <contrib>T³umaczy³ </contrib>
+          </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Flagi plików we &os;</title>
+
+      <para>Dodatkowo, oprócz opisanych wy¿ej praw dostêpu,
+        &os; wykorzystuje równie¿ <quote>flagi plików</quote>.
+        Flagi te umo¿liwiaj± wprowadzenie dodatkowego poziomu
+        ochrony i kontroli plików. Nie dotycz± natomiast
+        katalogów.</para>
+
+      <para>Dziêki zwiêkszonemu poziomowi kontroli plików
+        system mo¿e zagwarantowaæ, ¿e w niektórych sytuacjach
+        nawet u¿ytkownik <username>root</username>  nie bêdzie
+        móg³ usun±æ b±d¼ zmodyfikowaæ plików.</para>
+
+      <para>Zmiany flag plików dokonuje siê poleceniem &man.chflags.1;.
+        Przyk³adowo, by plikowi <filename>plik1</filename> nadaæ flagê
+        nieusuwalno¶ci nale¿y wydaæ poni¿esz polecenie:</para>
+
+      <screen>&prompt.root; <userinput>chflags sunlink <filename>plik1</filename></userinput></screen>
+
+      <para>Natomiast, by usun±æ flagê nieusuwalno¶ci
+        wystarczy wprowadziæ takie samo polecenie dodaj±c
+        <quote>no</quote> przed <option>sunlink</option>:</para>
+
+      <screen>&prompt.root; <userinput>chflags nosunlink <filename>plik1</filename></userinput></screen>
+
+      <para>By wy¶wietliæ flagi danego pliku wystarczy wpisaæ
+        polecenie &man.ls.1; z parametrem <option>-lo</option>:</para>
+
+      <screen>&prompt.root; <userinput>ls -lo <filename>plik1</filename>
+	</userinput></screen>
+
+      <para>Wynik powinien byæ zbli¿ony do poni¿szego:</para>
+
+      <programlisting>-rw-r--r--  1 trhodes  trhodes  sunlnk 0 Mar  1 05:54 plik1</programlisting>
+
+      <para>Niektóre z flag mog± byæ dodawane i usuwane jedynie przez
+        u¿ytkownika <username>root</username>, podczas gdy inne mog±
+        byæ ustawiane równie¿ przez w³a¶ciciela pliku. Zaleca siê aby
+        administratorzy przeczytali strony podrêcznika systemowego
+        &man.chflags.1; oraz &man.chflags.2;.</para>
+    </sect2>
+  </sect1>
+  
+  <sect1 id="dirstructure">
+    <title>Struktura katalogów</title>
+    <indexterm><primary>hierarchia katalogów</primary></indexterm>
+
+    <para>Poznanie hierarchii katalogów FreeBSD jest podstaw±
+      ogólnego zrozumienia dzia³ania systemu. Najwa¿niejszym
+      zagadnieniem jest koncepcja katalogu g³ównego, <quote>/</quote>.
+      Jest on montowany jako pierwszy podczas uruchamiania systemu
+      i zawiera podstawowe pliki niezbêdne do przygotowania
+      systemu do pracy w trybie wielou¿ytkownikowym. Ponadto
+      w katalogu g³ównym znajduj± siê punkty montowania innych
+      systemów plików, które mo¿emy montowaæ.</para>
+
+    <para>Punktem montowania nazywany jest katalog, poprzez
+      który inny system plików mo¿e byæ do³±czony do g³ównego
+      systemu plików. <xref linkend="disk-organization">
+      zawiera wiêcej informacji. Przyk³adem typowego punktu
+      montowania mo¿e byæ
+      <filename>/usr</filename>, <filename>/var</filename>,
+      <filename>/tmp</filename>, <filename>/mnt</filename>
+      oraz <filename>/cdrom</filename>. Najczê¶ciej ka¿demu
+      z takich katalogów odpowiada wpis w pliku
+      <filename>/etc/fstab</filename>. Plik ten zawiera tabelê
+      systemów plików i ich punktów montowania, z której korzysta
+      system. Wiêkszo¶æ systemów plików wymienionych w
+      <filename>/etc/fstab</filename> jest montowana automatycznie
+      przez skrypt &man.rc.8; podczas uruchamiania systemu,
+      wyj±tkiem s± te wpisy, które maj± opcjê <option>noauto</option>.
+      <xref linkend="disks-fstab"> zawiera wiêcej informacji.</para>
+
+    <para>Pe³ny opis struktury systemu plików znajduje siê w dokumentacji
+      systemowej &man.hier.7;. Tu ograniczymy siê do pobie¿nego
+      zapoznania siê z najwa¿niejszymi katalogami.</para>
+
+    <para>
+      <informaltable frame="none" pgwide="1">
+        <tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Katalog</entry>
+	      <entry>Opis</entry>
+	    </row>
+	  </thead>
+	  <tbody valign="top">
+            <row>
+	      <entry><filename class="directory">/</filename></entry>
+              <entry>G³ówny katalog systemu plików.</entry>
+            </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/bin/</filename></entry>
+              <entry>Programy u¿ytkowe wykorzystywane zarówno w trybie
+              jednego u¿ytkownika, jak i w trybie wielu u¿ytkowników.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/boot/</filename></entry>
+              <entry>	Programy i pliki konfiguracyjne u¿ywane podczas
+              uruchamiania systemu.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/boot/defaults/</filename></entry>
+              <entry>Pliki z domy¶ln± konfiguracj± uruchamiania systemu; patrz
+	      &man.loader.conf.5;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/dev/</filename></entry>
+              <entry>Pliki urz±dzeñ; patrz &man.intro.4;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/etc/</filename></entry>
+              <entry>Pliki i skrypty konfiguracyjne.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/etc/defaults/</filename></entry>
+              <entry>Pliki z domy¶ln± konfiguracj± systemu; patrz &man.rc.8;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/etc/mail/</filename></entry>
+              <entry>Pliki konfiguracyjne dla serwerów poczty, na przyk³ad
+              &man.sendmail.8;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/etc/namedb/</filename></entry>
+              <entry>Pliki konfigracyjne programu <command>named</command>; patrz
+	      &man.named.8;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/etc/periodic/</filename></entry>
+              <entry>Skrypty uruchamiane raz dziennie, raz na tydzieñ i raz na miesi±c
+              za po¶rednictwem &man.cron.8;; patrz &man.periodic.8;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/etc/ppp/</filename></entry>
+              <entry>Pliki konfiguracyjne <command>ppp</command>; patrz
+	      &man.ppp.8;.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/mnt/</filename></entry>
+              <entry>Pusty katalog, najczê¶ciej wykorzystywany przez administratorów
+              jako tymczasowy punkt montowania..</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/proc/</filename></entry>
+              <entry>System plików procesów, patrz &man.procfs.5;,
+	      &man.mount.procfs.8;.</entry>
+	    </row>
+
+	    <row>
+	      <entry><filename class="directory">/rescue/</filename></entry>
+              <entry>Katalog zawieraj±cy programy przydatne w przypadku awarii; patrz
+		&man.rescue.8;.</entry>
+	    </row>
+
+	    <row>
+	      <entry><filename class="directory">/root/</filename></entry>
+              <entry>Katalog domowy u¿ytkownika <username>root</username>.</entry>
+	    </row>
+
+	    <row>
+	      <entry><filename class="directory">/sbin/</filename></entry>
+              <entry>Programy i narzêdzia administracyjne wykorzystywane zarówno
+              w trybie jednego u¿ytkownika, jak i w trybie wielu u¿ytkowników.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/stand/</filename></entry>
+              <entry>Programy u¿ywane w samodzielnym ¶rodowisku.</entry>
+	    </row>
+	    
+	    
+	    <row>
+	      <entry><filename class="directory">/tmp/</filename></entry>
+              <entry>Pliki tymczasowe. Zawarto¶æ katalogu
+                <filename class="directory">/tmp</filename> NIE JEST zachowywana
+                przy ponownym uruchamianiu systemu. Równie¿ pamiêciowy system
+                plików jest czêsto montowany w katalogu
+                <filename class="directory">/tmp</filename>. Proces ten mo¿e
+                zostaæ zautomatyzowany wykorzystuj±c zmienne &man.rc.conf.5;
+                zwi±zane z tmpmfs (b±dz za pomoc± wpisu w
+                <filename>/etc/fstab</filename>; patrz &man.mdmfs.8;).</entry>
+	    </row>
+	    
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/</filename></entry>
+              <entry>Wiêkszo¶æ programów i aplikacji wykorzystywanych przez u¿ytkowników.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/bin/</filename></entry>
+              <entry>Najczê¶ciej u¿ywane programy, narzêdzia programistyczne, aplikacje.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/include/</filename></entry>
+              <entry>Pliki nag³ówkowe C.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/lib/</filename></entry>
+              <entry>Biblioteki.</entry>
+	    </row>
+	    
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/libdata/</filename></entry>
+              <entry>Pliki danych ró¿nych programów u¿ytkowych.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/libexec/</filename></entry>
+              <entry>SDemony i programy systemowe (uruchamiane przez inne programy).</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename
+	      class="directory">/usr/local/</filename></entry>
+
+              <entry>Lokalne programy, biblioteki, itp. Ponadto jest
+                to domy¶lny katalog dla instalowanych portów. Ogólna
+                struktura katalogów wewn±trz <filename>/usr/local</filename>
+                powinna odpowiadaæ strukturze <filename>/usr</filename>
+                opisanej w dokumentacji &man.hier.7;. Wyj±tkiem jest katalog
+                man, umieszczony bezpo¶rednio w <filename>/usr/local</filename>,
+                a nie w <filename>/usr/local/share</filename>, oraz dokumentacja
+                portów, znajduj±ca siê w
+	        <filename>share/doc/<replaceable>port</replaceable></filename>.
+	      </entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/obj/</filename></entry>
+              <entry>Pliki zale¿ne od architektury komputera, tworzone w procesie
+              budowania drzewa <filename>/usr/src</filename>.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/ports</filename></entry>
+              <entry>Kolekcja portów FreeBSD (opcjonalna).</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/sbin/</filename></entry>
+              <entry>Demony i programy systemowe (dostêpne dla u¿ytkowników).</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/share/</filename></entry>
+              <entry>Pliki niezale¿ne od architektury systemu.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/usr/src/</filename></entry>
+              <entry>Pliki ¼ród³owe BSD, lokalne pliki ¼ród³owe.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename
+	      class="directory">/usr/X11R6/</filename></entry>
+              <entry>Pliki wykonywalne, biblioteki, i inne pliki dystrybucji
+              X11R6 (opcjonalnie).</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/var/</filename></entry>
+              <entry>Rozmaite pliki dzienników systemowych, pliki tymczasowe,
+                pliki kolejek. Równie¿ pamiêciowy system plików jest czêsto
+                montowany w tym katalogu. Proces ten mo¿e zostaæ
+                zautomatyzowany wykorzystuj±c zmienne &man.rc.conf.5; zwi±zane
+                z varmfs (b±dz za pomoc± wpisu w <filename>/etc/fstab</filename>;
+                patrz &man.mdmfs.8;).</entry>
+	    </row>
+	    
+	    
+	    <row>
+	      <entry><filename class="directory">/var/log/</filename></entry>
+              <entry>Pliki dzienników systemowych.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/var/mail/</filename></entry>
+              <entry>Skrzynki pocztowe u¿ytkowników.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/var/spool/</filename></entry>
+              <entry>Katalogi kolejek systemu drukowania i poczty.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename class="directory">/var/tmp/</filename></entry>
+              <entry>Pliki tymczasowe nie usuwane przy ponownym uruchamianiu
+              systemu.</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><filename>/var/yp</filename></entry>
+              <entry>Mapy us³ugi NIS.</entry>
+	    </row>
+
+	  </tbody>
+	</tgroup>
+      </informaltable>
+    </para>
+
+  </sect1>
+
+  <sect1 id="disk-organization">
+      <title>Organizacja dysku</title>
+
+      <para>Najmniejsz± jednostk± organizacji dysku u¿ywan± przez FreeBSD
+        do odnajdywania plików jest nazwa pliku. W nazwach plików rozró¿niane
+        s± du¿e i ma³e litery, tak wiêc <filename>readme.txt</filename>
+        i <filename>README.TXT</filename> to dwa ró¿ne pliki. FreeBSD
+        nie wykorzystuje rozszerzeñ nazw plików (<filename>.txt</filename>)
+        do okre¶lenia, czy plik jest programem, dokumentem, czy innym
+        zbiorem danych.</para>
+
+      <para>Pliki przechowywane s± w katalogach. Katalog mo¿e byæ pusty,
+        lub mo¿e zawieraæ setki plików. Mo¿e równie¿ zawieraæ inne katalogi,
+        dziêki czemu mamy mo¿liwo¶æ zbudowania hierarchicznej struktury
+        katalogów. Pozwala to na ³atw± organizacjê danych.</para>
+
+      <para>Dostêp do plików i katalogów uzyskuje siê podaj±c nazwê pliku
+        lub katalogu, poprzedzon± uko¶nikiem <literal>/</literal> i innymi
+        wymaganymi nazwami katalogów. Je¶li mamy katalog <filename>foo</filename>,
+        a w nim katalog <filename>bar</filename>, w którym znajduje siê plik
+        <filename>readme.txt</filename>, wówczas pe³n± nazw±, b±d¼ ¶cie¿k±
+        dostêpu do pliku jest <filename>foo/bar/readme.txt</filename>.</para>
+
+      <para>Katalogi i pliki przechowywane s± w systemie plików. Ka¿dy
+        system plików ma jeden katalog najwy¿szego poziomu, zwany <firstterm>katalogiem
+        g³ównym</firstterm> systemu plików. W katalogu g³ównym mog± byæ umieszczone
+        nastêpne katalogi.</para>
+
+      <para>To, o czym mówimy, jest zapewne podobne do innych systemów operacyjnych,
+        z którymi byæ mo¿e zetknêli¶my siê wcze¶niej. S± jednak ró¿nice; na przyk³ad
+        w systemie &ms-dos; nazwy plików i katalogów oddzielane s± znakiem
+        <literal>\</literal>, w &macos; natomiast znakiem <literal>:</literal>.</para>
+
+      <para>We FreeBSD nie s± u¿ywane litery dysków, lub inne nazwy dysków w
+        ¶cie¿ce. Nie spotkamy siê w FreeBSD z czym¶ takim jak
+        <filename>c:/foo/bar/readme.txt</filename>.</para>
+
+      <para>Jest natomiast jeden system plików pe³ni±cy rolê <firstterm>g³ównego
+        systemu plików</firstterm>. Zawiera on katalog g³ówny dostêpny jako
+        <literal>/</literal>. Ka¿dy inny system plików jest <firstterm>montowany</firstterm>
+        w g³ownym systemie plików. Niezale¿nie od tego, ile dysków mamy w komputerze,
+        we FreeBSD ka¿dy katalog wydaje siê byæ czê¶ci± tego samego dysku.</para>
+
+      <para>Za³ó¿my, ¿e mamy trzy systemy plików, nazwane <literal>A</literal>,
+	<literal>B</literal> i <literal>C</literal>. Ka¿dy z nich ma katalog
+        g³ówny, zawieraj±cy dwa katalogi o nazwach <literal>A1</literal>,
+        <literal>A2</literal> (oraz odpowiednio
+	<literal>B1</literal>, <literal>B2</literal> i
+	<literal>C1</literal>, <literal>C2</literal>).</para>
+
+      <para>Niech <literal>A</literal> bêdzie g³ównym systemem plików.
+        Gdyby¶my sprawdzili jego zawarto¶æ poleceniem <command>ls</command>,
+        zobaczyliby¶my dwa podkatalogi <literal>A1</literal> i
+	<literal>A2</literal>. Drzewo katalogów wygl±da nastêpuj±co:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="install/example-dir1" format="EPS">
+	</imageobject>
+
+	<textobject>
+	  <literallayout class="monospaced"> /
+ |
+ +--- A1
+ |
+ `--- A2</literallayout>
+	</textobject>
+      </mediaobject>
+
+      <para>System plików musi byæ montowany w katalogu innego systemu
+        plików. Przyjmijmy teraz, ¿e montujemy system plików <literal>B</literal>
+        w katalogu <literal>A1</literal>. G³ówny katalog <literal>B</literal>
+        zast±pi <literal>A1</literal>, a podkatalogi <literal>B</literal>
+        pojawi± siê w odpowiednim miejscu:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="install/example-dir2" format="EPS">
+	</imageobject>
+
+	<textobject>
+	  <literallayout class="monospaced"> /
+ | 
+ +--- A1
+ |     |
+ |     +--- B1
+ |     |
+ |     `--- B2
+ |
+ `--- A2</literallayout>
+	</textobject>
+      </mediaobject>
+
+      <para>Do plików znajduj±cych siê w katalogach <literal>B1</literal>
+        i <literal>B2</literal> mo¿na siê dostaæ pos³uguj±c siê ¶cie¿k±
+        <filename>/A1/B1</filename> lub <filename>/A1/B2</filename>.
+        Pliki poprzednio obecne w katalogu <filename>/A1</filename>
+        s± tymczasowo ukryte. Pojawi± siê ponownie po
+        <firstterm>odmontowaniu</firstterm>
+        <filename>B</filename> z <filename>A</filename>.</para>
+
+      <para>Gdyby zamontowaæ <literal>B</literal> w <literal>A2</literal>,
+        drzewo katalogów wygl±da³oby tak:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="install/example-dir3" format="EPS">
+	</imageobject>
+
+	<textobject>
+	  <literallayout class="monospaced"> /
+ |
+ +--- A1
+ |
+ `--- A2
+       |
+       +--- B1
+       |
+       `--- B2</literallayout>
+	</textobject>
+      </mediaobject>
+
+      <para>¶cie¿ki natomiast mia³yby postaæ <filename>/A2/B1</filename>
+        i <filename>/A2/B2</filename>.</para>
+
+      <para>Systemy plików mog± byæ montowane jeden na drugim. Rozwijaj±c
+        poprzedni przyk³ad, mo¿emy zamontowaæ system plików <literal>C</literal>
+        w katalogu <literal>B1</literal> systemu plików <literal>B</literal>,
+        otrzymuj±c nastêpuj±c± postaæ drzewa katalogów:</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>Mo¿na równie dobrze zamontowaæ <literal>C</literal>
+        bezpo¶rednio w systemie plików <literal>A</literal>,
+        w katalogu <literal>A1</literal>:</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>Znaj±cym system &ms-dos; mo¿e to przypominaæ polecenie
+        <command>join</command>, choæ nie jest to to samo.</para>
+
+      <para>Zwykle nie trzeba zajmowaæ siê opisanymi powy¿ej rzeczami.
+        Najczê¶ciej tworzymy systemy plików podczas instalacji FreeBSD,
+        wybieramy miejsce ich zamontowania i nie wprowadzamy po¼niej
+        ¿adnych zmian, chyba, ¿e zainstalujemy nowy dysk.</para>
+
+      <para>Mo¿na utworzyæ jeden obszerny g³ówny system plików
+        i nie tworzyæ ¿adnych innych. Takie podej¶cie ma kilka wad
+        i jedn± zaletê.</para>
+
+      <itemizedlist>
+        <title>Korzy¶ci z kilku systemów plików</title>
+      
+	<listitem>
+          <para>Odrêbne systemy plików mog± mieæ ró¿ne <firstterm>opcje
+            montowania</firstterm> (mount options). Na przyk³ad, przy
+            odpowiednim przygotowaniu, g³ówny system plików mo¿e byæ
+            zamontowany tylko do odczytu, przez co niemo¿liwe bêdzie
+            przypadkowe usuniêcie lub zmiana wa¿nego pliku. Oddzielenie
+            systemów plików dostêpnych do zapisu dla u¿ytkowników, jak
+            np. <filename>/home</filename>, od innych pozwala równie¿
+            na montowanie ich z opcj± <firstterm>nosuid</firstterm>;
+            co z kolei pozwala zwiêkszyæ bezpieczeñstwo systemu
+            uniemo¿liwiaj±c wykorzystanie bitów
+            <firstterm>suid</firstterm>/<firstterm>guid</firstterm>.</para>
+	</listitem>
+
+	<listitem>
+          <para>FreeBSD automatycznie optymalizuje uk³ad plików w systemie
+            plików, w zale¿no¶ci od tego, jak ów system jest wykorzystywany.
+            System plików zawieraj±cy wiele czêsto zapisywanych ma³ych plików
+            bêdzie optymalizowany inaczej ni¿ taki, w którym przechowywane
+            jest mniej plików o du¿ych rozmiarach. W przypadku jednego du¿ego
+            systemu plików taka optymalizacja nie zadzia³a.</para>
+	</listitem>
+	
+	<listitem>
+          <para>Systemy plików FreeBSD s± odporne na awarie zasilania.
+            W niesprzyjaj±cych okoliczno¶ciach mo¿e siê jednak zdarzyæ,
+            ¿e przerwa w dostawie pr±du w krytycznym momencie spowoduje
+            uszkodzenie struktury systemu plików. Przechowywanie danych
+            w kilku systemach plików zwiêksza szansê, ¿e system uruchomi
+            siê ponownie, dziêki czemu ³atwiej bêdzie odzyskaæ dane
+            z kopii zapasowej.</para>
+	</listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+        <title>Korzy¶æ z pojedynczego systemu plików</title>
+
+	<listitem>
+          <para>Systemy plików maj± sta³y rozmiar. Podczas instalacji
+            FreeBSD tworzymy system plików o zadanym rozmiarze; pó¼niej
+            mo¿e siê okazaæ, ¿e trzeba powiêkszyæ partycjê. Nie³atwo
+            jest to zrobiæ inaczej, ni¿ przez przygotowanie zapasowej
+            kopii danych, utworzenie na nowo systemu plików o wiêkszych
+            rozmiarach, oraz skopiowanie danych z powrotem.</para>
+
+	  <important>
+            <para>We &os; dostêpne jest polecenie &man.growfs.8;,
+              które pozwala na zwiêkszenie rozmiaru systemu plików
+              w locie, pomijaj±c wspomniane ograniczenie.</para>
+	  </important>
+	</listitem>
+      </itemizedlist>
+    
+      <para>Systemy plików przechowywane s± na partycjach. Pojêcie
+        partycji ma tu inne znaczenie ni¿ popularnie stosowane (np.
+        partycja systemu &ms-dos;), ze wzglêdu na uniksowy rodowód
+        &os;. Ka¿da z partycji oznaczana jest liter±, od <literal>a</literal>
+        do <literal>h</literal>. Pojedyncza partycja mo¿e zawieraæ
+        jeden system plików, dlatego te¿ do systemów plików czêsto
+        odwo³uje siê albo poprzez miejsce ich zamontowania w g³ównym
+        systemie plików, albo przez literowe oznaczenie partycji, na
+        której dany system plików siê znajduje.</para>
+
+      <para>Przestrzeñ dyskowa jest równie¿ u¿ywana we FreeBSD
+        jako <firstterm>przestrzeñ wymiany</firstterm>, pe³ni±c w
+        ten sposób rolê <firstterm>pamiêci wirtualnej</firstterm>.
+        Komputer mo¿e dziêki temu dysponowaæ wiêksz± ilo¶ci± pamiêci,
+        ni¿ ma w rzeczywisto¶ci. Kiedy pamiêci zaczyna brakowaæ,
+        FreeBSD odsy³a niektóre nieu¿ywane dane do przestrzeni
+        wymiany, a gdy znów oka¿± siê potrzebne, przenosi je z powrotem
+        (odsy³aj±c jednocze¶nie inne dane).</para>
+
+      <para>Z niektórymi partycjami zwi±zane s± pewne konwencje
+        dotycz±ce ich zastosowania./para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <colspec colwidth="1*">
+	  <colspec colwidth="5*">
+
+	  <thead>
+	    <row>
+	      <entry>Patrycja</entry>
+
+	      <entry>Konwencja</entry>
+	    </row>
+	  </thead>
+
+	  <tbody valign="top">
+	    <row>
+	      <entry><literal>a</literal></entry>
+
+              <entry>Zwykle zawiera g³ówny system plików</entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>b</literal></entry>
+
+              <entry>Zwykle zawiera przestrzeñ wymiany</entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>c</literal></entry>
+
+              <entry>Zwykle jest tego samego rozmiaru, co obejmuj±cy
+                j± segment. Dziêki temu programy dzia³aj±ce na ca³ym
+                segmencie (na przyk³ad wykrywaj±ce uszkodzone obszary
+                dysku) mog± dzia³aæ na partycji <literal>c</literal>.
+                Zwykle nie tworzy siê na tej partycji systemu plików.</entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>d</literal></entry>
+
+              <entry>Swego czasu partycja <literal>d</literal> mia³a specjalne znaczenie,
+                obecnie ju¿ go nie ma. Do dzi¶ jednak niektóre programy
+                mog± dziwnie siê zachowywaæ, je¶li ka¿e im siê pracowaæ
+                na partycji <literal>d</literal>, dlatego te¿
+                <application>sysinstall</application>
+                zwykle wogóle jej nie tworzy.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para>Ka¿da partycja zawieraj±ca system plików przechowywana jest na czym¶,
+        co we FreeBSD nosi nazwê <firstterm>segmentu</firstterm>. Jest to okre¶lenie
+        tego, co wcze¶niej zwane by³o partycj±, i ponownie jest to konsekwencj±
+        uniksowych korzeni FreeBSD. Segmenty s± oznaczane liczbami od 1 do 4.</para>
+
+	<indexterm><primary>segmenty</primary></indexterm>
+	<indexterm><primary>partycje</primary></indexterm>
+        <indexterm><primary>niebezpiecznie dedykowane</primary></indexterm>
+
+      <para>Numery segmentów, wraz z przedrostkiem <literal>s</literal>,
+        poprzedzone s± nazw± urz±dzenia. Tak wiêc
+        <quote>da0<emphasis>s1</emphasis></quote>
+        jest pierwszym segmentem na pierwszym dysku SCSI. Na dysku mog±
+        byæ najwy¿ej cztery fizyczne segmenty, mo¿na jednak tworzyæ segmenty
+        logiczne wewn±trz segmentów fizycznych specjalnego typu. Powsta³e
+        w ten sposób segmenty rozszerzone maj± numery od 5 wzwy¿, zatem
+        <quote>ad0<emphasis>s5</emphasis></quote> odpowiada pierwszemu
+        rozszerzonemu segmentowi na dysku IDE. Urz±dzenia te s± wykorzystywane
+        przez systemy plików, które zajmuj± ca³y segment.</para> 
+
+      <para>Segmenty, dyski <quote>niebezpiecznie dedykowane</quote>
+        i inne dyski zawieraj± <firstterm>partycje</firstterm>,
+        oznaczane literami od <literal>a</literal> do <literal>h</literal>.
+        Litera dopisywana jest do nazwy urz±dzenia, wiêc
+        <quote>da0<emphasis>a</emphasis></quote> odpowiadaæ bêdzie
+        partycji a na pierwszym dysku da, <quote>niebezpiecznie
+        dedykowanym</quote>. Z kolei <quote>ad1s3<emphasis>e</emphasis></quote>
+        oznacza pi±t± partycjê w trzecim segmencie drugiego dysku IDE.</para>
+	
+      <para>W³asne oznaczenie ma tak¿e ka¿dy dysk. Nazwa dysku sk³ada siê
+        z symbolu okre¶laj±cego typ dysku, oraz numeru, okre¶laj±cego
+        który to dysk. Dyski, inaczej ni¿ segmenty, numerowane s± od zera.
+        <xref linkend="basics-dev-codes"> zawiera najczê¶ciej spotykane zwykle
+        oznaczenia.</para>
+
+      <para>Gdy odwo³ujemy siê do partycji, FreeBSD wymaga, by¶my podali
+        równie¿ nazwê obejmuj±cego j± segmentu i dysku. Z kolei gdy odwo³ujemy
+        siê do segmentu, podajemy równie¿ nazwê dysku. Kolejno podajemy wiêc
+        nazwê dysku, <literal>s</literal>, numer segmentu, a na koniec
+        literê partycji; patrz <xref linkend="basics-disk-slice-part">.</para>
+
+      <para><xref linkend="basics-concept-disk-model"> pokazuje schematyczny
+        model dysku, z pomoc± którego ³atwiej bêdzie zrozumieæ pewne rzeczy.</para>
+
+      <para>Gdy instalujemy FreeBSD, w pierwszej kolejno¶ci musimy przygotowaæ
+        segmenty na dysku, nastêpnie w segmencie przeznaczonym dla FreeBSD
+        utworzyæ partycje, nastêpnie wewn±trz partycji stworzyæ system plików
+        (lub przestrzeñ wymiany) i okre¶liæ miejsce jego montowania.</para>
+
+      <table frame="none" pgwide="1" id="basics-dev-codes">
+        <title>Oznaczenia dysków</title>
+
+	<tgroup cols="2">
+          <colspec colwidth="1*">
+          <colspec colwidth="5*">
+
+	  <thead>
+	    <row>
+              <entry>Oznaczenie</entry>
+	    
+	      <entry>Znaczenie</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><devicename>ad</devicename></entry>
+
+              <entry>Dysk ATAPI (IDE)</entry>
+	    </row>
+
+	    <row>
+	      <entry><devicename>da</devicename></entry>
+	      
+              <entry>Dysk SCSI o dostêpie bezpo¶rednim</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><devicename>acd</devicename></entry>
+	      
+              <entry>CDROM ATAPI (IDE)</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><devicename>cd</devicename></entry>
+	      
+              <entry>CDROM SCSI</entry>
+	    </row>
+	    
+	    <row>
+	      <entry><devicename>fd</devicename></entry>
+	      
+              <entry>Stacja dyskietek</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+      
+      <example id="basics-disk-slice-part">
+        <title>Przyk³adowe nazwy dysków, segmentów i partycji</title>
+	
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+            <colspec colwidth="1*">
+            <colspec colwidth="5*">
+
+	    <thead>
+	      <row>
+		<entry>Nazwa</entry>
+		
+		<entry>Znaczenie</entry>
+	      </row>
+	    </thead>
+	    
+	    <tbody>
+	      <row>
+		<entry><literal>ad0s1a</literal></entry>
+		
+                <entry>Pierwsza partycja (<literal>a</literal>)
+                  w pierwszym segmencie (<literal>s1</literal>)
+                  na pierwszym dysku IDE (<literal>ad0</literal>).</entry>
+	      </row>
+
+	      <row>
+		<entry><literal>da1s2e</literal></entry>
+		
+                <entry>Pi±ta partycja <literal>e</literal> w drugim
+                  segmencie (<literal>s2</literal>) na drugim dysku
+                  SCSI (<literal>da1</literal>).</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+      </example>
+
+      <example id="basics-concept-disk-model">
+        <title>Schematyczny model dysku</title>
+
+        <para>Rysunek przedstawia pierwszy dysk IDE z punktu widzenia
+          FreeBSD. Zak³adamy, ¿e dysk ma rozmiar 4&nbsp;GB i jest podzielony
+          na dwa segmenty (partycje w &ms-dos;) o rozmiarze po 2&nbsp;GB.
+          Pierwszy segment zawiera DOS-owy dysk <devicename>C:</devicename>,
+          natomiast w drugim segmencie znajduje siê przyk³adowa instalacja
+          FreeBSD, z trzema partycjami oraz partycj± wymiany.</para>
+
+        <para>Ka¿da z trzech partycji przechowuje system plików. Na
+          partycji <literal>a</literal> umieszczony jest g³ówny system plików,
+          na <literal>e</literal> znajduje siê katalog <filename>/var</filename>,
+          a na <literal>f</literal> katalog <filename>/usr</filename>.</para>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata fileref="install/disk-layout" format="EPS">
+          </imageobject>
+ 
+          <textobject>
+	    <literallayout class="monospaced">.-----------------.  --.
+|                 |    |
+|  DOS / Windows  |    |
+:                 :     &gt;  First slice, ad0s1
+:                 :    |
+|                 |    |
+:=================:  ==:                               --.
+|                 |    |  Partition a, mounted as /      |
+|                 |     &gt; referred to as ad0s2a          |
+|                 |    |                                 |
+:-----------------:  ==:                                 |
+|                 |    |  Partition b, used as swap      |
+|                 |     &gt; referred to as ad0s2b          |
+|                 |    |                                 |
+:-----------------:  ==:                                 |  Partition c, no
+|                 |    |  Partition e, used as /var       &gt; file system, all 
+|                 |     &gt; referred to as ad0s2e          |  of FreeBSD slice,
+|                 |    |                                 |  ad0s2c
+:-----------------:  ==:                                 |
+|                 |    |                                 |
+:                 :    |  Partition f, used as /usr      |
+:                 :     &gt; referred to as ad0s2f          |
+:                 :    |                                 |
+|                 |    |                                 |
+|                 |  --'                                 |
+`-----------------'                                    --'</literallayout>
+          </textobject>
+        </mediaobject>
+      </example>
+  </sect1>
+
+
+
+  <sect1 id="mount-unmount">
+    <title>Montowanie i odmontowywanie systemów plików</title>
+
+    <para>System plików mo¿na sobie wyobraziæ jako drzewo, którego
+      korzeniem jest <filename>/</filename>. <filename>/dev</filename>,
+      <filename>/usr</filename> i inne podkatalogi katalogu g³ównego
+      s± ga³êziami, z których mog± wyrastaæ kolejne ga³êzie, na
+      przyk³ad <filename>/usr/local</filename>, itd.</para>
+
+    <indexterm><primary>g³ówny system plików</primary></indexterm>
+    <para>Jest kilka powodów, dla których warto jest trzymaæ niektóre
+      katalogi w oddzielnych systemach plików. W katalogu
+      <filename>/var</filename> znajduj± siê podkatalogi
+      <filename>log/</filename> i <filename>spool/</filename> oraz rozmaite
+      pliki tymczasowe, z tego powodu mo¿e siê on zape³niæ. Zape³nienie
+      g³ównego systemu plików jest raczej niepo¿±dane, wiêc czêsto zaleca
+      siê oddzielenie <filename>/var</filename> od <filename>/</filename>.</para>
+
+    <para>Czêsto niektóre katalogi umieszczane s± na odrêbnych systemach
+      plików ze wzglêdu na to, ¿e znajduj± siê na osobnych dyskach fizycznych
+      lub dyskach wirtualnych, jak na przyk³ad pliki udostêpniane poprzez
+      <link linkend="network-nfs">Network File System</link>
+      lub napêdy CDROM.</para>
+
+    <sect2 id="disks-fstab">
+      <title>Plik <filename>fstab</filename></title>
+      <indexterm>
+	<primary>file systems</primary>
+	<secondary>mounted with fstab</secondary>
+      </indexterm>
+
+      <para>Systemy plików wymienione w pliku <filename>/etc/fstab</filename>
+        s± automatycznie montowane podczas <link linkend="boot">³adowania
+          systemu</link> (prócz oznaczonych opcj± <option>noauto</option>)./para>
+
+      <para>Wpisy w pliku <filename>/etc/fstab</filename> s± nastêpuj±cej postaci:</para>
+
+      <programlisting><replaceable>urz±dzenie</replaceable>       <replaceable>/punkt-montowania</replaceable> <replaceable>typ</replaceable>     <replaceable>opcje</replaceable>      <replaceable>archiwizacja</replaceable>     <replaceable>nr-przebiegu</replaceable></programlisting>
+
+      <variablelist>
+	<varlistentry>
+          <term><literal>urz±dzenie</literal></term>
+	  <listitem>
+            <para>Nazwa pliku urz±dzenia (istniej±cego), zgodnie z opisem w
+	      <xref linkend="disks-naming">.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+          <term><literal>punkt-montowania</literal></term>
+            
+          <listitem><para>Katalog (istniej±cy), w którym system
+              plików ma byæ zamontowany.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><literal>typ</literal></term>
+            
+          <listitem><para>Typ systemu plików przekazywany poleceniu
+		&man.mount.8;. We FreeBSD domy¶lnie jest to
+	      <literal>ufs</literal>.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+          <term><literal>opcje</literal></term>
+            
+          <listitem><para>Pierwsz± opcj± jest <option>rw</option>, je¶li
+              w systemie plików ma byæ mo¿liwy odczyt i zapis, albo
+              <option>ro</option>, je¿eli dozwolony ma byæ tylko odczyt.
+              W nastêpnej kolejno¶ci podawane s± inne opcje. Czêsto stosowana
+              jest opcja <option>noauto</option>, która zapobiega automatycznemu
+              montowaniu systemu plików podczas uruchamiania systemu.
+              Pozosta³e opcje opisane s± w dokumentacji systemowej &man.mount.8;.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+          <term><literal>archiwizacja</literal></term>
+          
+          <listitem><para>Na podstawie tej informacji program &man.dump.8;
+              stwierdza, które systemy plików maj± byæ archwizowane. Je¶li pole
+              to zostanie pominiête, domy¶lnie przyjmowana jest warto¶æ zero.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term><literal>nr-przebiegu</literal></term>
+
+         <listitem>
+           <para>Na podstawie tego pola wyznaczana jest kolejno¶æ, w jakiej
+             systemy plików poddawane s± sprawdzaniu. Systemy plików, które
+             nie maj± byæ sprawdzane, powinny mieæ <literal>nr-przebiegu</literal>
+             ustawiony na zero. G³ówny system plików (powinien byæ sprawdzony
+             jako pierwszy) powinien mieæ <literal>nr-przebiegu</literal> o warto¶ci
+             jeden, a inne systemy plików powinny mieæ wpisan± warto¶æ wiêksz± od
+             jednego. Je¶li dwa lub wiêcej systemów plików bêdzie mia³o taki sam
+             <literal>nr-przebiegu</literal>, wówczas &man.fsck.8;, o ile bêdzie
+             to mo¿liwe, podejmie próbê rownoleg³ego sprawdzenia tych systemów
+             plików.</para>
+         </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>Wiêcej informacji o formacie pliku <filename>/etc/fstab</filename>
+        oraz definiowanych w nim opcji dostêpnych w podrêczniku systemowym &man.fstab.5;</para>
+    </sect2>
+
+    <sect2 id="disks-mount">
+      <title>Polecenie <command>mount</command></title>
+      <indexterm>
+	<primary>systemy plików</primary>
+	<secondary>montowanie</secondary>
+      </indexterm>
+        
+      <para>Polecenie &man.mount.8; jest g³ównym poleceniem u¿ywanym
+        do montowania systemów plików.</para>
+        
+      <para>W najprostszej postaci, u¿ywa siê go nastêpuj±co:</para>
+
+      <informalexample>
+	<screen>&prompt.root; <userinput>mount <replaceable>urz±dzenie</replaceable> <replaceable>punkt-montowania</replaceable></userinput></screen>
+      </informalexample>
+
+      <para>Polecenie to ma mnóstwo opcji wymienionych w dokumentacji
+        systemowej &man.mount.8;. Do najczê¶ciej stosowanych nale¿±:</para>
+
+      <variablelist>
+        <title>Opcje montowania</title>
+
+	<varlistentry>
+	  <term><option>-a</option></term>
+            
+	  <listitem>
+            <para>Montowanie wszystkich systemów plików
+              wymienionych w <filename>/etc/fstab</filename>.
+              Nie s± montowane systemy plików z opcj± <quote>noauto</quote>
+              oraz wykluczone przez opcjê <option>-t</option>,
+              jak równie¿ systemy plików ju¿ zamontowane.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><option>-d</option></term>
+            
+	  <listitem>
+            <para>Wykonanie wszystkiego, oprócz faktycznego wywo³ania
+              funkcji systemowej montowania. W po³±czeniu z opcj±
+              <option>-v</option> mo¿na w ten sposób sprawdziæ, co
+              tak naprawdê &man.mount.8; stara siê zrobiæ.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><option>-f</option></term>
+
+	  <listitem>
+            <para>Wymuszenie montowania nieuporz±dkowanego systemu
+              plików (niebezpieczne), lub wymuszenie odebrania prawa
+              do zapisu przy zmianie trybu montowania systemu plików
+              z trybu <quote>odczyt i zapis</quote> na
+              <quote>tylko do odczytu</quote>.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+          <term><option>-r</option></term>
+            
+	  <listitem>
+            <para>Montowanie systemu plików w trybie tylko do odczytu.
+              Taki sam efekt ma zastosowanie opcji  <option>-o</option>
+              z argumentem <option>ro</option> (b±d¼ <option>rdonly</option>
+              w wersjach FreeBSD wcze¶niejszych ni¿ 5.2).</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><option>-t</option>
+	    <replaceable>typ</replaceable></term>
+
+	  <listitem>
+            <para>Montowanie systemu plików o okre¶lonym typie.
+              Przy zastosowaniu opcji <option>-a</option> montowane
+              s± tylko systemy plików podanego typu.</para>
+              
+            <para>Domy¶lnym typem systemu plików jest <quote>ufs</quote>.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><option>-u</option></term>
+            
+	  <listitem>
+            <para>Uaktualnienie opcji montowania systemu plików.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><option>-v</option></term>
+            
+	  <listitem>
+            <para>Pokazywanie dodatkowych komunikatów.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term><option>-w</option></term>
+            
+	  <listitem>
+            <para>Montowanie w trybie odczytu i zapisu.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+        
+      <para>Opcji <option>-o</option> towarzyszy lista oddzielonych
+        przecinkami parametrów, oto niektóre z nich:</para>
+        
+      <variablelist>
+	<varlistentry>
+	  <term>nodev</term>
+            
+	  <listitem>
+            <para>Ignorowanie obecnych w systemie plików urz±dzeñ
+              specjalnych. Przydatna opcja, je¶li chodzi
+              o bezpieczeñstwo.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term>noexec</term>
+            
+	  <listitem>
+            <para>Wy³±czenie uruchamiania programów wykonywalnych
+              na systemie plików. Równie¿ s³u¿y bezpieczeñstwu.</para>
+	  </listitem>
+	</varlistentry>
+          
+	<varlistentry>
+	  <term>nosuid</term>
+            
+	  <listitem>
+            <para>Ignorowanie bitów setuid i setgid w systemie
+              plików. Kolejna opcja s³u¿±ca bezpieczeñstwu.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2 id="disks-umount">
+      <title>Polecenie <command>umount</command> Command</title>
+      <indexterm>
+	<primary>systemy plików</primary>
+	<secondary>odmontowywanie</secondary>
+      </indexterm>
+        
+      <para>Poleceniu &man.umount.8; nale¿y podaæ jako parametr
+        punkt montowania, nazwê urz±dzenia b±d¼ opcjê <option>-a</option> lub
+	<option>-A</option>.</para>
+        
+      <para>Ka¿dej z form wywo³ania polecenia mo¿na podaæ opcjê
+        <option>-f</option>, która nakazuje dokonaæ bezwarunkowego
+        odmontowania, oraz opcjê <option>-v</option>, powoduj±c±
+        wypisywanie dodatkowych komunikatów. Nale¿y mieæ na uwadze,
+        ¿e raczej nie zaleca siê korzystania z <option>-f</option>.
+        Bezwarunkowe odmontowywanie systemu plików mo¿e doprowadziæ
+        do awarii systemu lub uszkodzenia danych znajduj±cych siê
+        w danym systemie plików.</para>
+        
+      <para>Opcje <option>-a</option> oraz <option>-A</option> s³u¿±
+        do odmontowania wszystkich zamontowanych systemów plików,
+        lub systemów plików wybranych typów, okre¶lonych w opcji
+        <option>-t</option>. Opcja <option>-A</option> nie dokonuje
+        próby odmontowania g³ównego systemu plików.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="basics-processes">
+    <title>Procesy</title>
+
+    <para>FreeBSD jest wielozadaniowym systemem operacyjnym. Oznacza
+      to, ¿e korzystaj±c z systemu mamy wra¿enie, ¿e wiele programów
+      dzia³a jednocze¶nie. Dzia³aj±cy w danej chwili program nazywany
+      jest <firstterm>procesem</firstterm>. Po wydaniu dowolnego
+      polecenia uruchamiany jest przynajmniej jeden proces. S± równie¿
+      procesy systemowe, które dzia³aj± nieprzerwanie, zapewniaj±c
+      prawid³owe funkcjonowanie systemu.</para>
+
+    <para>Ka¿demu procesowi przypisany jest jednoznaczny numer zwany
+      <firstterm>identyfikatorem procesu</firstterm>, lub po prostu
+      <firstterm>PID</firstterm>. Podobnie jak plik, równie¿ ka¿dy
+      proces ma swojego w³a¶ciciela i grupê. Na podstawie informacji
+      o w³a¶cicielu i grupie system operacyjny przydziela procesowi
+      prawa do otwierania plików i urz±dzeñ, przy zastosowaniu opisanych
+      wcze¶niej praw dostêpu. Wiêkszo¶æ procesów ma swój proces macierzysty;
+      jest to proces, który uruchomi³ dany proces. Przyk³adowo, kiedy wydajemy
+      polecenia w pow³oce, to zarówno pow³oka jest procesem, jak i ka¿de
+      z wykonanych poleceñ. Procesem macierzystym ka¿dego uruchomionego
+      w ten sposób procesu bêdzie pow³oka. Wyj±tkiem jest specjalny proces
+      zwany &man.init.8;. <command>init</command> jest pierwszym procesem,
+      wiêc jego PID jest zawsze równy 1. Proces <command>init</command>
+      uruchamiany jest przez j±dro systemu podczas ³adowania FreeBSD.</para>
+
+    <para>S± dwa bardzo przydatne polecenia, które pozwalaj± zobaczyæ,
+      jakie procesy s± uruchomione: &man.ps.1; i &man.top.1;. Polecenie
+      <command>ps</command> pokazuje statyczn± listê dzia³aj±cych w danej
+      chwili procesów, uwzglêdniaj±c informacje takie jak PID-y procesów,
+      zu¿ywan± pamiêæ, wydane do uruchomienia procesów polecenia, itd.
+      Polecenie <command>top</command> wy¶wietla listê uruchomionych
+      procesów, która jest co kilka sekund uaktualniana, dziêki czemu mo¿emy
+      na bie¿±co ¶ledziæ, czym zajmuje siê komputer.</para>
+
+    <para>Domy¶lnie <command>ps</command> pokazuje tylko dzia³aj±ce procesy
+      nale¿±ce do u¿ytkownika wydaj±cego polecenie. Na przyk³ad:</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>Jak widzimy, &man.ps.1; wy¶wietla informacje w kilku kolumnach.
+      W kolumnie <literal>PID</literal> pokazywany jest omówiony wcze¶niej
+      identyfikator procesu. PID-y s± przydzielane po kolei od 1 do 99999
+      i znów od pocz±tku, gdy siê skoñcz±. Kolumna <literal>TT</literal>
+      pokazuje terminal, na którym dzia³a program &mdash; na razie nie bêdziemy
+      siê tym zajmowaæ. W kolumnie <literal>STAT</literal> przedstawiony jest
+      stan procesu, jego tak¿e na razie nie bêdziemy omawiaæ. <literal>TIME</literal>
+      pokazuje czas wykorzystywania procesora przez dany proces, niekoniecznie
+      odpowiada on czasowi, jaki up³yn±³ od uruchomienia programu, poniewa¿ wiele
+      programów przez d³ugi czas oczekuje na jakie¶ zdarzenie, a dopiero potem
+      wykorzystuje procesor. Ostatnia kolumna, <literal>COMMAND</literal>, pokazuje
+      polecenie, którym uruchomiony zosta³ program.</para>
+
+    <para>&man.ps.1; ma wiele rozmaitych opcji, które maj± wp³yw na wy¶wietlane
+      informacje. Jedn± z najbardziej przydatnych kombinacji opcji jest
+      <literal>auxww</literal>. Opcja a pokazuje informacje o wszystkich
+      dzia³aj±cych procesach, równie¿ nie nale¿±cych do nas. <option>u</option>
+      pokazuje nazwê u¿ytkownika, do którego nale¿y proces, jak równie¿ wykorzystanie pamiêci.
+      <option>x</option> pokazuje informacje o procesach &mdash; demonach.
+      Opcja <option>ww</option> nakazuje, by polecenie &man.ps.1; wy¶wietla³o
+      pe³n± liniê polecenia, nie obcinaj±c jej, by zmie¶ci³a siê na ekranie.</para>
+
+    <para>Informacje pokazywane przez &man.top.1; wygl±daj± podobnie. Oto przyk³ad:</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>Informacje podzielone s± na dwie czê¶ci. Nag³ówek (pierwsze piêæ
+      wierszy) zawiera PID ostatnio uruchomionego procesu, ¶rednie obci±¿enie
+      systemu (miara zapracowania systemu), czas dzia³ania systemu (od ostatniego
+      uruchonienia) oraz aktualny czas. Inne liczby w nag³ówku informuj± o liczbie
+      dzia³aj±cych procesów (w przyk³adzie 47), jak du¿o pamiêci i przestrzeni
+      wymiany jest zajête, oraz ile czasu system przebywa w ró¿nych stanach
+      procesora.</para>
+
+    <para>Pod nag³ówkiem w kilku kolumnach pokazane s± informacje zbli¿one
+      do przedstawianych przez &man.ps.1;. Podobnie mo¿na tu znale¼æ PID
+      procesu, nazwê u¿ytkownika, czas zajmowania procesora, oraz polecenie,
+      którym uruchomiono proces. &man.top.1; pokazuje domy¶lnie tak¿e rozmiar
+      pamiêci zajmowanej przez proces. Ta ostatnia informacja podzielona jest
+      na dwie kolumny; jedna odpowiada ca³kowitemu rozmiarowi, druga rozmiarowi
+      rezydentnemu. Ca³kowity rozmiar oznacza, ile pamiêci by³o potrzebne programowi,
+      z kolei rozmiar rezydentny informuje, ile pamiêci wykorzystuje program w danej
+      chwili. W przyk³adzie widaæ, ¿e <application>&netscape;</application>
+      potrzebowa³ prawie 30&nbsp;MB pamiêci RAM, jednak obecnie wykorzystuje tylko
+      9&nbsp;MB.</para>
+
+    <para>&man.top.1; automatycznie aktualizuje wy¶wietlane informacje co dwie
+      sekundy; mo¿na to zmieniæ opcj± <option>s</option>.</para>
+  </sect1>
+
+  <sect1 id="basics-daemons">
+    <title>Demony, sygna³y i unicestwianie procesów</title>
+
+    <para>Kiedy korzystamy z edytora tekstu, mo¿emy go w prosty sposób
+      obs³ugiwaæ, wczytywaæ pliki, itp. Jest to mo¿liwe dziêki cechom
+      samego edytora oraz dziêki temu, ¿e edytor jest pod³±czony do
+      <firstterm>terminala</firstterm>. Jednak¿e, niektóre programy
+      pracuj± bez ci±g³ej komunikacji z u¿ytkownikiem, s± wiêc od³±czone
+      od terminala. Przyk³adem takiego programu mo¿e byæ serwer WWW,
+      nieustannie odpowiadaj±cy na ¿±dania pochodz±ce z sieci, bez potrzeby
+      komunikacji z u¿ytkownikiem. Inny przyk³ad to programy przesy³aj±ce
+      emaile pomiêdzy komputerami.</para>
+
+    <para>Takie programy nazywane s± <firstterm>demonami</firstterm> (ang. daemons).
+      Demony to postaci z mitologii greckiej &mdash; niewielkie us³u¿ne istoty,
+      ani dobre, ani z³e, które w rozmaity sposób pomaga³y ludziom. Podobnie
+      pomagaj± dzisiejsze serwery pocztowe i serwery WWW. Dlatego w³a¶nie od
+      d³ugiego czasu maskotk± BSD jest weso³y demon z wid³ami i w</para>
+
+    <para>Przyjêto, i¿ programy uruchamiane jako demony maj± nazwy zakoñczone
+      liter± <quote>d</quote>. <application>BIND</application> (Berkeley Internet
+      Name Daemon) jest serwerem nazw uruchamianym przez program
+      <command>named</command>, serwer WWW <application>Apache</application>
+      nosi nazwê <command>httpd</command>, demon kolejkowania drukarki (line printer
+      spooling daemon) to <command>lpd</command>, itd. Nie jest to sztywna regu³a,
+      lecz przyjêta konwencja; na przyk³ad g³ówny demon pocztowy programu
+      <application>Sendmail</application> nazywa siê <command>sendmail</command>,
+      a nie jak mo¿na by przypuszczaæ <command>maild</command>.</para>
+
+    <para>Niekiedy istnieje potrzeba komunikacji z procesem &mdash; demonem.
+      Odbywa siê ona poprzez <firstterm>signa³y</firstterm>, to znaczy mo¿emy
+      porozumieæ siê z demonem (lub jakimkolwiek dzia³aj±cym procesem) wysy³aj±c
+      mu sygna³. S± ró¿ne rodzaje sygna³ów, które mo¿emy wys³aæ &mdash; niektóre
+      z nich maj± okre¶lone znaczenie, inne s± odpowiednio interpretowane przez
+      aplikacjê, co powinno byæ opisane w dokumentacji aplikacji. Sygna³ mo¿emy
+      wys³aæ tylko do procesu, którego jeste¶my w³a¶cicielem. Wys³anie sygna³u
+      do procesu nale¿±cego do kogo¶ innego za po¶rednictwem &man.kill.1; lub
+      &man.kill.2; spowoduje odmowê dostêpu. Wyj±tkiem jest u¿ytkownik
+      <username>root</username>, który mo¿e wysy³aæ sygna³y do dowolnego
+      procesu, niezale¿nie od jego w³a¶ciciela.</para>
+
+    <para>Zdarza siê, ¿e samo FreeBSD równie¿ wysy³a aplikacjom sygna³y.
+      Je¿eli niew³a¶ciwie napisany program próbuje dostaæ siê do niedostêpnego
+      dla niego obszaru pamiêci, FreeBSD wysy³a procesowi sygna³ <firstterm>Segmentation
+        Violation</firstterm> (<literal>SIGSEGV</literal>). Aplikacja mo¿e skorzystaæ
+      z funkcji systemowej &man.alarm.3;, wówczas po up³yniêciu pewnego czasu
+      zostanie do niej wys³any sygna³ Alarm (<literal>SIGALRM</literal>).
+      I tak dalej.</para>
+
+    <para>Do zatrzymania procesu mo¿na wykorzystaæ dwa sygna³y: <literal>SIGTERM</literal>
+      i <literal>SIGKILL</literal>. Pierwszy z nich jest ³agodnym sposobem
+      unicestwienia procesu; proces mo¿e <emphasis>przechwyciæ</emphasis>
+      ten sygna³, nastêpnie zakoñczyæ swoj± pracê, np. zamykaj±c pliki,
+      które otworzy³. Czasami proces mo¿e zignorowaæ sygna³ <literal>SIGTERM</literal>,
+      je¶li akurat zajmuje siê czym¶, co nie powinno byæ przerywane.</para>
+
+    <para>Sygna³ <literal>SIGKILL</literal> nie mo¿e zostaæ zignorowany.
+      Dzia³a wed³ug zasady <quote>Nie obchodzi mnie, co robisz, w tej
+      chwili przestañ</quote>. Wys³anie procesowi sygna³u <literal>SIGKILL</literal>
+      powoduje, i¿ FreeBSD natychmiast go wstrzymuje<footnote>
+        <para>Nie do koñca jest to prawd± &mdash; w kilku przypadkach nie
+          mo¿na przerwaæ procesu. Na przyk³ad gdy proces stara siê przeczytaæ
+          plik znajduj±cy siê na innym komputerze w sieci, a ów inny komputer
+          z jakiego¶ powodu bêdzie niedostêpny (na skutek awarii sieci,
+          lub po prostu zostanie wy³±czony), to proces stanie siê
+          <quote>nieprzerywalny</quote>. Po chwili (zwykle po dwóch
+          minutach) proces przekroczy czas oczekiwania, wówczas
+          zostanie unicestwiony.</para>
+      </footnote>.</para>
+
+    <para>Inne u¿yteczne sygna³y to
+      <literal>SIGHUP</literal>, <literal>SIGUSR1</literal> i
+      <literal>SIGUSR2</literal>. S± to sygna³y ogólnego przeznaczenia,
+      ró¿ne aplikacje reaguj± na nie w ró¿ny sposób.</para>
+
+    <para>Powiedzmy, ¿e dokonali¶my zmiany w pliku konfiguracji
+      serwera WWW, i chcemy nakazaæ serwerowi, aby konfiguracja zosta³a
+      ponownie wczytana. Mogliby¶my zatrzymaæ i ponownie uruchomiæ
+      <command>httpd</command>, ale ubocznym efektem takiego postêpowania
+      by³aby chwilowa przerwa w pracy serwera, co jest raczej niepo¿±dane.
+      Wiêkszo¶æ demonów dzia³a w taki sposób, i¿ po otrzymaniu sygna³u
+      <literal>SIGHUP</literal> dokonuj± ponownego przeczytania swojego
+      pliku konfiguracyjnego. Dziêki temu zamiast unicestwiania i ponownego
+      uruchamiania <command>httpd</command> mo¿emy wys³aæ mu sygna³
+      <literal>SIGHUP</literal>. Nie jest jednoznacznie okre¶lone,
+      jak procesy reaguj± na sygna³ <literal>SIGHUP</literal>, dlatego
+      ró¿ne demony mog± zachowywaæ siê w ró¿ny sposób &mdash; w razie
+      niepewno¶ci warto zapoznaæ siê z dokumentacj± konkretnego demona.</para>
+    
+    <para>Sygna³y wysy³ane s± przy u¿yciu polecenia &man.kill.1;, jak
+      w poni¿szym przyk³adzie.</para>
+
+    <procedure>
+      <title>Wysy³anie sygna³u do procesu</title>
+
+      <para>W tym przyk³adzie zaprezentowano wysy³anie sygna³u do &man.inetd.8;.
+        Plik konfiguracyjny dla <command>inetd</command> to
+        <filename>/etc/inetd.conf</filename>. Wys³anie sygna³u
+        <literal>SIGHUP</literal> spowoduje ponowne przeczytanie tego pliku.</para>
+
+      <step>
+        <para>Trzeba ustaliæ PID procesu, do którego wysy³aæ bêdziemy sygna³
+          &mdash; do tego celu pos³u¿± polecenia &man.ps.1; i &man.grep.1;.
+          Polecenia &man.grep.1; u¿ywamy do odnalezienia podanego ci±gu
+          znaków. Poniewa¿ polecenia wydajemy jako zwyk³y u¿ytkownik,
+          a &man.inetd.8; dzia³a jako <username>root</username>, polecenie
+          &man.ps.1; musimy wywo³aæ z opcj± <option>ax</option>.</para>
+
+	<screen>&prompt.user; <userinput>ps -ax | grep inetd</userinput>
+  198  ??  IWs    0:00.00 inetd -wW</screen>
+
+	<para>Jak widaæ, &man.inetd.8; ma PID o warto¶ci 198. Niekiedy w
+          przedstawionym powy¿ej przyk³adzie mo¿e siê tak¿e pojawiæ proces
+          <literal>grep inetd</literal>, wynika to ze sposobu, w jaki
+          &man.ps.1; odnajduje dzia³aj±ce procesy.</para>
+      </step>
+
+      <step>
+        <para>Sygna³ wysy³amy przy pomocy polecenia &man.kill.1;.
+          Najpierw skorzystamy jednak z polecenia &man.su.1; by staæ siê
+          rootem, gdy¿ &man.inetd.8; dzia³a jako
+          <username>root</username>.</para>
+
+	<screen>&prompt.user; <userinput>su</userinput>
+<prompt>Password:</prompt>
+&prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen>
+
+	<para>Podobnie jak wiele poleceñ w systemach &unix;, &man.kill.1;
+          nie wy¶wietla ¿adnego komunikatu w przypadku powodzenia. Je¿eli
+          natomiast sygna³ zosta³ wys³any do procesu, którego nie jest siê
+          w³a¶cicielem, pojawi siê informacja: <errorname>kill:
+            <replaceable>PID</replaceable>: Operation not
+	    permitted</errorname> (niedozwolona operacja). B³êdne wpisanie
+          PID-u spowoduje albo wys³anie sygna³u do niew³a¶ciwego procesu,
+          co mo¿e skoñczyæ siê ¼le, albo te¿ wys³anie sygna³u do PID-u,
+          który nie jest w danej chwili wykorzystywany &mdash; pojawi siê
+          wówczas komunikat <errorname>kill:
+	    <replaceable>PID</replaceable>: No such process</errorname>
+          (nie ma takiego procesu).</para>
+
+	<note>
+          <title>Dlaczego warto korzystaæ z <command>/bin/kill</command>?</title>
+
+          <para>W wielu pow³okach polecenie <command>kill</command> jest wbudowane;
+            oznacza to, ¿e sama pow³oka zajmuje siê wysy³aniem sygna³u, nie
+            wywo³uj±c <filename>/bin/kill</filename>. Mo¿e to byæ u¿yteczne,
+            jednak¿e w ró¿nych pow³okach stosowana jest ró¿na sk³adnia do
+            okre¶lenia nazwy sygna³u, który ma byæ wys³any. Zamiast wiêc
+            zapamiêtywania wszystkich mo¿liwych sk³adni, ³atwiej jest po
+            prostu korzystaæ z polecenia
+            <command>/bin/kill <replaceable>...</replaceable></command></para>
+	</note>
+      </step>
+    </procedure>
+
+    <para>Inne sygna³y wysy³a siê t± sam± metod±, wystarczy zast±piæ
+      <literal>TERM</literal> lub <literal>KILL</literal> w odpowiedni
+      sposób.</para>
+
+    <important>
+      <para>nicestwianie losowo wybranego procesu jest raczej z³ym pomys³em.
+        Szczególne znaczenie ma &man.init.8;, proces o PID równym 1.
+        Wydanie polecenia <command>/bin/kill -s KILL 1</command> jest szybk±
+        metod± wy³±czenia systemu. Nale¿y zawsze sprawdzaæ poprawno¶æ
+        argumentów polecenia &man.kill.1;  przed naci¶niêciem klawisza
+        <keycap>Return</keycap>.</para>
+    </important>
+  </sect1>
+
+  <sect1 id="shells">
+    <title>Pow³oki</title>
+    <indexterm><primary>pow³oki</primary></indexterm>
+    <indexterm><primary>linia poleceñ</primary></indexterm>
+
+    <para>W codziennej pracy z FreeBSD bardzo czêsto wykorzystywany jest
+      interfejs linii poleceñ, zwany pow³ok± (ang. shell). Podstawowym
+      zadaniem pow³oki jest przyjmowanie poleceñ i wykonywanie ich.
+      Wiele pow³ok wyposa¿onych jest tak¿e w dodatkowe funkcje u³atwiaj±ce
+      pracê, np. usprawnienia zarz±dzania plikami, dopasowywanie nazw plików,
+      u³atwienia korzystania z linii poleceñ, makropolecenia i zmienne ¶rodowiskowe.
+      We FreeBSD dostêpnych jest kilka pow³ok, np. Bourne Shell <command>sh</command>
+      i ulepszony C-shell <command>tcsh</command>. Wiele innych pow³ok, jak choæby
+      <command>zsh</command> czy <command>bash</command>, mo¿na znale¼æ w kolekcji
+      portów FreeBSD.</para>
+
+    <para>Której z pow³ok najlepiej jest u¿ywaæ? To w³a¶ciwie kwestia gustu.
+      Dla programistów C najwygodniejsze mog± byæ pow³oki o sk³adni wzorowanej
+      na jêzyku C, np. <command>tcsh</command>. U¿ytkownikom Linuxa i tym,
+      dla których interfejs linii poleceñ systemów 8unix; jest nowo¶ci±, mo¿na
+      poleciæ <command>bash</command>. Do wyboru jest wiele pow³ok, ka¿da z nich
+      ma pewne charakterystyczne tylko dla niej w³a¶ciwo¶ci, które niekoniecznie
+      bêd± dzia³aæ w ka¿dych warunkach.</para>
+
+    <para>Czêsto spotykanym udogodnieniem pow³oki jest uzupe³nianie nazw plików.
+      Po wpisaniu kilku pierwszych liter polecenia lub nazwy pliku pow³oka potrafi
+      zwykle uzupe³niæ dalszy ci±g polecenia lub nazwy, dzieje siê to po wci¶niêciu
+      klawisza <keycap>Tab</keycap>. Przyjmijmy przyk³adowo, ¿e istniej± dwa pliki
+      o nazwach <filename>foobar</filename> i <filename>foo.bar</filename>.
+      Chcemy usun±æ plik <filename>foo.bar</filename>. Mo¿emy wiêc wydaæ polecenie:
+      <command>rm fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para>
+
+    <para>Pow³oka wy¶wietli: <command>rm foo[BIIP].bar</command>.</para>
+
+    <para>Napis [BIIP] oznacza sygna³ d¼wiêkowy, bêd±cy informacj± od pow³oki,
+      ¿e uzupe³nienie nazwy pliku nie by³o mo¿liwe, poniewa¿ mo¿na dopasowaæ
+      wiêcej ni¿ jedn± nazwê. Zarówno <filename>foobar</filename> jak i
+      <filename>foo.bar</filename>zaczynaj± siê od <literal>fo</literal>.
+      Pow³oka mog³a jednak¿e uzupe³niæ pocz±tek, czyli <literal>foo</literal>.
+      Teraz mo¿na wpisaæ kropkê <literal>.</literal> i ponownie wcisn±æ
+      <keycap>Tab</keycap>, tym razem pow³oka uzupe³ni nazwê do koñca.</para>
+    <indexterm><primary>zmienne ¶rodowiskowe</primary></indexterm>
+
+    <para>Inn± cech± pow³oki s± zmienne ¶rodowiskowe. Przechowywane s± one
+      w przestrzeni ¶rodowiska pow³oki w postaci par <quote>nazwa =
+        warto¶æ</quote>. Przestrzeñ ¶rodowiska jest widoczna dla ka¿dego
+      programu uruchamianego przez pow³okê, dlatego te¿ przechowuje siê tam
+      wiele parametrów konfiguracyjnych dla programów. Oto najczê¶ciej
+      spotykane zmienne ¶rodowiskowe wraz z krótkim opisem:</para>
+    <indexterm><primary>zmienne ¶rodowiskowe</primary></indexterm>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Zmienna</entry>
+	    <entry>Opis</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry><envar>USER</envar></entry>
+            <entry>Nazwa aktualnie zalogowanego u¿ytkownika.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>PATH</envar></entry>
+            <entry>Lista katalogów zawieraj±cych pliki wykonywalne
+              oddzielona przecinkami.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>DISPLAY</envar></entry>
+            <entry>Nazwa ekranu X11, je¶li takowy jest dostêpny.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>SHELL</envar></entry>
+            <entry>Wykorzystywana pow³oka.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>TERM</envar></entry>
+            <entry>Nazwa terminala u¿ytkownika, wykorzystywana do
+              okre¶lenia w³a¶ciwo¶ci terminala.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>TERMCAP</envar></entry>
+            <entry>Zapis z bazy termcap zawieraj±cy sekwencje kodów
+              odpowiadaj±cych ró¿nym funkcjom terminala.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>OSTYPE</envar></entry>
+            <entry>Typ systemu operacyjnego, np. FreeBSD.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>MACHTYPE</envar></entry>
+            <entry>Architektura sprzêtowa, na jakiej dzia³a system.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>EDITOR</envar></entry>
+            <entry>Preferowany przez u¿ytkownika edytor tekstu.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>PAGER</envar></entry>
+            <entry>Preferowany przez u¿ytkownika program wy¶wietlaj±cy
+              pliki tekstowe.</entry>
+	  </row>
+
+	  <row>
+	    <entry><envar>MANPATH</envar></entry>
+            <entry>Lista katalogów zawieraj±cych dokumentacjê systemow±
+              oddzielona przecinkami.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+
+    <indexterm><primary>Bourne shells</primary></indexterm>
+    <para>Sposób odczytywania i ustawiania zmiennych ¶rodowiskowych
+      zale¿y od rodzaju u¿ywanej pow³oki. Na przyk³ad w pow³okach
+      wzorowanych na C, jak <command>tcsh</command> i <command>csh</command>,
+      do ustawiania i przegl±dania zmiennych ¶rodowiskowych s³u¿y polecenie
+      <command>setenv</command>, natomiast w pow³okach Bourne'a, czyli
+      <command>sh</command> i <command>bash</command>, do tych celów
+      wykorzystywane jest polecenie <command>export</command>. Przyk³adowo,
+      aby zmieniæ zmienn± ¶rodowiskow± <envar>EDITOR</envar> na
+      <filename>/usr/local/bin/emacs</filename> w pow³oce <command>csh</command>
+      lub <command>tcsh</command>, nale¿y wydaæ polecenie:</para>
+
+    <screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen>
+
+    <para>A w pow³okach Bourne'a:</para>
+
+    <screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen>
+
+    <para>W wiêkszo¶ci pow³ok mo¿na wy¶wietliæ warto¶æ zmiennej
+      ¶rodowiskowej przez poprzedzenie jej nazwy znakiem <literal>$</literal>.
+      Dla przyk³adu, polecenie <command>echo $TERM</command> poka¿e warto¶æ
+      zmiennej <envar>$TERM</envar>, poniewa¿ pow³oka zastêpuje wyra¿enie
+      <envar>$TERM</envar> warto¶ci± zmiennej i przekazuje j± do
+      <command>echo</command>.</para>
+
+    <para>Wiele znaków, zwanych meta-znakami, traktowanych jest przez
+      pow³oki w specjalny sposób. Najczê¶ciej wykorzystywanym jest
+      <literal>*</literal>, oznaczaj±cy dowolny ci±g znaków w nazwie pliku,
+      umo¿liwiaj±cy wykonywanie operacji na wielu plikach. Przyk³adowo,
+      wywo³anie <command>echo *</command> jest prawie identyczne z wywo³aniem
+      <command>ls</command>, poniewa¿ pow³oka przekazuje do <command>echo</command>
+      nazwy wszystkich plików pasuj±cych <literal>*</literal>.</para>
+
+    <para>Je¶li potrzeba, by pow³oka nie interpretowa³a znaku jako znak
+      specjalny, nale¿y go poprzedziæ znakiem uko¶nika (<literal>\</literal>).
+      Wywo³anie <command>echo $TERM</command> powoduje wypisanie ustawionego
+      typu terminala, podczas gdy efektem polecenia <command>echo \$TERM</command>
+      jest po prostu napis <envar>$TERM</envar>.</para>
+
+    <sect2 id="changing-shells">
+      <title>Zmiana pow³oki</title>
+
+      <para>Naj³atwiej jest zmieniæ pow³okê przy u¿yciu polecenia <command>chsh</command>.
+        Wywo³anie tego polecenia uruchomi edytor wskazany przez zmienn±
+        <envar>EDITOR</envar>, lub edytor <command>vi</command>, je¶li nie jest ona
+        zdefiniowana. Nastêpnie nale¿y zmieniæ nazwê pow³oki w wierszu
+        <quote>Shell:</quote>.</para>
+
+      <para>Mo¿na te¿ skorzystaæ z <command>chsh</command> z opcj± <option>-s</option>,
+        która automatycznie zmieni pow³okê, bez uruchamiania edytora. Poni¿ej
+        przedstawiono wywo³anie zmieniaj±ce pow³okê na <command>bash</command>:</para>
+	
+      <screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen>
+
+      <note>
+        <para>Wybrana pow³oka <emphasis>musi</emphasis> byæ wymieniona w pliku
+          <filename>/etc/shells</filename>. Je¶li pow³okê zainstalowano z
+          <link linkend="ports">kolekcji portów</link> powinna zostaæ dopisana
+          automatycznie. Je¶li natomiast przeprowadzono rêczn± instalacjê
+          pow³oki, trzeba to zrobiæ samemu.</para>
+     
+      <para>Dla przyk³adu, je¶li pow³oka <command>bash</command> zosta³a zainstalowana
+        i umieszczona w <filename>/usr/local/bin</filename>, trzeba bêdzie wydaæ
+        polecenie:</para>
+
+      <screen>&prompt.root; <userinput>echo &quot;/usr/local/bin/bash&quot; &gt;&gt; /etc/shells</userinput></screen>
+
+       <para>Oraz uruchomiæ <command>chsh</command>.</para>
+     </note>
+   </sect2>
+  </sect1>
+
+  <sect1 id="editors">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Aleksander</firstname>
+          <surname>Fafu³a</surname>
+          <contrib>T³umaczy³ </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Edytory tekstu</title>
+    <indexterm><primary>edytory tekstu</primary></indexterm>
+    <indexterm><primary>edytory</primary></indexterm>
+
+    <para>Konfiguracja FreeBSD polega g³ównie na edytowaniu plików
+      tekstowych. Z tego w³a¶nie powodu, dobrze by³oby zapoznaæ
+      siê z edytorami tekstu. FreeBSD posiada ich kilka, a kolejne
+      mo¿na doinstalowaæ z drzewa portów.</para>
+
+    <indexterm>
+      <primary><command>ee</command></primary>
+    </indexterm>
+    <indexterm>
+      <primary>edytory</primary>
+      <secondary><command>ee</command></secondary>
+    </indexterm>
+    <para>Naj³atwiejszym do nauki i w u¿yciu jest edytor
+      <application>ee</application>, co jest skrótem od Easy Editor
+      (ang. £atwy Edytor). Aby uruchomiæ <application>ee</application>,
+      nale¿y u¿yæ polecenia <command>ee <replaceable>plik</replaceable></command>,
+      gdzie <replaceable>plik</replaceable> jest to, co chcemy edytowaæ.
+      Na przyk³ad, aby wyedytowaæ plik <filename>/etc/rc.conf</filename>,
+      napiszemy <command>ee /etc/rc.conf</command>. Gdy ju¿ jeste¶my w
+      <command>ee</command>, mo¿emy zauwa¿yæ, ¿e wszystkie niezbêdne
+      komendy s± wypisane u góry ekranu. Znak <literal>^</literal> oznacza
+      wci¶niêty klawisz <keycap>Ctrl</keycap>. Innymi s³owy <literal>^e</literal>
+      oznacza, ¿e nale¿y trzymaæ <keycap>Ctrl</keycap> i wcisn±æ klawisz
+      <keycap>e</keycap>. Aby wyj¶æ z <application>ee</application>, wci¶nij
+      <keycap>Esc</keycap>, nastêpnie wybierz leave editor (opu¶æ edytor).
+      Edytor zapyta, czy zachowaæ zmiany, je¶li plik zosta³ zmodyfikowany.</para>
+
+    <indexterm>
+      <primary><command>vi</command></primary>
+    </indexterm>
+    <indexterm>
+      <primary>edytory</primary>
+      <secondary><command>vi</command></secondary>
+    </indexterm>
+    <indexterm>
+      <primary><command>emacs</command></primary>
+    </indexterm>
+    <indexterm>
+      <primary>edytory</primary>
+      <secondary><command>emacs</command></secondary>
+    </indexterm>
+    <para>FreeBSD w swoich zasobach ma tak¿e potê¿ny edytor tekstu, jakim jest
+      <application>vi</application>. W kolekcji portów dostêpny jest tak¿e
+      <application>Emacs</application>, czy <application>vim</application>
+      (<filename role="package">editors/emacs</filename> i
+      <filename role="package">editors/vim</filename>). Edytory te oferuj±
+      du¿o wiêksz± funkcjonalno¶æ, ale oczekuj± w zamian wiêkszego obeznania
+      u¿ytkownika z zasadami ich dzia³ania, ponadto ich obs³uga jest trudniejsza
+      do nauki. Jednak¿e, je¶li planujesz edytowaæ wiele tekstu, nauka
+      <application>Emacs</application> lub <application>vim</application> zwróci
+      siê w d³ugim okresie w postaci zaoszczêdzonego czasu.</para>
+  </sect1>
+
+  <sect1 id="basics-devices">
+    <title>Urz±dzenia i pliki urz±dzeñ</title>
+
+    <para>Mianem urz±dzeñ okre¶la siê komponenty komputera, takie jak dysk,
+      drukarka, karta graficzna czy klawiatura. Podczas ³adowania systemu
+      FreeBSD wiêkszo¶æ wy¶wietlanych komunikatów dotyczy wykrywanych urz±dzeñ.
+      Komunikaty startowe dostêpne s± do pó¼niejszego przegl±dania w pliku
+      <filename>/var/run/dmesg.boot</filename>.</para>
+
+    <para>Przyk³adowo, <devicename>acd0</devicename> odpowiada pierwszemu
+      napêdowi CDROM IDE, natomiast <devicename>kbd0</devicename> oznacza
+      klawiaturê.</para>
+
+    <para>Dostêp do wiêkszo¶ci urz±dzeñ w systemie operacyjnym &unix;
+      odbywa siê poprzez specjalne pliki, zwane plikami urz±dzeñ,
+      znajduj±ce siê w katalogu <filename>/dev</filename>.</para>
+
+    <sect2>
+      <title>Tworzenie plików urz±dzeñ</title>
+      <para>Kiedy wyposa¿amy komputer w nowe urz±dzenie, lub kompilujemy
+        j±dro z obs³ug± dodatkowych urz±dzeñ, konieczne mo¿e okazaæ siê
+        utworzenie nowych plików urz±dzeñ.</para>
+
+      <sect3>
+        <title><literal>DEVFS</literal> (DEVice File System)</title>
+
+        <para>System plików urz±dzeñ, zwany <literal>DEVFS</literal>,
+          udostêpnia przestrzeñ nazw urz±dzeñ j±dra jako czê¶æ przestrzeni
+          nazw g³ównego systemu plików. <literal>DEVFS</literal> zajmuje siê
+          obs³ug± systemu plików urz±dzeñ, dziêki czemu nie trzeba samodzielnie
+          tworzyæ b±d¼ modyfikowaæ plików urz±dzeñ.</para>
+
+        <para>Wiêcej informacji znale¼æ mo¿na w dokumentacji systemowej &man.devfs.5;.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="binary-formats">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Cezary</firstname>
+          <surname>Morga</surname>
+          <contrib>T³umaczy³ </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+    
+    <title>Formaty binarne</title>
+
+    <para>By zrozumieæ czemu FreeBSD u¿ywa formatu &man.elf.5;, musimy wpierw
+      poznaæ trzy obecnie <quote>dominujace</quote> formaty plików wykonywalnych
+      w systemach &unix;:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>&man.a.out.5;</para>
+
+        <para>Najstarszy i najbardziej <quote>klasyczny</quote> format w Uniksie.
+          Wykorzystuje krótki nag³ówek z magicznym numerem na samym pocz±tku,
+          czêsto wykorzystywanym do okre¶lenia rodzaju pliku (szczegó³owy opis
+          dostêpny jest w &man.a.out.5;). Na plik sk³adaj± siê trzy segmenty:
+          .text, .data i .bss oraz tablice symboli i ci±gów tekstowych.</para>
+      </listitem>
+
+      <listitem>
+        <para><acronym>COFF</acronym></para>
+
+        <para>Format obiektowy pochodz±cy z SVR3. W tym formacie sekcja tablic
+          w wchodzi ju¿ w sk³ad nag³ówka, tak wiêc mo¿liwe jest zawarcie w pliku
+          wiêcej sekcji ni¿ tylko .text, .data i .bss.</para>
+      </listitem>
+
+      <listitem>
+        <para>&man.elf.5;</para>
+
+        <para>Nastepca <acronym>COFF</acronym> zawieraj±cy wiele dodatkowych
+          sekcji o 32- b±d¼ nawet 64-bitowych warto¶ciach. Jednym, acz wielkim
+          minusem jest fakt, i¿ przy projektowaniu formatu <acronym>ELF</acronym>
+          równie¿ za³o¿ono, ¿e na ka¿d± architekturê sprzêtow± bêdzie istnia³
+          tylko jeden interfejs ABI. Okaza³o siê natomiast, i¿ takie za³o¿enie
+          jest b³êdne nawet w ¶wiecie komercyjnych SYSV (z którego pochodz±
+          przynajmniej trzy ABI: SVR4, Solaris i SCO).</para>
+
+        <para>Sposobem na rozwi±zanie tego problemu we FreeBSD s± narzêdzia
+          do <emphasis>metkowania</emphasis> plików wykonywalnych
+          <acronym>ELF</acronym> informacjami, z którymi ABI jest on zgodny.
+          Wiêcej informacji dostêpnych jest w podrêczniku systemowym
+          &man.brandelf.1;.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>System FreeBSD pochodzi z <quote>klasycznego</quote> obozu.
+      Wykorzystywa³ on zatem format &man.a.out.5; &mdash; technologiê
+      wypróbowan± w wielu pokoleniach systemów BSD i z powodzeniem
+      stosowan± a¿ do ga³êzi 3.X. Mimo, ¿e skompilowanie i uruchomienie
+      w sposób natywny plików binarnych <acronym>ELF</acronym> (a tak¿e
+      j±dra) by³o mo¿liwe we FreeBSD ju¿ od pewnego czasu, Projekt
+      oficjalnie opiera³ siê przed migracj± do formatu <acronym>ELF</acronym>
+      jako podstawowego. Dlaczego? Otó¿, gdy obóz linuksowy wykona³ ten
+      bolesny krok ku <acronym>ELF</acronym> nie uda³o siê tak ³atwo uciec
+      od formatu <filename>a.out</filename>. Wynika³o to przede wszystkim
+      z faktu, i¿ niezbyt elastyczny plan migracji bazowa³ na mechani¼mie
+      wspó³dzielonych bibliotek, których modyfikacja nastrêcza³a wielu
+      trudno¶ci zarówno producentom sprzêtu jak i projektantom. Dopiero od
+      momentu gdy narzêdzia dostêpne dla <acronym>ELF</acronym> zaoferowa³y
+      sposób rozwi±zania problemu ze wspó³dzielonymi bibliotekami, zaczê³y
+      byæ postrzegane ogólnie jako <quote>droga do przodu</quote>, a tym
+      samym koszty migracji mog³y zostaæ uznane za niezbêdne do poniesienia.
+      Mechanizm wspó³dzielonych bibliotek FreeBSD w du¿ej mierze przypomina
+      mechanizm z &sunos; Sun'a i jako taki jest bardzo ³atwy w u¿yciu.</para>
+
+    <para>Sk±d wiêc tyle ró¿nych formatów?</para>
+
+    <para>W zamierzch³ych czasach do dyspozycji by³ prost sprzêt komputerowy.
+      Ów prosty sprzêt obs³ugiwa³ ma³y, prosty system. St±d te¿ format
+      <filename>a.out</filename>by³ ca³kowicie odpowiednim do prezentacji
+      plików binarnych w tym prostym systemie (PDP-11). Gdy &unix; zosta³
+      przeniesiony z tego prostego systemu na platformy typu Motorola 68k czy
+      VAXen, zachowany zosta³ format <filename>a.out</filename>, zdecydowanie
+      wystarcz±jacy dla wczesnych wersji Uniksa.</para>
+
+    <para>Pewien czas pó¼niej, jaki¶ bystry in¿ynier sprzêtowy stwierdzi³
+      ¿e gdyby potrafi³ zmusiæ oprogramowanie do robienia kilku obskurnych
+      sztuczek, wówczas móg³by pozbyæ siê kilku bramek z uk³adu scalonego
+      i zmusiæ CPU do szybszej pracy. Pomimo, ¿e format <filename>a.out</filename>
+      potrafi³ wspó³pracowaæ z tym nowym rodzajem sprzêtu (zwanego wówczas
+      <acronym>RISC</acronym>) to mimo wszystko nie by³ najlepszym do tego
+      formatem. Dlatego te¿ rozpoczêto prace nad innymi formatami binarnymi,
+      które mia³y osi±gn±æ lepsze wyniki ni¿ ograniczony, prosty <filename>a.out</filename>
+      móg³ zaoferowaæ. Stworzone zosta³y <acronym>COFF</acronym>,
+      <acronym>ECOFF</acronym> oraz kilka mniej znanych formatów, nim powsta³
+      <acronym>ELF</acronym>.</para>
+
+    <para>Kolejnym problemem okaza³ siê wzrost rozmiarów programów przy
+      wzglednie ma³ej pojemno¶ci dysków oraz pamiêci fizycznych, a tak¿e
+      zwiêkszieniu stopnia skomplikowania pamiêci wirtualnej VM. Tak te¿
+      narodzi³a siê koncepcja wspó³dzielonych bibliotek. Mimo, ¿e ów postêp
+      osi±gniêty by³ przy pomocy formatu <filename>a.out</filename> zakres
+      jego przydatno¶ci by³ stale rozci±gany, wraz z ka¿d± now± funkcj±.
+      Pojawi³a siê konieczno¶æ dynamicznego wczytywanie pewnych rzeczy ju¿
+      w trakcie uruchamiania programu czy zapisywania czê¶ci programu zaraz
+      po wykonaniu kodu init w pamiêci lub przestrzeni wymiany. Równie¿ jêzyki
+      programowania stawa³y siê coraz bardziej wyrafinowane. Wiele poprawek
+      wprowadzonych do formatu <filename>a.out</filename> umo¿liwia³y realizacjê
+      kolejnych funkcji, przy czym z regu³y dzia³a³y one tylko przez pewien czas.
+      Niestety, format a.out sta³ siê z czasem niezdolny do rozwi±zywania wszystkich
+      problemów bez wci±¿ rozrastaj±cego siê narzutu w kodzie i poziomu skomplikowania.
+      Mimo, ¿e <acronym>ELF</acronym> potrafi³ rozwi±zaæ wiele z ówczesnych problemów,
+      zmiana formatu binarnego, który generalnie dzia³a³, wci±¿ by³a wielk± uci±¿liwo¶ci±.
+      Dlatego te¿ <acronym>ELF</acronym> musia³ poczekaæ a¿ bardziej bolesnym okaza³o
+      siê pozostanie przy <filename>a.out</filename> niz przej¶cie
+      do <acronym>ELF</acronym>.</para>
+
+    <para>Wraz z up³ywem czasu, narzêdzia kompilacyjne, z których FreeBSD wywodzi
+      w³asne narzêdzia (przede wszystkim assembler i loader), wyewoluowa³y w dwa
+      równoleg³e projekty. Odmiana FreeBSD da³a wspó³dzielone biblioteki oraz poprawki
+      kilku b³êdów. Ludzie z GNU, którzy oryginalnie napisali te programy,
+      przepisali je na nowo i dodali proste kompilatory wskro¶ne, pozwalaj±ce na
+      pracê w ró¿nych formatach. Nowy pakiet narzêdzi GNU
+      (<application>binutils</application>) wspiera kompilowanie wskro¶ne,
+      format <acronym>ELF</acronym>, wspó³dzielone biblioteki, rozszerzenia
+      C++, itp. Dodatkowo, wielu producentów sprzêtu przygotowuje binaria
+      <acronym>ELF</acronym>. Jest to zatem dobra rzecz dla FreeBSD, ¿e
+      je obs³uguje.</para>
+
+    <para>Format <acronym>ELF</acronym> oferuje wiêksz± rozszerzalno¶æ niz
+      <filename>a.out</filename>. Narzêdzia <acronym>ELF</acronym> s± lepiej
+      przygotowywane i oferuj± kompilacjê wskro¶n±, co jest istotne dla wielu
+      programistów. Co prawda <acronym>ELF</acronym> mo¿e byæ trochê wolniejszy
+      ni¿ <filename>a.out</filename>, jednak¿e próba pomiaru mo¿e byæ trudna.
+      Istnieje równie¿ wiele innych szczegó³ów ró¿nych dla obydwu formatów,
+      m.in. sposób mapowania stron, obs³ugi kodu init itp. Co prawda,
+      ¿adne z nich nie jest istotne, jednak¿e ró¿nice istniej±. Z czasem,
+      wsparcie dla <filename>a.out</filename> zostanie wstrzymane z jadra
+      <filename>GENERIC</filename> i ostatecznie usuniête z j±dra gdy tylko
+      zniknie potrzeba obs³ugi programów <filename>a.out</filename>.</para>
+  </sect1>
+
+  <sect1 id="basics-more-information">
+    <title>Wiêcej informacji</title>
+
+    <sect2 id="basics-man">
+      <title>Dokumentacja systemowa</title>
+      <indexterm><primary>podrêcznik systemowy</primary></indexterm>
+
+      <para>Najdok³adniejsz± dokumentacj± we FreeBSD jest dokumentacja
+        systemowa. Dla prawie ka¿dego dostêpnego w systemie programu
+        przygotowana jest krótka instrukcja obs³ugi, omawiaj±ca podstawy
+        jego dzia³ania i rozmaite opcje. Dokumentacjê mo¿emy przegl±daæ
+        przy pomocy polecenia <command>man</command>. Korzystanie z tego
+        polecenia jest bardzo proste:</para>
+
+      <screen>&prompt.user; <userinput>man <replaceable>polecenie</replaceable></userinput></screen>
+
+      <para><literal>polecenie</literal> jest nazw± polecenia, o którym chcemy
+        uzyskaæ informacje. Na przyk³ad, aby dowiedzieæ siê czego¶ na temat
+        polecenia <command>ls</command> wpisujemy:</para>
+
+      <screen>&prompt.user; <userinput>man ls</userinput></screen>
+
+      <para>Dokumentacja systemowa podzielona jest na ponumerowane czê¶ci:</para>
+
+      <orderedlist>
+	<listitem>
+          <para>Polecenia dostêpne dla u¿ytkowników.</para>
+	</listitem>
+
+	<listitem>
+          <para>Funkcje systemowe i kody b³êdów.</para>
+	</listitem>
+
+	<listitem>
+          <para>Funkcje z bibliotek jêzyka C.</para>
+	</listitem>
+
+	<listitem>
+          <para>Sterowniki urz±dzeñ.</para>
+	</listitem>
+
+	<listitem>
+          <para>Formaty plików.</para>
+	</listitem>
+
+	<listitem>
+          <para>Gry i inne rozrywki.</para>
+	</listitem>
+
+	<listitem>
+          <para>Ró¿ne informacje.</para>
+	</listitem>
+
+	<listitem>
+          <para>Polecenia s³u¿±ce do zarz±dzania systemem.</para>
+	</listitem>
+
+	<listitem>
+          <para>Informacje dla programistów j±dra.</para>
+	</listitem>
+      </orderedlist>
+
+      <para>Niekiedy takie samo zagadnienie mo¿e pojawiæ siê w kilku
+        czê¶ciach dokumentacji. Na przyk³ad istnieje polecenie
+        <command>chmod</command>, oraz funkcja systemowa
+        <function>chmod()</function>. W taki wypadku mo¿emy wybraæ
+        interesuj±c± nas czê¶æ dokumentacji, podaj±c jej numer jako
+        parametr polecenia <command>man</command>:</para>
+
+      <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen>
+
+      <para>W efekcie pokazana zostanie dokumentacja polecenia <command>chmod</command>.
+        Zgodnie z przyjêt± konwencj±, numer odpowiedniej czê¶ci dokumentacji
+        podawany jest w nawiasach, tak wiêc &man.chmod.1; odpowiada poleceniu
+        <command>chmod</command>, natomiast &man.chmod.2; odpowiada funkcji
+        systemowej.</para>
+
+      <para>W opisany powy¿ej sposób mo¿emy dowiedzieæ siê, jak korzystaæ
+        z danego polecenia, je¶li znamy jego nazwê. Co zrobiæ, je¶li nie
+        mo¿emy sobie przypomnieæ nazwy polecenia? Otó¿, <command>man</command>
+        potrafi równie¿ wyszukiwaæ wybranych s³ów kluczowych w opisach
+        poleceñ, s³u¿y do tego opcja <option>-k</option>:</para>
+
+      <screen>&prompt.user; <userinput>man -k mail</userinput></screen>
+
+      <para>Wpisanie takiego polecenia spowoduje wy¶wietlenie listy
+        poleceñ, których opisy zawieraj± s³owo kluczowe <quote>mail</quote>.
+        Takie dzia³anie jest równowa¿ne skorzystaniu z polecenia
+        <command>apropos</command>.</para>
+
+      <para>Je¶li wiêc, przegl±daj±c zawarto¶æ katalogu
+        <filename>/usr/bin</filename>, zastanawiamy siê, do czego
+        w³a¶ciwie s³u¿± znajduj±ce siê tam polecenia, mo¿emy wpisaæ:</para>
+
+	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
+&prompt.user; <userinput>man -f *</userinput></screen>
+
+	<para>lub</para>
+
+	<screen>&prompt.user; <userinput>cd /usr/bin</userinput>
+&prompt.user; <userinput>whatis *</userinput></screen>
+
+	<para>W obu przypadkach efekt bêdzie taki sam.</para>
+    </sect2>
+
+    <sect2 id="basics-info">
+      <title>Pliki GNU Info</title>
+      <indexterm><primary>Free Software Foundation</primary></indexterm>
+
+      <para>Do FreeBSD do³±czonych jest wiele programów i narzêdzi
+        stworzonych przez Free Software Foundation (FSF). Prócz
+        dokumentacji systemowej, do tych programów do³±czone s±
+        bardziej rozbudowane dokumenty hipertekstowe, zwane plikami
+        <literal>info</literal>. Mo¿na je przegl±daæ poleceniem
+        <command>info</command>, lub trybem info <application>emacs</application>a,
+        o ile <application>emacs</application> zosta³ zainstalowany.</para>
+
+      <para>By skorzystaæ z polecenia &man.info.1;, wpisujemy:</para>
+
+      <screen>&prompt.user; <userinput>info</userinput></screen>
+
+      <para>Krótkie wprowadzenie pojawia siê po wpisaniu <literal>h</literal>.
+        Spis poleceñ jest dostêpny po wpisaniu <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/pl_PL.ISO8859-2/books/handbook/basics/example-dir1.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir1.dot
new file mode 100644
index 0000000000..f259e8377d
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir1.dot
@@ -0,0 +1,7 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/";
+	root -> "A2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir2.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir2.dot
new file mode 100644
index 0000000000..b846c82399
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir2.dot
@@ -0,0 +1,8 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/" -> "B1/";
+	"A1/" -> "B2/";
+	root -> "A2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir3.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir3.dot
new file mode 100644
index 0000000000..178a3a91bb
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir3.dot
@@ -0,0 +1,8 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/";
+	root -> "A2/" -> "B1/";
+	"A2/" -> "B2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir4.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir4.dot
new file mode 100644
index 0000000000..82d12b421a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir4.dot
@@ -0,0 +1,9 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/";
+	root -> "A2/" -> "B1/" -> "C1/";
+	"B1/" -> "C2/";
+	"A2/" -> "B2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/basics/example-dir5.dot b/pl_PL.ISO8859-2/books/handbook/basics/example-dir5.dot
new file mode 100644
index 0000000000..f5aa6e01dc
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/basics/example-dir5.dot
@@ -0,0 +1,9 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/" -> "C1/";
+	"A1/" -> "C2/";
+	root -> "A2/" -> "B1/";
+	"A2/" -> "B2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/bibliography/Makefile b/pl_PL.ISO8859-2/books/handbook/bibliography/Makefile
new file mode 100644
index 0000000000..f926466a22
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/bibliography/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	bibliography/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/bibliography/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/bibliography/chapter.sgml
new file mode 100644
index 0000000000..aee600218a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/bibliography/chapter.sgml
@@ -0,0 +1,655 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<appendix id="bibliography">
+  <title>Bibliografia</title>
+  
+  <para>While the manual pages provide the definitive reference for individual
+    pieces of the FreeBSD operating system, they are notorious for not
+    illustrating how to put the pieces together to make the whole operating
+    system run smoothly.  For this, there is no substitute for a good book on
+    &unix; system administration and a good users' manual.</para>
+  
+  <sect1 id="bibliography-freebsd">
+    <title>Books &amp; Magazines Specific to FreeBSD</title>
+    
+    <para><emphasis>International books &amp;
+	Magazines:</emphasis></para>
+    
+    <itemizedlist>
+      <listitem>
+	<para><ulink
+	    url="http://jdli.tw.FreeBSD.org/publication/book/freebsd2/index.htm">Using FreeBSD</ulink> (in Chinese).</para>
+      </listitem>
+
+      <listitem>
+
+	<para>FreeBSD Unleashed (Chinese translation), published by 
+	  <ulink url="http://www.hzbook.com/">China Machine
+	    Press</ulink>. ISBN 7-111-10201-0.
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD From Scratch First Edition (in Chinese),
+	  published by China Machine Press. ISBN 7-111-07482-3.
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD From Scratch Second Edition (in Chinese),
+	  published by China Machine Press. ISBN 7-111-10286-X.
+	</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD Handbook (Chinese translation), published by 
+	  <ulink url="http://www.ptpress.com.cn/">Posts &amp; Telecom
+	    Press</ulink>. ISBN 7-115-10541-3.
+	</para>
+      </listitem>
+
+      <listitem>
+
+	<para>FreeBSD 3.x Internet (in Chinese), published by
+	  <ulink url="http://www.tup.tsinghua.edu.cn/">Tsinghua
+	    University Press</ulink>. ISBN 7-900625-66-6.</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD &amp; Windows (in Chinese), ISBN 7-113-03845-X</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD Internet Services HOWTO (in Chinese), ISBN 7-113-03423-3</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA System
+	  Co, LTD.  ISBN 4-87966-468-5 C3055 P2900E.</para>
+      </listitem>
+      
+      <listitem>
+	<para>FreeBSD (in Japanese), published by CUTT.  ISBN 4-906391-22-2
+	  C3055 P2400E.</para>
+      </listitem>
+      
+      <listitem>
+	<para><ulink
+	    url="http://www.shoeisha.com/book/Detail.asp?bid=650">Complete Introduction to FreeBSD</ulink> (in Japanese), published by <ulink url="http://www.shoeisha.co.jp/">Shoeisha Co., Ltd</ulink>.  ISBN 4-88135-473-6 P3600E.</para>
+      </listitem>
+      
+      <listitem>
+	<para><ulink
+	    url="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal UNIX Starter Kit FreeBSD</ulink> (in Japanese), published by <ulink url="http://www.ascii.co.jp/">ASCII</ulink>.  ISBN 4-7561-1733-3 P3000E.</para>
+      </listitem>
+      
+      <listitem>
+	<para>FreeBSD Handbook (Japanese translation), published by <ulink
+	    url="http://www.ascii.co.jp/">ASCII</ulink>.  ISBN 4-7561-1580-2
+	  P3800E.</para>
+      </listitem>
+      
+      <listitem>
+	<para>FreeBSD mit Methode (in German), published by <ulink url="http://www.cul.de">Computer und
+	  Literatur Verlag</ulink>/Vertrieb Hanser, 1998.  ISBN 3-932311-31-0.</para>
+      </listitem>
+      
+      <listitem>
+        <para><ulink
+	    url="http://www.cul.de/freebsd.html">FreeBSD 4 - Installieren, Konfigurieren, Administrieren</ulink>
+	  (in German), published by <ulink url="http://www.cul.de">Computer und Literatur Verlag</ulink>, 2001.
+	  ISBN 3-932311-88-4.</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink
+	    url="http://www.cul.de/freebsd.html">FreeBSD 5 - Installieren, Konfigurieren, Administrieren</ulink>
+	  (in German), published by <ulink url="http://www.cul.de">Computer und Literatur Verlag</ulink>, 2003.
+	  ISBN 3-936546-06-1.</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink url="http://www.mitp.de/vmi/mitp/detail/pWert/1343/">
+	  FreeBSD de Luxe</ulink> (in German), published by
+	  <ulink url="http://www.mitp.de">Verlag Modere Industrie</ulink>,
+	  2003. ISBN 3-8266-1343-0.
+	</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink
+	    url="http://www.pc.mycom.co.jp/FreeBSD/install-manual.html">FreeBSD Install and Utilization Manual</ulink> (in Japanese), published by <ulink url="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</ulink>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil Widodo 
+	<emphasis><ulink url="http://maxwell.itb.ac.id/">
+	Building Internet Server with
+	FreeBSD</ulink></emphasis> (in Indonesia Language), published
+	by <ulink url="http://www.elexmedia.co.id/">Elex Media Komputindo</ulink>.</para>
+      </listitem>
+
+    </itemizedlist>
+    
+    <para><emphasis>English language books &amp; Magazines:</emphasis></para>
+    
+    <itemizedlist>
+      <listitem>
+	<para><ulink url="http://www.AbsoluteBSD.com/">Absolute
+	  BSD: The Ultimate Guide to FreeBSD</ulink>, published by
+	  <ulink url="http://www.nostarch.com/">No Starch Press</ulink>, 2002.
+	  ISBN: 1886411743</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink
+	    url="http://www.freebsdmall.com/cgi-bin/fm/bsdcomp">
+	    The Complete FreeBSD</ulink>, published by
+	    <ulink url="http://www.oreilly.com/">O'Reilly</ulink>, 2003.
+	    ISBN: 0596005164</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink url="http://www.freebsd-corp-net-guide.com/">The
+	  FreeBSD Corporate Networker's Guide</ulink>, published by
+	  <ulink url="http://www.awl.com/aw/">Addison-Wesley</ulink>, 2000.
+	  ISBN: 0201704811</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink url="http://andrsn.stanford.edu/FreeBSD/introbook/">
+	  FreeBSD: An Open-Source Operating System for Your Personal 
+	  Computer</ulink>, published by The Bit Tree Press, 2001.
+	  ISBN: 0971204500</para>
+      </listitem>
+
+      <listitem>
+	<para>Teach Yourself FreeBSD in 24 Hours, published by
+	  <ulink url="http://www.samspublishing.com/">Sams</ulink>, 2002.
+	  ISBN: 0672324245</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD unleashed, published by
+	  <ulink url="http://www.samspublishing.com/">Sams</ulink>, 2002.
+	  ISBN: 0672324563</para>
+      </listitem>
+
+      <listitem>
+	<para>FreeBSD: The Complete Reference, published by
+	  <ulink url="http://books.mcgraw-hill.com">McGrawHill</ulink>, 2003.
+	  ISBN: 0072224096 </para>
+      </listitem>
+
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-userguides">
+    <title>Users' Guides</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Computer Systems Research Group, UC Berkeley.  <emphasis>4.4BSD
+	    User's Reference Manual</emphasis>.  O'Reilly &amp; Associates,
+	  Inc., 1994. ISBN 1-56592-075-9</para>
+      </listitem>
+      
+      <listitem>
+	<para>Computer Systems Research Group, UC Berkeley.  <emphasis>4.4BSD
+	    User's Supplementary Documents</emphasis>. O'Reilly &amp;
+	  Associates, Inc., 1994. ISBN 1-56592-076-7</para>
+      </listitem>
+      
+      <listitem>
+	<para><emphasis>UNIX in a Nutshell</emphasis>.  O'Reilly &amp;
+	  Associates, Inc., 1990. ISBN 093717520X</para>
+      </listitem>
+      
+      <listitem>
+	<para>Mui, Linda.  <emphasis>What You Need To Know When You Can't Find
+	    Your UNIX System Administrator</emphasis>.  O'Reilly &amp;
+	  Associates, Inc., 1995. ISBN 1-56592-104-6</para>
+      </listitem>
+      
+      <listitem>
+	<para><ulink url="http://www-wks.acs.ohio-state.edu/">Ohio State
+	    University</ulink> has written a <ulink
+	    url="http://www-wks.acs.ohio-state.edu/unix_course/unix.html">UNIX
+	    Introductory Course</ulink> which is available online in HTML and
+	  PostScript format.</para>
+
+	<para>An Italian <ulink
+	  url="&url.doc.base;/it_IT.ISO8859-15/books/unix-introduction/index.html">translation</ulink>
+	  of this document is available as part of the FreeBSD Italian
+	  Documentation Project.</para>
+      </listitem>
+      
+      <listitem>
+	<para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, Japan
+	    FreeBSD Users Group</ulink>.  <ulink
+	    url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's
+	    Reference Manual</ulink> (Japanese translation). <ulink
+	    url="http://www.pc.mycom.co.jp/">Mainichi Communications
+	    Inc.</ulink>, 1998.  ISBN4-8399-0088-4 P3800E.</para>
+      </listitem>
+
+      <listitem>
+	<para><ulink url="http://www.ed.ac.uk/">Edinburgh
+	  University</ulink> has written an <ulink
+	  url="http://unixhelp.ed.ac.uk/">Online Guide</ulink> for
+	  newcomers to the UNIX environment.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-adminguides">
+    <title>Administrators' Guides</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Albitz, Paul and Liu, Cricket.  <emphasis>DNS and
+	    BIND</emphasis>, 4th Ed. O'Reilly &amp; Associates, Inc., 2001.
+	  ISBN 1-59600-158-4</para>
+      </listitem>
+      
+      <listitem>
+	<para>Computer Systems Research Group, UC Berkeley.  <emphasis>4.4BSD
+	    System Manager's Manual</emphasis>.  O'Reilly &amp; Associates,
+	  Inc., 1994.  ISBN 1-56592-080-5</para>
+      </listitem>
+      
+      <listitem>
+	<para>Costales, Brian, et al.  <emphasis>Sendmail</emphasis>, 2nd Ed.
+	  O'Reilly &amp; Associates, Inc., 1997. ISBN 1-56592-222-0</para>
+      </listitem>
+      
+      <listitem>
+	<para>Frisch, &AElig;leen.  <emphasis>Essential System
+	    Administration</emphasis>, 2nd Ed. O'Reilly &amp; Associates,
+	  Inc., 1995.  ISBN 1-56592-127-5</para>
+      </listitem>
+      
+      <listitem>
+	<para>Hunt, Craig.  <emphasis>TCP/IP Network
+	    Administration</emphasis>, 2nd Ed. O'Reilly &amp; Associates, Inc., 1997.
+	  ISBN 1-56592-322-7</para>
+      </listitem>
+      
+      <listitem>
+	<para>Nemeth, Evi.  <emphasis>UNIX System Administration
+	    Handbook</emphasis>.  3rd Ed. Prentice Hall, 2000.  ISBN 
+          0-13-020601-6</para>
+      </listitem>
+      
+      <listitem>
+	<para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly
+	  &amp; Associates, Inc., 1991.  ISBN 0-937175-75-7</para>
+      </listitem>
+      
+      <listitem>
+	<para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, Japan
+	    FreeBSD Users Group</ulink>.  <ulink
+	    url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System
+	    Administrator's Manual</ulink> (Japanese translation). <ulink
+	    url="http://www.pc.mycom.co.jp/">Mainichi Communications
+	    Inc.</ulink>, 1998.  ISBN4-8399-0109-0 P3300E.</para>
+      </listitem>
+
+      <listitem>
+	<para>Dreyfus, Emmanuel.  <ulink
+	  url="http://www.eyrolles.com/Informatique/Livre/9782212114638/">Cahiers
+	  de l'Admin: BSD</ulink> 2nd Ed. (in French), Eyrolles, 2004.
+	  ISBN 2-212-11463-X</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-programmers">
+    <title>Programmers' Guides</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Asente, Paul, Converse, Diana, and Swick, Ralph.
+	  <emphasis>X Window System Toolkit</emphasis>.  Digital Press,
+	  1998.  ISBN 1-55558-178-1</para>
+      </listitem>
+      
+      <listitem>
+	<para>Computer Systems Research Group, UC Berkeley.  <emphasis>4.4BSD
+	    Programmer's Reference Manual</emphasis>. O'Reilly &amp;
+	  Associates, Inc., 1994.  ISBN 1-56592-078-3</para>
+      </listitem>
+      
+      <listitem>
+	<para>Computer Systems Research Group, UC Berkeley.  <emphasis>4.4BSD
+	    Programmer's Supplementary Documents</emphasis>.  O'Reilly &amp;
+	  Associates, Inc., 1994.  ISBN 1-56592-079-1</para>
+      </listitem>
+      
+      <listitem>
+	<para>Harbison, Samuel P. and Steele, Guy L. Jr.  <emphasis>C: A
+	    Reference Manual</emphasis>.  4th ed. Prentice Hall, 1995. 
+	  ISBN 0-13-326224-3</para>
+      </listitem>
+      
+      <listitem>
+	<para>Kernighan, Brian and Dennis M. Ritchie.  <emphasis>The C
+	    Programming Language</emphasis>.  2nd Ed. PTR Prentice Hall, 1988.
+	  ISBN 0-13-110362-8</para>
+      </listitem>
+      
+      <listitem>
+	<para>Lehey, Greg.  <emphasis>Porting UNIX Software</emphasis>.
+	  O'Reilly &amp; Associates, Inc., 1995.  ISBN 1-56592-126-7</para>
+      </listitem>
+      
+      <listitem>
+	<para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>.
+	  Prentice Hall, 1992.  ISBN 0-13-131509-9</para>
+      </listitem>
+      
+      <listitem>
+	<para>Spinellis, Diomidis.  <ulink
+	  url="http://www.spinellis.gr/codereading/"><emphasis>Code
+	  Reading: The Open Source Perspective</emphasis></ulink>.
+	  Addison-Wesley, 2003.  ISBN 0-201-79940-5</para>
+      </listitem>
+
+      <listitem>
+	<para>Spinellis, Diomidis.  <ulink
+	  url="http://www.spinellis.gr/codequality/"><emphasis>Code
+	  Quality: The Open Source Perspective</emphasis></ulink>.
+	  Addison-Wesley, 2006.  ISBN 0-321-16607-8</para>
+      </listitem>
+
+      <listitem>
+	<para>Stevens, W. Richard and Stephen A. Rago.
+	<emphasis>Advanced Programming in the UNIX
+	    Environment</emphasis>.  2nd Ed.
+	    Reading, Mass. : Addison-Wesley, 2005.
+	  ISBN 0-201-43307-9</para>
+      </listitem>
+      
+      <listitem>
+	<para>Stevens, W. Richard.  <emphasis>UNIX Network
+	    Programming</emphasis>.  2nd Ed, PTR Prentice Hall, 1998.  ISBN
+	  0-13-490012-X</para>
+      </listitem>
+      
+      <listitem>
+	<para>Wells, Bill.  <quote>Writing Serial Drivers for UNIX</quote>.
+	  <emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994.
+	  pp68-71, 97-99.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-osinternals">
+    <title>Operating System Internals</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Andleigh, Prabhat K.  <emphasis>UNIX System
+	    Architecture</emphasis>.  Prentice-Hall, Inc., 1990.  ISBN 
+          0-13-949843-5</para>
+      </listitem>
+      
+      <listitem>
+	<para>Jolitz, William.  <quote>Porting UNIX to the 386</quote>.
+	  <emphasis>Dr. Dobb's Journal</emphasis>.  January 1991-July
+	  1992.</para>
+      </listitem>
+      
+      <listitem>
+	<para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and
+	  John Quarterman <emphasis>The Design and Implementation of the
+	    4.3BSD UNIX Operating System</emphasis>.  Reading, Mass. :
+	  Addison-Wesley, 1989.  ISBN 0-201-06196-1</para>
+      </listitem>
+      
+      <listitem>
+	<para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design
+	    and Implementation of the 4.3BSD UNIX Operating System: Answer
+	    Book</emphasis>.  Reading, Mass. : Addison-Wesley, 1991.  ISBN 
+          0-201-54629-9</para>
+      </listitem>
+      
+      <listitem>
+	<para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and
+	  John Quarterman.  <emphasis>The Design and Implementation of the
+	    4.4BSD Operating System</emphasis>.  Reading, Mass. :
+	  Addison-Wesley, 1996.  ISBN 0-201-54979-4</para>
+
+	<para>(Chapter 2 of this book is available <ulink
+	  url="&url.books.design-44bsd;/book.html">online</ulink> as part of
+	  the FreeBSD Documentation Project, and chapter 9 <ulink
+	  url="http://www.netapp.com/tech_library/nfsbook.html">
+	  here</ulink>.)</para>
+      </listitem>
+      
+      <listitem>
+	<para>Marshall Kirk McKusick, George V. Neville-Neil <emphasis>The Design
+	    and Implementation of the FreeBSD Operating System</emphasis>.
+	    Boston, Mass. : Addison-Wesley, 2004.  ISBN 0-201-70245-2</para>
+      </listitem>
+
+      <listitem>
+	<para>Stevens, W. Richard.  <emphasis>TCP/IP Illustrated, Volume 1:
+	    The Protocols</emphasis>.  Reading, Mass. : Addison-Wesley,
+	  1996.  ISBN 0-201-63346-9</para>
+      </listitem>
+      
+      <listitem>
+	<para>Schimmel, Curt.  <emphasis>Unix Systems for Modern
+	    Architectures</emphasis>.  Reading, Mass. : Addison-Wesley, 1994.
+	  ISBN 0-201-63338-8</para>
+      </listitem>
+      
+      <listitem>
+	<para>Stevens, W. Richard.  <emphasis>TCP/IP Illustrated, Volume 3:
+	    TCP for Transactions, HTTP, NNTP and the UNIX Domain
+	    Protocols</emphasis>.  Reading, Mass. : Addison-Wesley, 1996.
+	  ISBN 0-201-63495-3</para>
+      </listitem>
+      
+      <listitem>
+	<para>Vahalia, Uresh.  <emphasis>UNIX Internals -- The New
+	    Frontiers</emphasis>.  Prentice Hall, 1996.  ISBN 
+          0-13-101908-2</para>
+      </listitem>
+      
+      <listitem>
+	<para>Wright, Gary R. and W. Richard Stevens.  <emphasis>TCP/IP
+	    Illustrated, Volume 2: The Implementation</emphasis>. Reading,
+	  Mass. : Addison-Wesley, 1995.  ISBN 0-201-63354-X</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-security">
+    <title>Security Reference</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls
+	    and Internet Security: Repelling the Wily Hacker</emphasis>.
+	  Reading, Mass. : Addison-Wesley, 1995.  ISBN
+	  0-201-63357-4</para>
+      </listitem>
+      
+      <listitem>
+	<para>Garfinkel, Simson and Gene Spafford.
+	  <emphasis>Practical UNIX &amp; Internet Security</emphasis>.
+	  2nd Ed. O'Reilly &amp; Associates, Inc., 1996.  ISBN
+	  1-56592-148-8</para>
+      </listitem>
+      
+      <listitem>
+	<para>Garfinkel, Simson.  <emphasis>PGP Pretty Good
+	    Privacy</emphasis> O'Reilly &amp; Associates, Inc., 1995.  ISBN 
+          1-56592-098-8</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-hardware">
+    <title>Hardware Reference</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Anderson, Don and Tom Shanley.  <emphasis>Pentium Processor
+	    System Architecture</emphasis>.  2nd Ed. Reading, Mass. :
+	  Addison-Wesley, 1995.  ISBN 0-201-40992-5</para>
+      </listitem>
+      
+      <listitem>
+	<para>Ferraro, Richard F.  <emphasis>Programmer's Guide to the EGA,
+	    VGA, and Super VGA Cards</emphasis>.  3rd ed. Reading, Mass. :
+	  Addison-Wesley, 1995.  ISBN 0-201-62490-7</para>
+      </listitem>
+      
+      <listitem>
+	<para>Intel Corporation publishes documentation on their CPUs,
+	  chipsets and standards on their <ulink
+	    url="http://developer.intel.com/">developer web site</ulink>,
+	  usually as PDF files.</para>
+      </listitem>
+      
+      <listitem>
+	<para>Shanley, Tom.  <emphasis>80486 System Architecture</emphasis>.
+	  3rd ed. Reading, Mass. : Addison-Wesley, 1995.  ISBN
+	  0-201-40994-1</para>
+      </listitem>
+      
+      <listitem>
+	<para>Shanley, Tom.  <emphasis>ISA System Architecture</emphasis>.
+	  3rd ed. Reading, Mass. : Addison-Wesley, 1995.  ISBN
+	  0-201-40996-8</para>
+      </listitem>
+      
+      <listitem>
+	<para>Shanley, Tom.  <emphasis>PCI System Architecture</emphasis>.
+	  4th ed. Reading, Mass. : Addison-Wesley, 1999.  ISBN
+	  0-201-30974-2</para>
+      </listitem>
+      
+      <listitem>
+	<para>Van Gilluwe, Frank.  <emphasis>The Undocumented PC</emphasis>, 2nd Ed.
+	  Reading, Mass: Addison-Wesley Pub. Co., 1996.  ISBN
+	  0-201-47950-8</para>
+      </listitem>
+
+      <listitem>
+	<para>Messmer, Hans-Peter.  <emphasis>The Indispensable PC Hardware Book</emphasis>, 4th Ed.
+	  Reading, Mass: Addison-Wesley Pub. Co., 2002.  ISBN
+	  0-201-59616-4</para>
+      </listitem>
+
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-history">
+    <title>&unix; History</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With
+	    Source Code</emphasis>.  ITP Media Group, 1996.  ISBN
+	  1573980137</para>
+      </listitem>
+      
+      <listitem>
+	<para>Raymond, Eric S.  <emphasis>The New Hacker's Dictionary, 3rd
+	    edition</emphasis>.  MIT Press, 1996.  ISBN
+	  0-262-68092-0.  Also known as the <ulink
+	    url="http://www.catb.org/~esr/jargon/html/index.html">Jargon
+	    File</ulink></para>
+      </listitem>
+      
+      <listitem>
+	<para>Salus, Peter H.  <emphasis>A quarter century of UNIX</emphasis>.
+	  Addison-Wesley Publishing Company, Inc., 1994.  ISBN
+	  0-201-54777-5</para>
+      </listitem>
+      
+      <listitem>
+	<para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The
+	    UNIX-HATERS Handbook</emphasis>.  IDG Books Worldwide, Inc.,
+	  1994.  ISBN 1-56884-203-1.  Out of print, but available <ulink
+	    url="http://research.microsoft.com/~daniel/unix-haters.html">
+	    online</ulink>.</para>
+      </listitem>
+      
+      <listitem>
+	<para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis>
+	  &mdash; special edition.  Prentice-Hall, Inc., 1989.  ISBN 
+          0-13-536657-7</para>
+      </listitem>
+      
+      <listitem>
+	<para><emphasis>The BSD family tree</emphasis>.
+	  <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree"></ulink>
+	   or <ulink type="html" url="file://localhost/usr/share/misc/bsd-family-tree"><filename>/usr/share/misc/bsd-family-tree</filename></ulink>
+	   on a FreeBSD machine.</para>
+      </listitem>
+      
+      <listitem>
+	<para><emphasis>The BSD Release Announcements collection</emphasis>.
+	  1997.  <ulink url="http://www.de.FreeBSD.org/de/ftp/releases/"></ulink></para>
+      </listitem>
+      
+      <listitem>
+	<para><emphasis>Networked Computer Science Technical Reports
+	    Library</emphasis>.  <ulink url="http://www.ncstrl.org/"></ulink></para>
+      </listitem>
+      
+      <listitem>
+	<para><emphasis>Old BSD releases from the Computer Systems Research
+	  group (CSRG)</emphasis>.
+	  <ulink url="http://www.mckusick.com/csrg/"></ulink>:
+	  The 4CD set covers all BSD versions from 1BSD to 4.4BSD and
+	  4.4BSD-Lite2 (but not 2.11BSD, unfortunately).  The last
+	  disk also holds the final sources plus the SCCS files.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="bibliography-journals">
+    <title>Magazines and Journals</title>
+    
+    <itemizedlist>
+      <listitem>
+	<para><emphasis>The C/C++ Users Journal</emphasis>.  R&amp;D
+	  Publications Inc.  ISSN 1075-2838</para>
+      </listitem>
+      
+      <listitem>
+	<para><emphasis>Sys Admin &mdash; The Journal for UNIX System
+	    Administrators</emphasis> Miller Freeman, Inc., ISSN
+	  1061-2688</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>freeX &mdash; Das Magazin f&uuml;r Linux - BSD - UNIX</emphasis>
+	  (in German) Computer- und Literaturverlag GmbH, ISSN 1436-7033</para>
+      </listitem>
+
+    </itemizedlist>
+  </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/pl_PL.ISO8859-2/books/handbook/book.sgml b/pl_PL.ISO8859-2/books/handbook/book.sgml
new file mode 100644
index 0000000000..b2d52e5db4
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/book.sgml
@@ -0,0 +1,343 @@
+<!--
+     The FreeBSD Polish Documentation Project
+
+     $FreeBSD$
+     Original revision: 1.166
+-->
+
+<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
+<!ENTITY % books.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN">
+%books.ent;
+<!ENTITY % chapters SYSTEM "chapters.ent">
+%chapters;
+<!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.geom "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.firewalls "IGNORE">
+<!ENTITY % chap.network-servers "IGNORE">
+<!ENTITY % chap.mail "IGNORE">
+<!ENTITY % chap.cutting-edge "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 % chap.freebsd-glossary "IGNORE">
+<!ENTITY % chap.mac "IGNORE">
+<!ENTITY % chap.audit "IGNORE">
+
+<!ENTITY % pgpkeys SYSTEM "../../../share/pgpkeys/pgpkeys.ent"> %pgpkeys;
+]>
+
+<book lang="pl">
+  <bookinfo>
+    <title>Podrêcznik FreeBSD</title>
+    
+    <corpauthor>Projekt Dokumentacji FreeBSD</corpauthor>
+    
+    <pubdate>Luty 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>
+      <year>2004</year>
+      <year>2005</year>
+      <year>2006</year>
+      <holder>Projekt Dokumentacji FreeBSD</holder>
+    </copyright>
+
+    &bookinfo.legalnotice;
+
+    <legalnotice id="trademarks" role="trademarks">
+      &tm-attrib.freebsd;
+      &tm-attrib.3com;
+      &tm-attrib.3ware;
+      &tm-attrib.arm;
+      &tm-attrib.adaptec;
+      &tm-attrib.adobe;
+      &tm-attrib.apple;
+      &tm-attrib.corel;
+      &tm-attrib.creative;
+      &tm-attrib.cvsup;
+      &tm-attrib.heidelberger;
+      &tm-attrib.ibm;
+      &tm-attrib.ieee;
+      &tm-attrib.intel;
+      &tm-attrib.intuit;
+      &tm-attrib.linux;
+      &tm-attrib.lsilogic;
+      &tm-attrib.m-systems;
+      &tm-attrib.macromedia;
+      &tm-attrib.microsoft;
+      &tm-attrib.netscape;
+      &tm-attrib.nexthop;
+      &tm-attrib.opengroup;
+      &tm-attrib.oracle;
+      &tm-attrib.powerquest;
+      &tm-attrib.realnetworks;
+      &tm-attrib.redhat;
+      &tm-attrib.sap;
+      &tm-attrib.sun;
+      &tm-attrib.symantec;
+      &tm-attrib.themathworks;
+      &tm-attrib.thomson;
+      &tm-attrib.usrobotics;
+      &tm-attrib.vmware;
+      &tm-attrib.waterloomaple;
+      &tm-attrib.wolframresearch;
+      &tm-attrib.xfree86;
+      &tm-attrib.xiph;
+      &tm-attrib.general;
+    </legalnotice>
+    
+    <abstract>
+      <para>Witamy w ¶wiecie FreeBSD! Zadaniem niniejszego podrêcznika jest
+        opisanie procesu instalacji i czynno¶ci zwi±zanych z codziennym
+        u¿ytkowaniem systemu FreeBSD w wersji <emphasis>&rel2.current;-RELEASE</emphasis>
+        oraz <emphasis>&rel.current;-RELEASE</emphasis>. Prace nad tym podrêcznikiem
+        trwaj± <emphasis>ca³y czas</emphasis>. Stanowi on dzie³o wielu osób z
+        ca³ego ¶wiata. Tym nie mniej mamy ¶wiadomo¶æ, i¿ wiele rozdzia³ów wci±¿
+        nie zosta³o napisanych, a niektóre spo¶ród istniej±cych wymagaj± aktualizacji.
+        Je¶li jeste¶ zainteresowany pomoc± w rozwoju projektu wy¶lij email na adres
+        &a.pl.doc.d;. Najnowsza wersja anglojêzyczna niniejszego dokumentu jest
+        zawsze dostêpna na <ulink
+	  url="http://www.FreeBSD.org/">stronie domowej FreeBSD</ulink>
+        (wersje wcze¶niejsze dostêpne s± pod adresem <ulink
+	  url="http://docs.FreeBSD.org/doc/"></ulink>). Podrêcznik dostêpny jest
+        równie¿ w innych formatach dokumentów oraz w postaci skompresowanej z <ulink 
+          url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">serwera FTP Projektu
+          FreeBSD</ulink> b±d¼ jednego z wielu <link
+	  linkend="mirrors-ftp">serwerów lustrzanych</link>. Dla osób zainteresowanych,
+        drukowan± wersjê podrêcznika (jêzyk ang.) mo¿na nabyæ wprost z witryny <ulink
+	  url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>. Dostêpne jest
+        równie¿ <ulink
+	  url="&url.base;/search/index.html">przeszukiwanie podrêcznika</ulink>.</para>
+    </abstract>
+  </bookinfo>
+
+  &chap.preface;
+
+  <part id="getting-started">
+    <title>Pierwsze kroki</title>
+    
+    <partintro>
+      <para>Ta czê¶æ Podrêcznika FreeBSD adresowana jest do u¿ytkowników i
+        administratorów, który nie mieli dotychczas kontaktu z systemem FreeBSD.
+        Niniejsze rozdzia³y maj± za zadanie:</para>
+
+      <itemizedlist>
+	<listitem>
+          <para>Zaprezentowaæ system FreeBSD.</para>
+	</listitem>
+
+	<listitem>
+          <para>Przeprowadziæ przez proces instalacji.</para>
+	</listitem>
+
+	<listitem>
+          <para>Nauczyæ podstaw systemu &unix;.</para>
+	</listitem>
+
+	<listitem>
+          <para>Pokazaæ jak zainstalowaæ programy innych autorów, dostêpne w ogromnej
+            ilo¶ci dla systemu FreeBSD.</para>
+	</listitem>
+
+	<listitem>
+          <para>Przedstawiæ system X - system okien &unix;, oraz szczegó³owo wyja¶niæ
+            jak prawid³owo skonfigurowaæ ¶rodowisko graficzne, tak by zwiêkszyæ
+            efektywno¶æ swej pracy.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Starali¶my siê sprowadziæ liczbê odno¶ników wewn±trz tekstu do mo¿liwie
+        najmniejszej, tak by zminimalizowaæ ilo¶æ <quote>przeskoków</quote> i u³atwiæ
+        czytanie Podrêcznika od deski do deski.</para>
+    </partintro>
+
+    <![ %chap.introduction;             [ &chap.introduction;         ]]>
+    <![ %chap.install;                  [ &chap.install;              ]]>
+    <![ %chap.basics;                   [ &chap.basics;               ]]>
+    <![ %chap.ports;                    [ &chap.ports;                ]]>
+    <![ %chap.x11;                      [ &chap.x11;                  ]]>
+  </part>
+  
+  <part id="common-tasks">
+    <title>Codzienne czynno¶ci</title>
+    
+    <partintro>
+      <para>Now that the basics have been covered, this part of the
+        FreeBSD Handbook will discuss some frequently used features of
+        FreeBSD.  These chapters:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Introduce you to popular and useful desktop
+	    applications: browsers, productivity tools, document
+	    viewers, etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Introduce you to a number of multimedia tools
+	  available for FreeBSD.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Explain the process of building a customized FreeBSD
+	  kernel, to enable extra functionality on your system.</para>
+	</listitem>
+
+        <listitem>
+          <para>Describe the print system in detail, both for desktop
+          and network-connected printer setups.</para>
+        </listitem>
+
+        <listitem>
+          <para>Show you how to run Linux applications on your FreeBSD
+          system.</para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>Some of these chapters recommend that you do some prior
+	reading, and this is noted in the synopsis at the beginning of
+	each chapter.</para>
+
+    </partintro>
+
+    <![ %chap.desktop;                  [ &chap.desktop;              ]]>
+    <![ %chap.multimedia;               [ &chap.multimedia;           ]]>
+    <![ %chap.kernelconfig;             [ &chap.kernelconfig;         ]]>
+    <![ %chap.printing;                 [ &chap.printing;             ]]>
+    <![ %chap.linuxemu;                 [ &chap.linuxemu;             ]]>
+  </part>
+
+  <part id="system-administration">
+    <title>Administracja systemem</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.security;                 [ &chap.security;             ]]>
+    <![ %chap.mac;			[ &chap.mac;		      ]]>
+    <![ %chap.audit;			[ &chap.audit;		      ]]>
+    <![ %chap.disks;                    [ &chap.disks;                ]]>
+    <![ %chap.geom;			[ &chap.geom;		      ]]>
+    <![ %chap.vinum;                    [ &chap.vinum;                ]]>
+    <![ %chap.l10n;                     [ &chap.l10n;                 ]]>
+    <![ %chap.cutting-edge;             [ &chap.cutting-edge;         ]]>
+  </part>
+
+  <part id="network-communication">
+    <title>Komunikacja sieciowa</title>
+
+    <partintro>
+      <para>FreeBSD is one of the most widely deployed operating
+        systems for high performance network servers.  The chapters in
+        this part cover:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Serial communication</para>
+        </listitem>
+
+        <listitem>
+          <para>PPP and PPP over Ethernet</para>
+        </listitem>
+
+        <listitem>
+          <para>Electronic Mail</para>
+        </listitem>
+
+        <listitem>
+          <para>Running Network Servers</para>
+        </listitem>
+
+        <listitem>
+          <para>Firewalls</para>
+        </listitem>
+
+        <listitem>
+          <para>Other Advanced Networking Topics</para>
+        </listitem>
+      </itemizedlist>
+
+      <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 in a network environment.</para>
+    </partintro>
+
+    <![ %chap.serialcomms;              [ &chap.serialcomms;          ]]>
+    <![ %chap.ppp-and-slip;             [ &chap.ppp-and-slip;         ]]>
+    <![ %chap.mail;                     [ &chap.mail;                 ]]>
+    <![ %chap.network-servers;          [ &chap.network-servers;      ]]>
+    <![ %chap.firewalls;                [ &chap.firewalls;            ]]>
+    <![ %chap.advanced-networking;      [ &chap.advanced-networking;  ]]>
+
+  </part>
+  
+  <part id="appendices">
+    <title>Dodatki</title>
+    
+    <![ %chap.mirrors;                  [ &chap.mirrors;              ]]>
+    <![ %chap.bibliography;             [ &chap.bibliography;         ]]>
+    <![ %chap.eresources;               [ &chap.eresources;           ]]>
+    <![ %chap.pgpkeys;                  [ &chap.pgpkeys;              ]]>
+  </part>
+  <![ %chap.freebsd-glossary;         [ &bookinfo.freebsd-glossary; ]]>
+  <![ %chap.index;                    [ &chap.index;                ]]>
+  &chap.colophon;
+</book>
+
+<!-- 
+     Local Variables:
+     mode: sgml
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/boot/Makefile b/pl_PL.ISO8859-2/books/handbook/boot/Makefile
new file mode 100644
index 0000000000..92105efc40
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/boot/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	boot/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/boot/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/boot/chapter.sgml
new file mode 100644
index 0000000000..267f81ecc0
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/boot/chapter.sgml
@@ -0,0 +1,820 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="boot">
+  <title>The FreeBSD Booting Process</title>
+
+  <sect1 id="boot-synopsis">
+    <title>Synopsis</title>
+    <indexterm><primary>booting</primary></indexterm>
+    <indexterm><primary>bootstrap</primary></indexterm>
+
+    <para>The process of starting a computer and loading the operating system
+      is referred to as <quote>the bootstrap process</quote>, or simply
+      <quote>booting</quote>.  FreeBSD's boot process provides a great deal of
+      flexibility in customizing what happens when you start the system,
+      allowing you to select from different operating systems installed on the
+      same computer, or even different versions of the same operating system
+      or installed kernel.</para>
+
+    <para>This chapter details the configuration options you can set and how
+      to customize the FreeBSD boot process.  This includes everything that
+      happens until the FreeBSD kernel has started, probed for devices, and
+      started &man.init.8;.  If you are not quite sure when this happens, it
+      occurs when the text color changes from bright white to grey.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>What the components of the FreeBSD bootstrap system are, and how
+	  they interact.</para>
+      </listitem>
+
+      <listitem>
+	<para>The options you can give to the components in the FreeBSD
+	  bootstrap to control the boot process.</para>
+      </listitem>
+      
+      <listitem>
+        <para>The basics of &man.device.hints.5;.</para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <title>x86 Only</title>
+
+      <para>This chapter only describes the boot process for FreeBSD running
+	on Intel x86 systems.</para>
+    </note>
+  </sect1>
+
+  <sect1 id="boot-introduction">
+    <title>The Booting Problem</title>
+
+    <para>Turning on a computer and starting the operating system poses an
+      interesting dilemma.  By definition, the computer does not know how to
+      do anything until the operating system is started.  This includes
+      running programs from the disk.  So if the computer can not run a
+      program from the disk without the operating system, and the operating
+      system programs are on the disk, how is the operating system
+      started?</para>
+
+    <para>This problem parallels one in the book <citetitle>The Adventures of
+      Baron Munchausen</citetitle>.  A character had fallen part way down a
+      manhole, and pulled himself out by grabbing his bootstraps, and
+      lifting.  In the early days of computing the term
+      <firstterm>bootstrap</firstterm> was applied to the mechanism used to
+      load the operating system, which has become shortened to
+      <quote>booting</quote>.</para>
+
+    <indexterm><primary>BIOS</primary></indexterm>
+
+    <indexterm><primary>Basic Input/Output System</primary><see>BIOS</see></indexterm>
+
+    <para>On x86 hardware the Basic Input/Output System (BIOS) is responsible
+      for loading the operating system.  To do this, the BIOS looks on the
+      hard disk for the Master Boot Record (MBR), which must be located on a
+      specific place on the disk.  The BIOS has enough knowledge to load and
+      run the MBR, and assumes that the MBR can then carry out the rest of the
+      tasks involved in loading the operating system,
+      possibly with the help of the BIOS.</para>
+
+    <indexterm><primary>Master Boot Record (MBR)</primary></indexterm>
+
+    <indexterm><primary>Boot Manager</primary></indexterm>
+
+    <indexterm><primary>Boot Loader</primary></indexterm>
+
+    <para>The code within the MBR is usually referred to as a <emphasis>boot
+      manager</emphasis>, especially when it interacts with the user.  In this case
+      the boot manager usually has more code in the first
+      <emphasis>track</emphasis> of the disk or within some OS's file system.  (A
+      boot manager is sometimes also called a <emphasis>boot loader</emphasis>,
+      but FreeBSD uses that term for a later stage of booting.) Popular boot
+      managers include <application>boot0</application> (a.k.a. <application>Boot
+      Easy</application>, the standard &os; boot manager),
+      <application>Grub</application>, <application>GAG</application>, and
+      <application>LILO</application>.
+      (Only <application>boot0</application> fits within the MBR.)</para>
+
+    <para>If you have only one operating system installed on your disks then
+      a standard PC MBR will suffice.  This MBR searches for the first bootable
+      (a.k.a. active) slice on the disk, and then runs the code on that slice to
+      load the remainder of the operating system.  The MBR installed by
+      &man.fdisk.8;, by default, is such an MBR.  It is based on
+      <filename>/boot/mbr</filename>.</para>
+
+    <para>If you have installed multiple operating systems on your disks then
+      you can install a different boot manager, one that can display a list of
+      different operating systems, and allows you to choose the one to boot
+      from.  Two of these are discussed in the next subsection.</para>
+
+    <para>The remainder of the FreeBSD bootstrap system is divided into three
+      stages.  The first stage is run by the MBR, which knows just enough to
+      get the computer into a specific state and run the second stage.  The
+      second stage can do a little bit more, before running the third stage.
+      The third stage finishes the task of loading the operating system.  The
+      work is split into these three stages because the PC standards put
+      limits on the size of the programs that can be run at stages one and
+      two.  Chaining the tasks together allows FreeBSD to provide a more
+      flexible loader.</para>
+
+    <indexterm><primary>kernel</primary></indexterm>
+    <indexterm><primary><command>init</command></primary></indexterm>
+
+    <para>The kernel is then started and it begins to probe for devices
+      and initialize them for use.  Once the kernel boot
+      process is finished, the kernel passes control to the user process
+      &man.init.8;, which then makes sure the disks are in a usable state.
+      &man.init.8; then starts the user-level resource configuration which
+      mounts file systems, sets up network cards to communicate on the
+      network, and generally starts all the processes that usually
+      are run on a FreeBSD system at startup.</para>
+  </sect1>
+
+  <sect1 id="boot-blocks">
+    <title>The Boot Manager and Boot Stages</title>
+
+    <indexterm><primary>Boot Manager</primary></indexterm>
+
+    <sect2 id="boot-boot0">
+      <title>The Boot Manager</title>
+      <indexterm><primary>Master Boot Record (MBR)</primary></indexterm>
+
+      <para>The code in the MBR or boot manager is sometimes referred to as
+        <emphasis>stage zero</emphasis> of the boot process.  This subsection
+        discusses two of the boot managers previously mentioned:
+        <application>boot0</application> and <application>LILO</application>.</para>
+
+      <formalpara><title>The <application>boot0</application> Boot Manager:</title>
+        <para>The MBR installed by FreeBSD's installer or &man.boot0cfg.8;, by
+          default, is based on <filename>/boot/boot0</filename>.
+          (The <application>boot0</application> program is very simple, since the
+          program in the <abbrev>MBR</abbrev> can only be 446 bytes long because of the slice
+          table and <literal>0x55AA</literal> identifier at the end of the MBR.)
+          If you have installed <application>boot0</application> and
+          multiple operating systems on your hard disks, then you will see a
+          display similar to this one at boot time:</para></formalpara>
+
+      <example id="boot-boot0-example">
+	<title><filename>boot0</filename> Screenshot</title>
+
+	<screen>F1 DOS
+F2 FreeBSD
+F3 Linux
+F4 ??
+F5 Drive 1
+
+Default: F2</screen>
+      </example>
+
+      <para>Other operating systems, in particular &windows;, have been known
+	to overwrite an existing MBR with their own.  If this happens to you,
+	or you want to replace your existing MBR with the FreeBSD MBR then use
+	the following command:</para>
+
+      <screen>&prompt.root; <userinput>fdisk -B -b /boot/boot0 <replaceable>device</replaceable></userinput></screen>
+
+      <para>where <replaceable>device</replaceable> is the device that you
+	boot from, such as <devicename>ad0</devicename> for the first IDE
+	disk, <devicename>ad2</devicename> for the first IDE disk on a second
+	IDE controller, <devicename>da0</devicename> for the first SCSI disk,
+	and so on.  Or, if you want a custom configuration of the MBR,
+	use &man.boot0cfg.8;.</para>
+
+      <formalpara><title>The LILO Boot Manager:</title>
+
+	<para>To install this boot manager so it will also boot FreeBSD, first
+	  start Linux and add the following to your existing
+	  <filename>/etc/lilo.conf</filename> configuration file:</para></formalpara>
+
+      <programlisting>other=/dev/hdXY
+table=/dev/hdX
+loader=/boot/chain.b
+label=FreeBSD</programlisting>
+
+      <para>In the above, specify FreeBSD's primary partition and drive using
+	Linux specifiers, replacing <replaceable>X</replaceable> with the Linux
+	drive letter and <replaceable>Y</replaceable> with the Linux primary
+	partition number.  If you are using a <acronym>SCSI</acronym> drive, you
+	will need to change <replaceable>/dev/hd</replaceable> to read something
+	similar to <replaceable>/dev/sd</replaceable>.  The
+	<option>loader=/boot/chain.b</option> line can be omitted if you have
+	both operating systems on the same drive.  Now run
+	<command>/sbin/lilo&nbsp;-v</command> to commit your new changes to the
+	system; this should be verified by checking its screen messages.</para>
+    </sect2>
+  
+    <sect2 id="boot-boot1">
+      <title>Stage One, <filename>/boot/boot1</filename>, and Stage Two,
+	<filename>/boot/boot2</filename></title>
+      
+      <para>Conceptually the first and second stages are part of the same
+	program, on the same area of the disk.  Because of space constraints
+	they have been split into two, but you would always install them
+	together.  They are copied from the combined file
+	<filename>/boot/boot</filename> by the installer or
+	<application>bsdlabel</application> (see below).</para>
+
+      <para>They are located outside file systems, in the first track of
+	the boot slice, starting with the first sector.  This is where <link
+	linkend="boot-boot0">boot0</link>, or any other boot manager,
+	expects to find a program to run which will
+	continue the boot process.  The number of sectors used is easily
+	determined from the size of <filename>/boot/boot</filename>.</para>
+
+      <para><filename>boot1</filename> is very simple, since it
+	can only be 512 bytes
+	in size, and knows just enough about the FreeBSD
+	<firstterm>bsdlabel</firstterm>, which stores information
+	about the slice, to find and execute <filename>boot2</filename>.</para>
+      
+      <para><filename>boot2</filename> is slightly more sophisticated, and understands
+	the FreeBSD file system enough to find files on it, and can
+	provide a simple interface to choose the kernel or loader to
+	run.</para>
+
+      <para>Since the <link linkend="boot-loader">loader</link> is
+	much more sophisticated, and provides a nice easy-to-use
+	boot configuration, <filename>boot2</filename> usually runs
+	it, but previously it
+	was tasked to run the kernel directly.</para>
+
+      <example id="boot-boot2-example">
+	<title><filename>boot2</filename> Screenshot</title>
+
+	<screen>&gt;&gt; FreeBSD/i386 BOOT
+Default: 0:ad(0,a)/boot/loader
+boot:</screen>
+      </example>
+
+      <para>If you ever need to replace the installed
+	<filename>boot1</filename> and <filename>boot2</filename> use
+	&man.bsdlabel.8;:</para>
+      
+      <screen>&prompt.root; <userinput>bsdlabel -B <replaceable>diskslice</replaceable></userinput></screen>
+
+      <para>where <replaceable>diskslice</replaceable> is the disk and slice
+	you boot from, such as <devicename>ad0s1</devicename> for the first
+	slice on the first IDE disk.</para>
+
+      <warning>
+	<title>Dangerously Dedicated Mode</title>
+
+	<para>If you use just the disk name, such as
+	  <devicename>ad0</devicename>, in the &man.bsdlabel.8; command you
+	  will create a dangerously dedicated disk, without slices.  This is
+	  almost certainly not what you want to do, so make sure you double
+	  check the &man.bsdlabel.8; command before you press
+	  <keycap>Return</keycap>.</para>
+      </warning>
+    </sect2>
+
+  <sect2 id="boot-loader">
+    <title>Stage Three, <filename>/boot/loader</filename></title>
+
+    <indexterm><primary>boot-loader</primary></indexterm>
+    <para>The loader is the final stage of the three-stage
+      bootstrap, and is located on the file system, usually as
+      <filename>/boot/loader</filename>.</para>
+      
+    <para>The loader is intended as a user-friendly method for
+      configuration, using an easy-to-use built-in command set,
+      backed up by a more powerful interpreter, with a more complex
+      command set.</para> 
+
+    <sect3 id="boot-loader-flow">
+      <title>Loader Program Flow</title>
+      
+      <para>During initialization, the loader will probe for a
+	console and for disks, and figure out what disk it is
+	booting from.  It will set variables accordingly, and an
+	interpreter is started where user commands can be passed from
+	a script or interactively.</para>
+      <indexterm><primary>loader</primary></indexterm>
+      <indexterm><primary>loader configuration</primary></indexterm>
+
+      <para>The loader will then read
+	<filename>/boot/loader.rc</filename>, which by default reads
+	in <filename>/boot/defaults/loader.conf</filename> which
+	sets reasonable defaults for variables and reads
+	<filename>/boot/loader.conf</filename> for local changes to
+	those variables.  <filename>loader.rc</filename> then acts
+	on these variables, loading whichever modules and kernel are
+	selected.</para>
+
+      <para>Finally, by default, the loader issues a 10 second wait
+	for key presses, and boots the kernel if it is not interrupted.
+	If interrupted, the user is presented with a prompt which
+	understands the easy-to-use command set, where the user may
+	adjust variables, unload all modules, load modules, and then
+	finally boot or reboot.</para>
+
+    </sect3>
+    
+    <sect3 id="boot-loader-commands">
+      <title>Loader Built-In Commands</title>
+      
+      <para>These are the most commonly used loader commands.  For a
+        complete discussion of all available commands, please see
+        &man.loader.8;.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>autoboot <replaceable>seconds</replaceable></term>
+
+	  <listitem>
+	    <para>Proceeds to boot the kernel if not interrupted
+	      within the time span given, in seconds.  It displays a
+	      countdown, and the default time span is 10
+	      seconds.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>boot
+	    <optional><replaceable>-options</replaceable></optional>
+	    <optional><replaceable>kernelname</replaceable></optional></term>
+
+	  <listitem>
+	    <para>Immediately proceeds to boot the kernel, with the
+	      given options, if any, and with the kernel name given,
+	      if it is.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>boot-conf</term>
+
+	  <listitem>
+	    <para>Goes through the same automatic configuration of
+	      modules based on variables as what happens at boot.
+	      This only makes sense if you use
+	      <command>unload</command> first, and change some
+	      variables, most commonly <envar>kernel</envar>.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>help
+	    <optional><replaceable>topic</replaceable></optional></term>
+
+	  <listitem>
+	    <para>Shows help messages read from
+	      <filename>/boot/loader.help</filename>.  If the topic
+	      given is <literal>index</literal>, then the list of
+	      available topics is given.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>include <replaceable>filename</replaceable>
+	    &hellip;</term>
+
+	  <listitem>
+	    <para>Processes the file with the given filename.  The
+	      file is read in, and interpreted line by line.  An
+	      error immediately stops the include command.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>load <optional><option>-t</option>
+	    <replaceable>type</replaceable></optional>
+	    <replaceable>filename</replaceable></term>
+
+	  <listitem>
+	    <para>Loads the kernel, kernel module, or file of the
+	      type given, with the filename given.  Any arguments
+	      after filename are passed to the file.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>ls <optional><option>-l</option></optional>
+	    <optional><replaceable>path</replaceable></optional></term>
+
+	  <listitem>
+	    <para>Displays a listing of files in the given path, or
+	      the root directory, if the path is not specified.  If
+	      <option>-l</option> is specified, file sizes will be
+	      shown too.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>lsdev <optional><option>-v</option></optional></term>
+
+	  <listitem>
+	    <para>Lists all of the devices from which it may be
+	      possible to load modules. If <option>-v</option> is
+	      specified, more details are printed.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>lsmod <optional><option>-v</option></optional></term>
+
+	  <listitem>
+	    <para>Displays loaded modules. If <option>-v</option> is
+	      specified, more details are shown.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>more <replaceable>filename</replaceable></term>
+
+	  <listitem>
+	    <para>Displays the files specified, with a pause at each
+	      <varname>LINES</varname> displayed.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>reboot</term>
+
+	  <listitem>
+	    <para>Immediately reboots the system.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>set <replaceable>variable</replaceable></term>
+	  <term>set
+	    <replaceable>variable</replaceable>=<replaceable>value</replaceable></term>
+
+	  <listitem>
+	    <para>Sets the loader's environment variables.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>unload</term>
+
+	  <listitem>
+	    <para>Removes all loaded modules.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect3>
+
+    <sect3 id="boot-loader-examples">
+      <title>Loader Examples</title>
+
+      <para>Here are some practical examples of loader usage:</para>
+
+      <itemizedlist>
+	<indexterm><primary>single-user mode</primary></indexterm>
+	<listitem>
+	  <para>To simply boot your usual kernel, but in single-user
+	    mode:</para>
+
+	  <screen><userinput>boot -s</userinput></screen>
+	</listitem>
+
+	<listitem>
+	  <para>To unload your usual kernel and modules, and then
+	    load just your old (or another) kernel:</para>
+    <indexterm>
+      <primary><filename>kernel.old</filename></primary>
+    </indexterm>
+
+	  <screen><userinput>unload</userinput>
+<userinput>load <replaceable>kernel.old</replaceable></userinput></screen>
+
+	  <para>You can use <filename>kernel.GENERIC</filename> to
+	    refer to the generic kernel that comes on the install
+	    disk, or <filename>kernel.old</filename> to refer to
+	    your previously installed kernel (when you have upgraded
+	    or configured your own kernel, for example).</para>
+
+	  <note>
+	    <para>Use the following to load your usual modules with
+	      another kernel:</para>
+
+	    <screen><userinput>unload</userinput>
+<userinput>set kernel="<replaceable>kernel.old</replaceable>"</userinput>
+<userinput>boot-conf</userinput></screen></note>
+	</listitem>
+
+	<listitem>
+	  <para>To load a kernel configuration script (an automated
+	    script which does the things you would normally do in the
+	    kernel boot-time configurator):</para>
+
+	  <screen><userinput>load -t userconfig_script <replaceable>/boot/kernel.conf</replaceable></userinput></screen>
+	</listitem>
+      </itemizedlist>
+  </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="boot-kernel">
+    <title>Kernel Interaction During Boot</title>
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>boot interaction</secondary>
+    </indexterm>
+    
+    <para>Once the kernel is loaded by either <link
+	linkend="boot-loader">loader</link> (as usual) or <link
+	linkend="boot-boot1">boot2</link> (bypassing the loader), it
+      examines its boot flags, if any, and adjusts its behavior as
+      necessary.</para>
+
+    <sect2 id="boot-kernel-bootflags">
+      <indexterm>
+        <primary>kernel</primary>
+        <secondary>bootflags</secondary>
+      </indexterm>
+      <title>Kernel Boot Flags</title>
+
+      <para>Here are the more common boot flags:</para>
+
+      <variablelist id="boot-kernel-bootflags-list">
+	<varlistentry>
+	  <term><option>-a</option></term>
+
+	  <listitem>
+	    <para>during kernel initialization, ask for the device
+	      to mount as the root file system.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-C</option></term>
+
+	  <listitem>
+	    <para>boot from CDROM.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-c</option></term>
+
+	  <listitem>
+	    <para>run UserConfig, the boot-time kernel
+	      configurator</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-s</option></term>
+
+	  <listitem>
+	    <para>boot into single-user mode</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-v</option></term>
+
+	  <listitem>
+	    <para>be more verbose during kernel startup</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <note>
+	<para>There are other boot flags, read &man.boot.8; for more
+	  information on them.</para></note>
+    </sect2>
+
+<!--    <sect2 id="boot-kernel-userconfig">
+      <title>UserConfig: the Boot-time Kernel Configurator</title>
+      
+      <para> </para>
+    </sect2> -->
+  </sect1>
+  
+  <sect1 id="device-hints">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 18 OCT 2002 -->
+    </sect1info>
+    <indexterm>
+      <primary>device.hints</primary>
+    </indexterm>
+    <title>Device Hints</title>
+
+    <note><para>This is a FreeBSD&nbsp;5.0 and later feature which does not
+      exist in earlier versions.</para></note>
+
+    <para>During initial system startup, the boot &man.loader.8; will read the
+      &man.device.hints.5; file.  This file stores kernel boot information
+      known as variables, sometimes referred to as <quote>device hints</quote>.
+      These <quote>device hints</quote> are used by device drivers for device
+      configuration.</para>
+      
+    <para>Device hints may also be specified at the <link linkend="boot-loader">
+      Stage 3 boot loader</link> prompt.  Variables can be added using
+      <command>set</command>, removed with <command>unset</command>, and viewed
+      with the <command>show</command> commands.  Variables set in the
+      <filename>/boot/device.hints</filename> file can be overridden here also.  Device hints entered at
+      the boot loader are not permanent and will be forgotten on the next
+      reboot.</para>
+
+    <para>Once the system is booted, the &man.kenv.1; command can be used to
+      dump all of the variables.</para>
+
+    <para>The syntax for the <filename>/boot/device.hints</filename> file is one variable per line, using
+      the standard hash <quote>#</quote> as comment markers.  Lines are
+      constructed as follows:</para>
+
+    <screen><userinput>hint.driver.unit.keyword="<replaceable>value</replaceable>"</userinput></screen>
+
+    <para>The syntax for the Stage 3 boot loader is:</para>
+    <screen><userinput>set hint.driver.unit.keyword=<replaceable>value</replaceable></userinput></screen>
+
+    <para><literal>driver</literal> is the device driver name, <literal>unit</literal>
+      is the device driver unit number, and <literal>keyword</literal> is the hint
+      keyword.  The keyword may consist of the following options:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>at</literal>: specifies the bus which the device is attached to.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>port</literal>: specifies the start address of the <acronym>I/O</acronym>
+	  to be used.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>irq</literal>: specifies the interrupt request number to be used.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>drq</literal>: specifies the DMA channel number.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>maddr</literal>: specifies the physical memory address occupied by the
+	  device.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>flags</literal>: sets various flag bits for the device.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>disabled</literal>: if set to <literal>1</literal> the device is disabled.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Device drivers may accept (or require) more hints not listed here, viewing
+      their manual page is recommended.  For more information, consult the
+      &man.device.hints.5;, &man.kenv.1;, &man.loader.conf.5;, and &man.loader.8;
+      manual pages.</para>
+  </sect1>
+
+  <sect1 id="boot-init">
+    <indexterm>
+      <primary><command>init</command></primary>
+    </indexterm>
+    <title>Init: Process Control Initialization</title>
+	
+    <para>Once the kernel has finished booting, it passes control to
+      the user process &man.init.8;, which is located at
+      <filename>/sbin/init</filename>, or the program path specified
+      in the <envar>init_path</envar> variable in
+      <command>loader</command>.</para>
+
+    <sect2 id="boot-autoreboot">
+      <title>Automatic Reboot Sequence</title>
+      
+      <para>The automatic reboot sequence makes sure that the
+	file systems available on the system are consistent.  If they
+	are not, and &man.fsck.8; cannot fix the
+	inconsistencies, &man.init.8; drops the system
+	into <link linkend="boot-singleuser">single-user mode</link>
+	for the system administrator to take care of the problems
+	directly.</para>
+    </sect2>
+
+    <sect2 id="boot-singleuser">
+      <title>Single-User Mode</title>
+      <indexterm><primary>single-user mode</primary></indexterm>
+      <indexterm><primary>console</primary></indexterm>
+      
+      <para>This mode can be reached through the <link
+	  linkend="boot-autoreboot">automatic reboot
+	  sequence</link>, or by the user booting with the
+	<option>-s</option> option or setting the
+	<envar>boot_single</envar> variable in
+	<command>loader</command>.</para>
+
+      <para>It can also be reached by calling
+	&man.shutdown.8; without the reboot
+	(<option>-r</option>) or halt (<option>-h</option>) options,
+	from <link linkend="boot-multiuser">multi-user
+	  mode</link>.</para>
+
+      <para>If the system <literal>console</literal> is set
+	to <literal>insecure</literal> in <filename>/etc/ttys</filename>,
+	then the system prompts for the <username>root</username> password
+	before initiating single-user mode.</para>
+
+      <example id="boot-insecure-console">
+	<title>An Insecure Console in <filename>/etc/ttys</filename></title>
+
+	<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 insecure</programlisting>
+      </example>
+
+      <note>
+	<para>An <literal>insecure</literal> console means that you
+	  consider your physical security to the console to be
+	  insecure, and want to make sure only someone who knows the
+	  <username>root</username> password may use single-user mode, and it
+	  does not mean that you want to run your console insecurely.  Thus,
+	  if you want security, choose <literal>insecure</literal>,
+	  not <literal>secure</literal>.</para>
+      </note>
+    </sect2>
+    
+    <sect2 id="boot-multiuser">
+      <title>Multi-User Mode</title>
+      <indexterm><primary>multi-user mode</primary></indexterm>
+      
+      <para>If &man.init.8; finds your file systems to be
+	in order, or once the user has finished in <link
+	  linkend="boot-singleuser">single-user mode</link>, the
+	system enters multi-user mode, in which it starts the
+	resource configuration of the system.</para>
+
+      <sect3 id="boot-rc">
+      <indexterm><primary>rc files</primary></indexterm>
+	<title>Resource Configuration (rc)</title>
+
+	<para>The resource configuration system reads in
+	  configuration defaults from
+	  <filename>/etc/defaults/rc.conf</filename>, and
+	  system-specific details from
+	  <filename>/etc/rc.conf</filename>, and then proceeds to
+	  mount the system file systems mentioned in
+	  <filename>/etc/fstab</filename>, start up networking
+	  services, start up miscellaneous system daemons, and
+	  finally runs the startup scripts of locally installed
+	  packages.</para>
+
+	<para>The &man.rc.8; manual page is a good reference to the resource
+	  configuration system, as is examining the scripts
+	  themselves.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="boot-shutdown">
+    <title>Shutdown Sequence</title>
+    <indexterm>
+      <primary><command>shutdown</command></primary>
+    </indexterm>
+
+    <para>Upon controlled shutdown, via &man.shutdown.8;,
+      &man.init.8; will attempt to run the script
+      <filename>/etc/rc.shutdown</filename>, and then proceed to send
+      all processes the <literal>TERM</literal> signal, and subsequently 
+      the <literal>KILL</literal> signal to any that do not terminate 
+      timely.</para>
+
+    <para>To power down a FreeBSD machine on architectures and systems
+      that support power management, simply use the command
+      <command>shutdown -p now</command> to turn the power off
+      immediately.  To just reboot a FreeBSD system, just use
+      <command>shutdown -r now</command>.  You need to be
+      <username>root</username> or a member of
+      <groupname>operator</groupname> group to run &man.shutdown.8;.
+      The &man.halt.8; and &man.reboot.8; commands can also be used,
+      please refer to their manual pages and to &man.shutdown.8;'s one
+      for more information.</para>
+
+    <note>
+      <para>Power management requires &man.acpi.4; support in the kernel
+	or loaded as module for.</para>
+    </note>
+
+  </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/pl_PL.ISO8859-2/books/handbook/chapter.decl b/pl_PL.ISO8859-2/books/handbook/chapter.decl
new file mode 100644
index 0000000000..3aac7b965b
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/chapter.decl
@@ -0,0 +1,2 @@
+<!-- $FreeBSD$ -->
+<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
diff --git a/pl_PL.ISO8859-2/books/handbook/chapters.ent b/pl_PL.ISO8859-2/books/handbook/chapters.ent
new file mode 100644
index 0000000000..476882f131
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/chapters.ent
@@ -0,0 +1,60 @@
+<!-- 
+     Creates entities for each chapter in the FreeBSD Handbook. Each entity
+     is named chap.foo, where foo is the value of the id attribute on that
+     chapter, and corresponds to the name of the directory in which that
+     chapter's .sgml file is stored.
+   
+     Chapters should be listed in the order in which they are referenced.
+ 
+     $FreeBSD$
+     Original revision: 1.35
+-->
+
+<!ENTITY chap.preface			SYSTEM "preface/preface.sgml">
+
+<!-- Part one -->
+<!ENTITY chap.introduction		SYSTEM "introduction/chapter.sgml">
+<!ENTITY chap.install			SYSTEM "install/chapter.sgml">
+<!ENTITY chap.basics			SYSTEM "basics/chapter.sgml">
+<!ENTITY chap.ports			SYSTEM "ports/chapter.sgml">
+<!ENTITY chap.x11			SYSTEM "x11/chapter.sgml">
+
+<!-- Part two -->
+<!ENTITY chap.desktop			SYSTEM "desktop/chapter.sgml">
+<!ENTITY chap.multimedia		SYSTEM "multimedia/chapter.sgml">
+<!ENTITY chap.kernelconfig		SYSTEM "kernelconfig/chapter.sgml">
+<!ENTITY chap.printing			SYSTEM "printing/chapter.sgml">
+<!ENTITY chap.linuxemu			SYSTEM "linuxemu/chapter.sgml">
+
+<!-- Part three -->
+<!ENTITY chap.config			SYSTEM "config/chapter.sgml">
+<!ENTITY chap.boot			SYSTEM "boot/chapter.sgml">
+<!ENTITY chap.users			SYSTEM "users/chapter.sgml">
+<!ENTITY chap.security			SYSTEM "security/chapter.sgml">
+<!ENTITY chap.mac			SYSTEM "mac/chapter.sgml">
+<!ENTITY chap.audit			SYSTEM "audit/chapter.sgml">
+<!ENTITY chap.disks			SYSTEM "disks/chapter.sgml">
+<!ENTITY chap.geom			SYSTEM "geom/chapter.sgml">
+<!ENTITY chap.vinum			SYSTEM "vinum/chapter.sgml">
+<!ENTITY chap.l10n			SYSTEM "l10n/chapter.sgml">
+<!ENTITY chap.cutting-edge		SYSTEM "cutting-edge/chapter.sgml">
+
+<!-- Part four -->
+<!ENTITY chap.serialcomms		SYSTEM "serialcomms/chapter.sgml">
+<!ENTITY chap.ppp-and-slip		SYSTEM "ppp-and-slip/chapter.sgml">
+<!ENTITY chap.mail			SYSTEM "mail/chapter.sgml">
+<!ENTITY chap.network-servers		SYSTEM "network-servers/chapter.sgml">
+<!ENTITY chap.firewalls		        SYSTEM "firewalls/chapter.sgml">
+<!ENTITY chap.advanced-networking	SYSTEM "advanced-networking/chapter.sgml">
+
+<!-- Part five (appendices) -->
+<!ENTITY chap.mirrors			SYSTEM "mirrors/chapter.sgml">
+<!ENTITY chap.mirrors.ftp.inc		SYSTEM "mirrors.sgml.ftp.inc">
+<!ENTITY chap.mirrors.cvsup.inc		SYSTEM "mirrors.sgml.cvsup.inc">
+
+<!ENTITY chap.bibliography		SYSTEM "bibliography/chapter.sgml">
+<!ENTITY chap.eresources		SYSTEM "eresources/chapter.sgml">
+<!ENTITY chap.eresources.www.inc	SYSTEM "eresources.sgml.www.inc">
+<!ENTITY chap.pgpkeys			SYSTEM "pgpkeys/chapter.sgml">
+<!ENTITY chap.index			SYSTEM "index.sgml">
+<!ENTITY chap.colophon			SYSTEM "colophon.sgml">
diff --git a/pl_PL.ISO8859-2/books/handbook/colophon.sgml b/pl_PL.ISO8859-2/books/handbook/colophon.sgml
new file mode 100644
index 0000000000..a3cc069be4
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/colophon.sgml
@@ -0,0 +1,30 @@
+<!--
+     The FreeBSD Polish Documentation Project
+
+     $FreeBSD$
+     Original revision: 1.9
+-->
+
+<colophon id='colophon'>
+  <para>Niniejsza ksi±¿ka jest dzie³em setek osób z <quote>Projektu
+    Dokumentacji FreeBSD</quote>. Tekst jest przygotowywany w jêzyku
+    SGML zgodnie ze standardem DocBook DTD, a nastêpnie konwertowany do
+    ca³ej rzeszy innych formatów za pomoc± modu³u DSSSL
+    <application>Jade</application>. Instrukcje formatowania tekstu
+    zosta³y przygotowane przy wykorzystaniu arkuszy styli DSSSL Norma
+    Walsha. Przygotowanie wersji do wydruku nie by³oby mo¿liwe gdyby nie
+    jêzyk sk³adu tekstu <application>&tex;</application> Donalda Knutha,
+    <application>LaTeX</application> Lesliego Lamporta, czy makra
+    <application>JadeTeX</application> Sebastiana Rahtza.</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/pl_PL.ISO8859-2/books/handbook/config/Makefile b/pl_PL.ISO8859-2/books/handbook/config/Makefile
new file mode 100644
index 0000000000..40c8e11572
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/config/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	config/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/config/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/config/chapter.sgml
new file mode 100644
index 0000000000..959bd62835
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/config/chapter.sgml
@@ -0,0 +1,3223 @@
+<!--
+     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 id="config-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm><primary>system configuration</primary></indexterm>
+    <indexterm><primary>system optimization</primary></indexterm>
+
+    <para>One of the important aspects of &os; is system configuration.
+      Correct system configuration will help prevent headaches during future upgrades.
+      This chapter will explain much of the &os; configuration process,
+      including some of the parameters which
+      can be set to tune a &os; 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 and test a network card.</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 &os; 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 &os; basics (<xref
+	    linkend="basics">).</para>
+      </listitem>
+      <listitem>
+	<para>Be familiar with 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.bsdlabel.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>
+
+	<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, even if swap is 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>	. /etc/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 file sizes show 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">
+    <sect1info>
+      <authorgroup>
+        <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Starting Services</title>
+
+    <indexterm><primary>services</primary></indexterm>
+
+    <para>Many users choose to install third party software on &os;
+      from the Ports Collection.  In many of these situations it
+      may be necessary to configure the software in a manner which
+      will allow it to be started upon system initialization.  Services,
+      such as <filename role="package">mail/postfix</filename> or
+      <filename role="package">www/apache13</filename> are just two
+      of the many software packages which may be started during system
+      initialization.  This section explains the procedures available
+      for starting third party software.</para>
+
+    <para>In &os;, most included services, such as &man.cron.8;, are
+      started through the system start up scripts.  These scripts may
+      differ depending on &os; or vendor version; however, the most
+      important aspect to consider is that their start up configuration
+      can be handled through simple startup scripts.</para>
+
+    <para>Before the advent of <filename>rc.d</filename>, applications would drop a
+      simple start up script into the
+      <filename class="directory">/usr/local/etc/rc.d</filename>
+      directory which would be read by the system initialization
+      scripts.  These scripts would then be executed during the latter
+      stages of system start up.</para>
+
+    <para>While many individuals have spent hours trying to merge the
+      old configuration style into the new system, the fact remains
+      that some third party utilities still require a script simply
+      dropped into the aforementioned directory.  The subtle differences
+      in the scripts depend whether or not <filename>rc.d</filename> is being used.  Prior
+      to &os;&nbsp;5.1 the old configuration style is used and in
+      almost all cases a new style script would do just fine.</para>
+
+    <para>While every script must meet some minimal requirements, most
+      of the time these requirements are &os; version
+      agnostic.  Each script must have a <filename>.sh</filename>
+      extension appended to the end and every script must be
+      executable by the system.  The latter may be achieved by using
+      the <command>chmod</command> command and setting the unique permissions
+      of <literal>755</literal>.  There should also be, at minimal,
+      an option to <literal>start</literal> the application and an
+      option to <literal>stop</literal> the application.</para>
+
+    <para>The simplest start up script would probably look a little
+      bit like this one:</para>
+
+    <programlisting>#!/bin/sh
+echo -n ' utility'
+
+case "$1" in
+start)
+        /usr/local/bin/utility
+        ;;
+stop)
+        kill -9 `cat /var/run/utility.pid`
+        ;;
+*)
+        echo "Usage: `basename $0` {start|stop}" &gt;&2
+        exit 64
+        ;;
+esac
+
+exit 0</programlisting>
+
+    <para>This script provides for a <literal>stop</literal> and
+      <literal>start</literal> option for
+      the application hereto referred simply as
+      <literal>utility</literal>.</para>
+
+    <para>Could be started manually with:</para>
+
+    <screen>&prompt.root; <userinput><filename>/usr/local/etc/rc.d/utility.sh</filename> start</userinput></screen>
+
+    <para>While not all third party software requires the line in
+      <filename>rc.conf</filename>, almost every day a new port will
+      be modified to accept this configuration.  Check the final output
+      of the installation for more information on a specific
+      application.  Some third party software will provide start up
+      scripts which permit the application to be used with
+      <filename>rc.d</filename>; although, this will be discussed in the next section.</para>
+
+    <sect2>
+      <title>Extended Application Configuration</title>
+
+      <para>Now that &os; includes <filename>rc.d</filename>, configuration
+	of application startup has become easier, and more
+	featureful.  Using the key words discussed in the
+	<link linkend="configtuning-rcd">rc.d</link> section,
+	applications may now be set to start after certain other
+	services for example <acronym>DNS</acronym>; may permit extra
+	flags to be passed through <filename>rc.conf</filename> in
+	place of hard coded flags in the start up script, etc.  A
+	basic script may look similar to the following:</para>
+
+      <programlisting>#!/bin/sh
+#
+# PROVIDE: utility
+# REQUIRE: DAEMON
+# KEYWORD: shutdown
+
+#
+# DO NOT CHANGE THESE DEFAULT VALUES HERE
+# SET THEM IN THE /etc/rc.conf FILE
+#
+utility_enable=${utility_enable-"NO"}
+utility_flags=${utility_flags-""}
+utility_pidfile=${utility_pidfile-"/var/run/utility.pid"}
+
+. /etc/rc.subr
+
+name="utility"
+rcvar=`set_rcvar`
+command="/usr/local/sbin/utility"
+
+load_rc_config $name
+
+pidfile="${utility_pidfile}"
+
+start_cmd="echo \"Starting ${name}.\"; /usr/bin/nice -5 ${command} ${utility_flags} ${command_args}"
+
+run_rc_command "$1"</programlisting>
+
+      <para>This script will ensure that the provided
+	<application>utility</application> will be started after the
+	<literal>daemon</literal> service.  It also provides a method
+	for setting and tracking the <acronym>PID</acronym>, or process
+	<acronym>ID</acronym> file.</para>
+
+      <para>This application could then have the following line placed
+	in <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>utility_enable="YES"</programlisting>
+
+      <para>This new method also allows for easier manipulation of the
+	command line arguments, inclusion of the default functions
+	provided in <filename>/etc/rc.subr</filename>, compatibility
+	with the &man.rcorder.8; utility and provides for easier
+	configuration via the <filename>rc.conf</filename> file.</para>
+    </sect2>
+
+    <sect2>
+      <title>Using Services to Start Services</title>
+
+      <para>Other services, such as <acronym>POP</acronym>3 server
+	daemons, <acronym>IMAP</acronym>, etc. could be started using
+	the &man.inetd.8;.  This involves installing the service
+	utility from the Ports Collection with a configuration line
+	appended to the <filename>/etc/inetd.conf</filename> file,
+	or uncommenting one of the current configuration lines.  Working
+	with <application>inetd</application> and its configuration is
+	described in depth in the
+	<link linkend="network-inetd">inetd</link> section.</para>
+
+      <para>In some cases, it may be more plausible to use the
+	&man.cron.8; daemon to start system services.  This approach
+	has a number of advantages because <command>cron</command> runs
+	these processes as the <filename>crontab</filename>'s file
+	owner.  This allows regular users to start and maintain some
+	applications.</para>
+
+      <para>The <command>cron</command> utility provides a unique
+	feature, <literal>@reboot</literal>, which may be used in place
+	of the time specification.  This will cause the job to be run
+	when &man.cron.8; is started, normally during system
+	initialization.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="configtuning-cron">
+    <sect1info>
+      <authorgroup>
+        <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Contributed by </contrib>
+	<!-- 20 May 2003 -->
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Configuring the <command>cron</command> Utility</title>
+
+    <indexterm><primary>cron</primary>
+      <secondary>configuration</secondary></indexterm>
+
+    <para>One of the most useful utilities in &os; is &man.cron.8;.  The
+      <command>cron</command> utility runs in the background and constantly
+      checks the <filename>/etc/crontab</filename> file.  The <command>cron</command>
+      utility also checks the <filename>/var/cron/tabs</filename> directory, in
+      search of new <filename>crontab</filename> files.  These
+      <filename>crontab</filename> files store information about specific
+      functions which <command>cron</command> is supposed to perform at
+      certain times.</para>
+
+    <para>The <command>cron</command> utility uses two different
+      types of configuration files, the system crontab and user crontabs. The
+      only difference between these two formats is the sixth field.  In the
+      system crontab, the sixth field is the name of a user for the command
+      to run as. This gives the system crontab the ability to run commands
+      as any user. In a user crontab, the sixth field is the command to run,
+      and all commands run as the user who created the crontab; this is an
+      important security feature.</para>
+
+    <note>
+      <para>User crontabs allow individual users to schedule tasks without the 
+        need for <username>root</username> privileges. Commands in a user's crontab run with the 
+        permissions of the user who owns the crontab.</para>
+
+      <para>The <username>root</username> user can have a user crontab just like
+        any other user. This one is different from
+        <filename>/etc/crontab</filename> (the system crontab). Because of the
+        system crontab, there is usually no need to create a user crontab
+        for <username>root</username>.</para>
+    </note>
+
+    <para>Let us take a look at the <filename>/etc/crontab</filename> file
+      (the system crontab):</para>
+
+
+    <programlisting># /etc/crontab - root's crontab for &os;
+#
+# &dollar;&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp &dollar;
+# <co id="co-comments">
+#
+SHELL=/bin/sh
+PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env">
+HOME=/var/log
+#
+#
+#minute	hour	mday	month	wday	who	command <co id="co-field-descr">
+#
+#
+*/5	*	*	*	*	root	/usr/libexec/atrun <co id="co-main">
+</programlisting>
+
+    <calloutlist>
+      <callout arearefs="co-comments">
+	<para>Like most &os; configuration files, the <literal>#</literal>
+	  character represents a comment.  A comment can be placed in
+	  the file as a reminder of what and why a desired action is performed.
+	  Comments cannot be on the same line as a command or else they will
+	  be interpreted as part of the command; they must be on a new line.
+	  Blank lines are ignored.</para>
+      </callout>
+
+      <callout arearefs="co-env">
+	<para>First, the environment must be defined.  The equals
+	  (<literal>=</literal>) character is used to define any environment
+	  settings, as with this example where it is used for the <envar>SHELL</envar>,
+	  <envar>PATH</envar>, and <envar>HOME</envar> options.  If the shell line is
+	  omitted, <command>cron</command> will use the default, which is
+	  <command>sh</command>.  If the <envar>PATH</envar> variable is
+	  omitted, no default will be used and file locations will need to
+	  be absolute.  If <envar>HOME</envar> is omitted, <command>cron</command>
+	  will use the invoking users home directory.</para>
+      </callout>
+
+      <callout arearefs="co-field-descr">
+	<para>This line defines a total of seven fields.  Listed here are the
+	  values <literal>minute</literal>, <literal>hour</literal>,
+	  <literal>mday</literal>, <literal>month</literal>, <literal>wday</literal>,
+	  <literal>who</literal>, and <literal>command</literal>.  These
+	  are almost all self explanatory.  <literal>minute</literal> is the time in minutes the
+	  command will be run.  <literal>hour</literal> is similar to the <literal>minute</literal> option, just in
+	  hours.  <literal>mday</literal> stands for day of the month.  <literal>month</literal> is similar to <literal>hour</literal>
+	  and <literal>minute</literal>, as it designates the month.  The <literal>wday</literal> option stands for
+	  day of the week.  All these fields must be numeric values, and follow
+	  the twenty-four hour clock.  The <literal>who</literal> field is special,
+	  and only exists in the <filename>/etc/crontab</filename> file.
+	  This field specifies which user the command should be run as.
+	  When a user installs his or her <filename>crontab</filename> file, they
+	  will not have this option. Finally, the <literal>command</literal> option is listed.
+	  This is the last field, so naturally it should designate the command
+	  to be executed.</para>
+      </callout>
+
+      <callout arearefs="co-main">
+	<para>This last line will define the values discussed above.  Notice here
+	  we have a <literal>*/5</literal> listing, followed by several more
+	  <literal>*</literal> characters.  These <literal>*</literal> characters
+	  mean <quote>first-last</quote>, and can be interpreted as
+	  <emphasis>every</emphasis> time.  So, judging by this line,
+	  it is apparent that the <command>atrun</command> command is to be invoked by
+	  <username>root</username> every five minutes regardless of what
+	  day or month it is.  For more information on the <command>atrun</command> command,
+	  see the &man.atrun.8; manual page.</para>
+
+	<para>Commands can have any number of flags passed to them; however,
+	  commands which extend to multiple lines need to be broken with the backslash
+	  <quote>\</quote> continuation character.</para>
+      </callout>
+    </calloutlist>
+
+    <para>This is the basic set up for every
+      <filename>crontab</filename> file, although there is one thing
+      different about this one.  Field number six, where we specified
+      the username, only exists in the system
+      <filename>/etc/crontab</filename> file.  This field should be
+      omitted for individual user <filename>crontab</filename>
+      files.</para>
+
+
+    <sect2 id="configtuning-installcrontab">
+      <title>Installing a Crontab</title>
+
+      <important>
+      <para>You must not use the procedure described here to
+        edit/install the system crontab. Simply use your favorite
+        editor: the <command>cron</command> utility will notice that the file
+        has changed and immediately begin using the updated version. 
+        See
+        <ulink url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS">
+        this FAQ entry </ulink> for more information.</para>
+      </important>
+
+      <para>To install a freshly written user
+	<filename>crontab</filename>, first use your favorite editor to create
+	a file in the proper format, and then use the
+	<command>crontab</command> utility.  The most common usage
+	is:</para>
+
+      <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen>
+      
+      <para>In this example, <filename>crontab-file</filename> is the filename
+    of a <filename>crontab</filename> that was previously created.</para>
+
+      <para>There is also an option to list installed
+	<filename>crontab</filename> files: just pass the
+	<option>-l</option> option to <command>crontab</command> and look
+	over the output.</para>
+
+      <para>For users who wish to begin their own crontab file from scratch,
+	without the use of a template, the <command>crontab -e</command>
+	option is available.  This will invoke the selected editor
+	with an empty file.  When the file is saved, it will be
+	automatically installed by the <command>crontab</command> command.
+      </para>
+      
+      <para>If you later want to remove your user <filename>crontab</filename>
+	completely, use <command>crontab</command> with the <option>-r</option>
+	option.
+      </para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="configtuning-rcd">
+    <sect1info>
+      <authorgroup>
+        <author>
+	 <firstname>Tom</firstname>
+	 <surname>Rhodes</surname>
+	 <contrib>Contributed by </contrib>
+	 <!-- 16 May 2003 -->
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Using rc under &os;</title>
+
+    <para>In 2002 &os; integrated the NetBSD
+      <filename>rc.d</filename> system for system initialization.
+      Users should notice the files listed in the
+      <filename>/etc/rc.d</filename> directory.  Many of these files
+      are for basic services which can be controlled with the
+      <option>start</option>, <option>stop</option>,
+      and <option>restart</option> options.
+      For instance, &man.sshd.8; can be restarted with the following
+      command:</para>
+
+    <screen>&prompt.root; <userinput>/etc/rc.d/sshd restart</userinput></screen>
+
+    <para>This procedure is similar for other services.  Of course,
+      services are usually started automatically at boot time as specified in
+      &man.rc.conf.5;.  For example, enabling the Network Address
+      Translation daemon at startup is as simple as adding the
+      following line to <filename>/etc/rc.conf</filename>:</para>
+
+    <programlisting>natd_enable="YES"</programlisting>
+
+    <para>If a <option>natd_enable="NO"</option> line is already
+       present, then simply change the <option>NO</option> to
+       <option>YES</option>.  The rc scripts will automatically load
+       any other dependent services during the next reboot, as
+       described below.</para>
+
+    <para>Since the <filename>rc.d</filename> system is primarily
+      intended to start/stop services at system startup/shutdown time,
+      the standard <option>start</option>,
+      <option>stop</option> and <option>restart</option> options will only
+      perform their action if the appropriate
+      <filename>/etc/rc.conf</filename> variables are set.  For
+      instance the above <command>sshd restart</command> command will
+      only work if <varname>sshd_enable</varname> is set to
+      <option>YES</option> in <filename>/etc/rc.conf</filename>.  To
+      <option>start</option>, <option>stop</option> or
+      <option>restart</option> a service regardless of the settings in
+      <filename>/etc/rc.conf</filename>, the commands should be
+      prefixed with <quote>force</quote>.  For instance to restart
+      <command>sshd</command> regardless of the current
+      <filename>/etc/rc.conf</filename> setting, execute the following
+      command:</para>
+
+    <screen>&prompt.root; <userinput>/etc/rc.d/sshd forcerestart</userinput></screen>
+
+    <para>It is easy to check if a service is enabled in
+      <filename>/etc/rc.conf</filename> by running the appropriate
+      <filename>rc.d</filename> script with the option
+      <option>rcvar</option>.  Thus, an administrator can check that
+      <command>sshd</command> is in fact enabled in
+      <filename>/etc/rc.conf</filename> by running:</para>
+
+    <screen>&prompt.root; <userinput>/etc/rc.d/sshd rcvar</userinput>
+# sshd
+$sshd_enable=YES</screen>
+
+    <note>
+      <para>The second line (<literal># sshd</literal>) is the output
+        from the <command>sshd</command> command, not a <username>root</username>
+        console.</para>
+    </note>
+
+    <para>To determine if a service is running, a
+      <option>status</option> option is available.  For instance to
+      verify that <command>sshd</command> is actually started:</para>
+
+    <screen>&prompt.root; <userinput>/etc/rc.d/sshd status</userinput>
+sshd is running as pid 433.</screen>
+
+    <para>In some cases it is also possible to <option>reload</option> a service.
+      This will attempt to send a signal to an individual service, forcing the
+      service to reload its configuration files.  In most cases this
+      means sending the service a <literal>SIGHUP</literal>
+      signal.  Support for this feature is not included for every service.</para>
+
+    <para>The <filename>rc.d</filename> system is not only used for network services, it also
+      contributes to most of the system initialization.  For
+      instance, consider the <filename>bgfsck</filename> file.  When
+      this script is executed, it will print out the following
+      message:</para>
+
+    <screen>Starting background file system checks in 60 seconds.</screen>
+
+    <para>Therefore this file is used for background file system
+      checks, which are done only during system initialization.</para>
+
+    <para>Many system services depend on other services to function
+      properly.  For example, NIS and other RPC-based services may
+      fail to start until after the <command>rpcbind</command>
+      (portmapper) service has started.  To resolve this issue,
+      information about dependencies and other meta-data is included
+      in the comments at the top of each startup script.  The
+      &man.rcorder.8; program is then used to parse these comments
+      during system initialization to determine the order in which
+      system services should be invoked to satisfy the dependencies.
+      The following words may be included at the top of each startup
+      file:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>PROVIDE</literal>: Specifies the services this file provides.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>REQUIRE</literal>: Lists services which are required for this
+	  service.  This file will run <emphasis>after</emphasis>
+	  the specified services.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>BEFORE</literal>: Lists services which depend on this service.
+	  This file will run <emphasis>before</emphasis>
+	  the specified services.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>By using this method, an administrator can easily control system
+      services without the hassle of <quote>runlevels</quote> like
+      some other &unix; operating systems.</para>
+
+    <para>Additional information about the
+      <filename>rc.d</filename> system can be found in the &man.rc.8;
+      and &man.rc.subr.8; manual pages.</para>
+  </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 cards</primary>
+      <secondary>configuration</secondary>
+    </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 &os; administrator.</para>
+
+    <sect2>
+      <title>Locating the Correct Driver</title>
+
+      <indexterm>
+	<primary>network cards</primary>
+	<secondary>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.
+	&os; 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.
+	<filename>/usr/src/sys/conf/NOTES</filename> and
+	<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename> will give you
+	the list of network interface 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>If the driver for your NIC is not present in
+	<filename>GENERIC</filename>, you will need to load the proper
+	driver to use your NIC.  This may be accomplished in one of
+	two ways:</para>
+
+      <itemizedlist>
+        <listitem>
+	  <para>The easiest way is to simply load a kernel module for
+	    your network card with &man.kldload.8;, or automatically at boot time by adding the appropriate line to the file <filename>/boot/loader.conf</filename>.  Not all NIC
+	    drivers are available as modules; notable examples of
+	    devices for which modules do not exist are ISA cards.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Alternatively, you may statically compile the support
+	    for your card into your kernel.  Check
+	    <filename>/usr/src/sys/conf/NOTES</filename>,
+	    <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</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>
+	</listitem>
+      </itemizedlist>
+
+      <sect3 id="config-network-ndis">
+	<title>Using &windows; NDIS Drivers</title>
+
+	<indexterm><primary>NDIS</primary></indexterm>
+	<indexterm><primary>NDISulator</primary></indexterm>
+	<indexterm><primary>&windows; drivers</primary></indexterm>
+	<indexterm><primary>Microsoft Windows</primary></indexterm>
+	<indexterm><primary>Microsoft Windows</primary>
+	    <secondary>device drivers</secondary></indexterm>
+	<indexterm><primary>KLD (kernel loadable
+	  object)</primary></indexterm>
+<!-- We should probably omit the expanded name, and add a <see> entry
+for it.  Whatever is done must also be done to the same indexterm in
+linuxemu/chapter.sgml -->
+
+	<para>Unfortunately, there are still many vendors that do not
+	  provide schematics for their drivers to the open source
+	  community because they regard such information as trade
+	  secrets.  Consequently, the developers of &os; and other
+	  operating systems are left two choices: develop the drivers
+	  by a long and pain-staking process of reverse engineering or
+	  using the existing driver binaries available for the
+	  &microsoft.windows; platforms.  Most developers, including
+	  those involved with &os;, have taken the latter
+	  approach.</para>
+
+	<para>Thanks to the contributions of Bill Paul (wpaul), as of
+	  &os;&nbsp;5.3-RELEASE there is <quote>native</quote> support
+	  for the Network Driver Interface Specification (NDIS).  The
+	  &os; NDISulator (otherwise known as Project Evil) takes a
+	  &windows; driver binary and basically tricks it into
+	  thinking it is running on &windows;.  Because the
+	  &man.ndis.4; driver is using a &windows; binary, it is only
+	  usable on &i386; and amd64 systems.</para>
+
+	<note>
+	  <para>The &man.ndis.4; driver is designed to support mainly
+	    PCI, CardBus and PCMCIA devices, USB devices are not yet
+	    supported.</para>
+	</note>
+
+	<para>In order to use the NDISulator, you need three
+	  things:</para>
+
+	<orderedlist>
+	 <listitem>
+	  <para>Kernel sources</para>
+	 </listitem>
+	 <listitem>
+	  <para>&windowsxp; driver binary
+	    (<filename>.SYS</filename> extension)</para>
+	 </listitem>
+	 <listitem>
+	  <para>&windowsxp; driver configuration file
+	    (<filename>.INF</filename> extension)</para>
+	 </listitem>
+	</orderedlist>
+
+	<para>Locate the files for your specific card.  Generally,
+	  they can be found on the included CDs or at the vendors'
+	  websites.  In the following examples, we will use
+	  <filename>W32DRIVER.SYS</filename> and
+	  <filename>W32DRIVER.INF</filename>.</para>
+
+	<note>
+	  <para>You can not use a &windows;/i386 driver with
+	    &os;/amd64, you must get a &windows;/amd64 driver to make it
+	    work properly.</para>
+	</note>
+
+	<para>The next step is to compile the driver binary into a
+	  loadable kernel module.  To accomplish this, as
+	  <username>root</username>, use &man.ndisgen.8;:</para>
+
+	<screen>&prompt.root; <userinput>ndisgen <replaceable>/path/to/W32DRIVER.INF</replaceable> <replaceable>/path/to/W32DRIVER.SYS</replaceable></userinput></screen>
+
+	<para>The &man.ndisgen.8; utility is interactive and will
+	  prompt for any extra information it requires; it will
+	  produce a kernel module in the current directory which can
+	  be loaded as follows:</para>
+
+	<screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER.ko</replaceable></userinput></screen>
+
+	<para>In addition to the generated kernel module, you must
+	  load the <filename>ndis.ko</filename> and
+	  <filename>if_ndis.ko</filename> modules.  This should be
+	  automatically done when you load any module that depends on
+	  &man.ndis.4;.  If you want to load them manually, use the
+	  following commands:</para>
+
+	<screen>&prompt.root; <userinput>kldload ndis</userinput>
+&prompt.root; <userinput>kldload if_ndis</userinput></screen>
+
+	<para>The first command loads the NDIS miniport driver
+	  wrapper, the second loads the actual network
+	  interface.</para>
+
+	<para>Now, check &man.dmesg.8; to see if there were any errors
+	  loading.  If all went well, you should get output resembling
+	  the following:</para>
+
+	<screen>ndis0: &lt;Wireless-G PCI Adapter&gt; mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
+ndis0: NDIS API version: 5.0
+ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5
+ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps
+ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen>
+
+	<para>From here you can treat the
+	  <devicename>ndis0</devicename> device like any other network
+	  interface (e.g., <devicename>dc0</devicename>).</para>
+
+	<para>You can configure the system to load the NDIS modules at
+	  boot time in the same way as with any other module.  First,
+	  copy the generated module,
+	  <filename>W32DRIVER.ko</filename>, to the <filename
+	  class="directory">/boot/modules</filename> directory.  Then,
+	  add the following line to
+	  <filename>/boot/loader.conf</filename>:</para>
+
+	<programlisting>W32DRIVER_load="YES"</programlisting>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Configuring the Network Card</title>
+
+      <indexterm>
+	<primary>network cards</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 &os; 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>&os; 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 cards</primary>
+	  <secondary>testing</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 test the local 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 cards</primary>
+	<secondary>troubleshooting</secondary>
+      </indexterm>
+
+      <para>Troubleshooting hardware and software configurations is always
+	a pain, and a pain which can be alleviated by checking the simple
+	things first.  Is your network cable plugged in?  Have you properly
+	configured the network services?  Did you configure the firewall
+	correctly?  Is the card you are using supported by &os;?  Always
+	check the hardware notes before sending off a bug report.  Update
+	your version of &os; to the latest STABLE version.  Check the
+	mailing list archives, or perhaps search the Internet.</para>
+
+      <para>If the card works, yet performance is poor, it would be
+	worthwhile to read over the &man.tuning.7; manual page.  You
+	can also check the network configuration as incorrect network
+	settings can cause slow connections.</para>
+
+      <para>Some users experience one or two <errorname>device
+	timeout</errorname> messages, which is normal for some cards.  If they
+	continue, or are bothersome, you may wish to be sure the
+	device is not conflicting with another device.  Double check
+	the cable connections.  Perhaps you may just need to get
+	another card.</para>
+
+      <para>At times, users see a few <errorname>watchdog timeout</errorname>
+	errors.  The first thing to do here is to check your network
+	cable. Many cards require a PCI slot which supports Bus
+	Mastering. On some old motherboards, only one PCI slot allows
+	it (usually slot 0). Check the network card and the
+	motherboard documentation to determine if that may be the
+	problem.</para>
+
+      <para><errorname>No route to host</errorname> messages occur if the
+	system is unable to route a packet to the destination host.
+	This can happen if no default route is specified, or if a
+	cable is unplugged.  Check the output of <command>netstat
+	-rn</command> and make sure there is a valid route to the host
+	you are trying to reach.  If there is not, read on to <xref
+	linkend="advanced-networking">.</para>
+
+      <para><errorname>ping: sendto: Permission denied</errorname> error
+	messages are often caused by a misconfigured firewall.  If
+	<command>ipfw</command> is enabled in the kernel but no rules
+	have been defined, then the default policy is to deny all
+	traffic, even ping requests!  Read on to <xref
+	linkend="firewalls"> for more information.</para>
+
+      <para>Sometimes performance of the card is poor, or below average.
+	In these cases it is best to set the media selection mode
+	from <literal>autoselect</literal> to the correct media selection.
+	While this usually works for most hardware, it may not resolve
+	this issue for everyone.  Again, check all the network settings,
+	and read over the &man.tuning.7; manual page.</para>
+
+      </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 &os; 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 <literal>alias0</literal> and proceed
+      upwards in order, (for example, <literal>_alias1</literal>, <literal>_alias2</literal>, 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 <literal>1</literal>s (expressed as either
+      <hostid role="netmask">255.255.255.255</hostid> or <hostid role="netmask">0xffffffff</hostid>).
+      </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>.  As noted above, only the
+      first address in a given network range (in this case,
+      <hostid role="ipaddr">10.0.1.1</hostid> and
+      <hostid role="ipaddr">202.0.75.17</hostid>) should have a real
+      netmask; all the rest (<hostid role="ipaddr">10.1.1.2</hostid>
+      through <hostid role="ipaddr">10.1.1.5</hostid> and
+      <hostid role="ipaddr">202.0.75.18</hostid> through
+      <hostid role="ipaddr">202.0.75.20</hostid>) must be configured with a
+      netmask of <hostid role="netmask">255.255.255.255</hostid>.</para>
+
+    <para>The following <filename>/etc/rc.conf</filename> 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" pgwide="1">
+	<tgroup cols="2">
+	  <colspec colwidth="1*">
+	  <colspec colwidth="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 &os;'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" pgwide="1">
+	  <tgroup cols="2">
+	  <colspec colwidth="1*">
+	  <colspec colwidth="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;&os;&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;&os;&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;&os;&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 id="configtuning-sysctlconf">
+      <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 &os;:</para>
+
+      <programlisting>kern.logsigexit=0       # Do not log fatal signal exits (e.g. sig 11)
+compat.linux.osname=&os;
+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</primary>
+      <secondary>with sysctl</secondary>
+    </indexterm>
+
+    <para>&man.sysctl.8; is an interface that allows you to make changes
+      to a running &os; 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 -&gt; 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>
+
+    <para>If you want to set automatically some variables each time
+      the machine boots, add them to the
+      <filename>/etc/sysctl.conf</filename> file.  For more information
+      see the &man.sysctl.conf.5; manual page and the
+      <xref linkend="configtuning-sysctlconf">.</para>
+
+  <sect2 id="sysctl-readonly">
+    <sect2info>
+      <authorgroup>
+        <author>
+	 <firstname>Tom</firstname>
+	 <surname>Rhodes</surname>
+	 <contrib>Contributed by </contrib>
+	 <!-- 31 January 2003 -->
+        </author>
+      </authorgroup>
+    </sect2info>
+    <title>&man.sysctl.8; Read-only</title>
+
+    <para>In some cases it may be desirable to modify read-only &man.sysctl.8;
+      values.  While this is sometimes unavoidable, it can only be done
+      on (re)boot.</para>
+
+    <para>For instance on some laptop models the &man.cardbus.4; device will
+      not probe memory ranges, and fail with errors which look similar to:</para>
+
+    <screen>cbb0: Could not map register memory
+device_probe_and_attach: cbb0 attach returned 12</screen>
+
+    <para>Cases like the one above usually require the modification of some
+      default &man.sysctl.8; settings which are set read only.  To overcome
+      these situations a user can put &man.sysctl.8; <quote>OIDs</quote>
+      in their local <filename>/boot/loader.conf</filename>.  Default
+      settings are located in the <filename>/boot/defaults/loader.conf</filename>
+      file.</para>
+
+    <para>Fixing the problem mentioned above would require a user to set
+      <option>hw.pci.allow_unsupported_io_range=1</option> in the aforementioned
+      file.  Now &man.cardbus.4; will work properly.</para>
+
+    </sect2>
+  </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.
+	  With this variable turned off (to 0), the buffer
+	  cache will only cache a fixed number of directories even if
+	  you have a huge amount of memory.  When turned on (to 1), 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 keeping 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.  Keeping this option on will generally not reduce
+	  performance even with the wasted memory but you should
+	  experiment to find out.</para>
+      </sect3>
+
+     <sect3>
+ 	<title><varname>vfs.write_behind</varname></title>
+
+ 	<indexterm>
+ 	  <primary><varname>vfs.write_behind</varname></primary>
+ 	</indexterm>
+
+ 	<para>The <varname>vfs.write_behind</varname> sysctl variable
+ 	  defaults to <literal>1</literal> (on).  This tells the file system
+ 	  to issue media writes as full clusters are collected, which
+ 	  typically occurs when writing large sequential files.  The idea
+ 	  is to avoid saturating the buffer cache with dirty buffers when
+ 	  it would not benefit I/O performance.  However, this may stall
+ 	  processes and under certain circumstances you may wish to turn it
+ 	  off.</para>
+       </sect3>
+
+       <sect3>
+ 	<title><varname>vfs.hirunningspace</varname></title>
+
+ 	<indexterm>
+ 	  <primary><varname>vfs.hirunningspace</varname></primary>
+ 	</indexterm>
+
+ 	<para>The <varname>vfs.hirunningspace</varname> sysctl variable
+ 	  determines how much outstanding write I/O may be queued to disk
+ 	  controllers system-wide at any given instance.  The default is
+ 	  usually sufficient but on machines with lots of disks you may
+ 	  want to bump it up to four or five <emphasis>megabytes</emphasis>.
+ 	  Note that setting too high a value (exceeding the buffer cache's
+ 	  write threshold) can lead to extremely bad clustering
+ 	  performance.  Do not set this value arbitrarily high!  Higher
+ 	  write values may add latency to reads occurring at the same time.
+ 	</para>
+
+ 	<para>There are various other buffer-cache and VM page cache
+ 	  related sysctls.  We do not recommend modifying these values,
+	  the VM system does an extremely good job of
+ 	  automatically tuning itself.</para>
+       </sect3>
+
+       <sect3>
+ 	<title><varname>vm.swap_idle_enabled</varname></title>
+
+ 	<indexterm>
+ 	  <primary><varname>vm.swap_idle_enabled</varname></primary>
+ 	</indexterm>
+
+ 	<para>The <varname>vm.swap_idle_enabled</varname> sysctl variable
+ 	  is useful in large multi-user systems where you have lots of
+ 	  users entering and leaving the system and lots of idle processes.
+ 	  Such systems tend to generate a great deal of continuous pressure
+ 	  on free memory reserves.  Turning this feature on and tweaking
+ 	  the swapout hysteresis (in idle seconds) via
+ 	  <varname>vm.swap_idle_threshold1</varname> and
+ 	  <varname>vm.swap_idle_threshold2</varname> allows you to depress
+ 	  the priority of memory pages associated with idle processes more
+ 	  quickly then the normal pageout algorithm.  This gives a helping
+ 	  hand to the pageout daemon.  Do not turn this option on unless
+ 	  you need it, because the tradeoff you are making is essentially
+ 	  pre-page memory sooner rather than later; thus eating more swap
+ 	  and disk bandwidth.  In a small system this option will have a
+ 	  determinable effect but in a large system that is already doing
+ 	  moderate paging this option allows the VM system to stage whole
+ 	  processes into and out of memory easily.</para>
+       </sect3>
+
+      <sect3>
+	<title><varname>hw.ata.wc</varname></title>
+
+	<indexterm>
+	  <primary><varname>hw.ata.wc</varname></primary>
+	</indexterm>
+
+	<para>&os;&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.
+	  &os;'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>
+
+      <sect3>
+	<title><literal>SCSI_DELAY</literal>
+	(<varname>kern.cam.scsi_delay</varname>)</title>
+
+	<indexterm>
+	  <primary><varname>kern.cam.scsi_delay</varname></primary>
+	</indexterm>
+
+	<indexterm>
+	  <primary>kernel options</primary>
+	  <secondary><literal>SCSI_DELAY</literal></secondary>
+	</indexterm>
+
+	<para>The <literal>SCSI_DELAY</literal> kernel config may be used to
+	  reduce system boot times.  The defaults are fairly high and can be
+	  responsible for <literal>15</literal> seconds of delay in the
+	  boot process.  Reducing it to <literal>5</literal> seconds usually
+	  works (especially with modern drives).  Newer versions of &os;
+	  (5.0 and higher) should use the <varname>kern.cam.scsi_delay</varname>
+	  boot time tunable.  The tunable, and kernel config option accept
+	  values in terms of <emphasis>milliseconds</emphasis> and
+	  <emphasis>not</emphasis> <emphasis>seconds</emphasis>.</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>
+
+      <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 file systems.  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</primary>
+	  <secondary>details</secondary>
+	</indexterm>
+
+	<para>There are two traditional approaches to writing a file
+	  systems 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 file systems 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 file systems where this is required, to free
+	   resources that may be unused.  (File systems 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</primary>
+      <secondary>kernel limits</secondary>
+    </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>In older FreeBSD releases, <varname>kern.maxfile</varname>'s default
+          value is derived from 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 at once, the resources needed may be similar to a
+          high-scale web server.</para>
+
+        <para>As of FreeBSD 4.5, <varname>kern.maxusers</varname> is
+          automatically sized at boot based on the amount of memory available
+          in the system, and may be determined at run-time by inspecting the
+          value of the read-only <varname>kern.maxusers</varname> sysctl.
+          Some sites will require larger or smaller values of
+          <varname>kern.maxusers</varname> and may set it as a loader tunable;
+          values of 64, 128, and 256 are not uncommon.  We do not recommend
+          going above 256 unless you need a huge number of file descriptors;
+          many of the tunable values set to their defaults by
+          <varname>kern.maxusers</varname> may be individually overridden at
+          boot-time or run-time in <filename>/boot/loader.conf</filename> (see
+          the &man.loader.conf.5; man page or the
+          <filename>/boot/defaults/loader.conf</filename> file for some hints)
+          or as described elsewhere in this document.  Systems older than
+          FreeBSD&nbsp;4.4 must set this value via the kernel &man.config.8;
+          option <option>maxusers</option> instead.</para>
+
+	<para>In older releases, the system will auto-tune
+	  <literal>maxusers</literal> for you if you explicitly set it to
+	  <literal>0</literal><footnote>
+	    <para>The auto-tuning algorithm sets
+	      <literal>maxusers</literal> equal to the amount of memory in the
+	      system, with a minimum of 32, and a maximum of 384.</para>
+	  </footnote>.  When setting this option, you will want to set
+	  <literal>maxusers</literal> to at least 4, especially if you are
+	  using the X Window System or compiling software.  The reason is that
+	  the most important table set by <literal>maxusers</literal> is the
+	  maximum number of processes,  which is set to <literal>20 + 16 *
+	  maxusers</literal>, so if you set <literal>maxusers</literal> to 1,
+	  then you can only have 36 simultaneous processes, including the 18
+	  or so that the system starts up at boot time and the 15 or so you
+	  will probably create when you start the X Window System.  Even a
+	  simple task like reading a manual page will start up nine
+	  processes to filter, decompress, and view it.  Setting
+	  <literal>maxusers</literal> to 64 will allow you to have up to 1044
+	  simultaneous processes, which should be enough for nearly all uses.
+	  If, however, you see the dreaded <errortype>proc table
+	  full</errortype> error when trying to start another program, or are
+	  running a server with a large number of simultaneous users (like
+	  <hostid role="fqdn">ftp.FreeBSD.org</hostid>), you can always
+	  increase the number and rebuild.</para>
+
+	<note>
+	  <para><literal>maxusers</literal> does <emphasis>not</emphasis>
+	    limit the number of users which can log into your machine.  It
+	    simply sets various table sizes to reasonable values considering
+	    the maximum number of users you will likely have on your system
+	    and how many processes each of them will be running.  One keyword
+	    which <emphasis>does</emphasis> limit the number of simultaneous
+	    remote logins and X terminal windows is <link
+	    linkend="kernelconfig-ptys"><literal>pseudo-device pty
+	    16</literal></link>.  With &os;&nbsp;5.X, you do not have to
+	    worry about this number since the &man.pty.4; driver is
+	    <quote>auto-cloning</quote>; you simply use the line
+	    <literal>device pty</literal> in your configuration file.</para>
+	</note>
+
+      </sect3>
+
+      <sect3>
+	<title><varname>kern.ipc.somaxconn</varname></title>
+
+	<indexterm>
+	  <primary><varname>kern.ipc.somaxconn</varname></primary>
+	</indexterm>
+
+	<para>The <varname>kern.ipc.somaxconn</varname> sysctl variable
+	  limits the size of the listen queue for accepting new TCP
+	  connections.  The default value of <literal>128</literal> is
+	  typically too low for robust handling of new connections in a
+	  heavily loaded web server environment.  For such environments, it
+	  is recommended to increase this value to <literal>1024</literal> or
+	  higher.  The service daemon may itself limit the listen queue size
+	  (e.g. &man.sendmail.8;, or <application>Apache</application>) but
+	  will often have a directive in its configuration file to adjust
+	  the queue size.  Large listen queues also do a better job of
+	  avoiding Denial of Service (<abbrev>DoS</abbrev>) attacks.</para>
+      </sect3>
+
+    </sect2>
+    <sect2 id="nmbclusters">
+      <title>Network Limits</title>
+
+      <para>The <literal>NMBCLUSTERS</literal> 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 &os;'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.  We recommend
+	values between 4096 and 32768 for machines with greater amounts
+	of memory.  Under no circumstances should you specify an
+	arbitrarily high value for this parameter as it could lead to a
+	boot time crash.  The <option>-m</option> option to
+	&man.netstat.1; may be used to observe network cluster
+	use.</para>
+
+      <para><varname>kern.ipc.nmbclusters</varname> loader tunable should
+        be used to tune this at boot time.  Only older versions of &os;
+        will require you to use the <literal>NMBCLUSTERS</literal> kernel
+        &man.config.8; option.</para>
+
+      <para>For busy servers that make extensive use of the
+	&man.sendfile.2; system call, it may be necessary to increase
+	the number of &man.sendfile.2; buffers via the
+	<literal>NSFBUFS</literal> kernel configuration option or by
+	setting its value in <filename>/boot/loader.conf</filename>
+	(see &man.loader.8; for details).  A common indicator that
+	this parameter needs to be adjusted is when processes are seen
+	in the <literal>sfbufa</literal> state.  The sysctl
+	variable <varname>kern.ipc.nsfbufs</varname> is a read-only
+	glimpse at the kernel configured variable.  This parameter
+	nominally scales with <varname>kern.maxusers</varname>,
+	however it may be necessary to tune accordingly.</para>
+
+      <important>
+	<para>Even though a socket has been marked as non-blocking,
+	  calling &man.sendfile.2; on the non-blocking socket may
+	  result in the &man.sendfile.2; call blocking until enough
+	  <literal>struct sf_buf</literal>'s are made
+	  available.</para>
+      </important>
+
+      <sect3>
+	<title><varname>net.inet.ip.portrange.*</varname></title>
+
+	<indexterm>
+	  <primary>net.inet.ip.portrange.*</primary>
+	</indexterm>
+
+	<para>The <varname>net.inet.ip.portrange.*</varname> sysctl
+	  variables control the port number ranges automatically bound to TCP
+	  and UDP sockets.  There are three ranges: a low range, a default
+	  range, and a high range.  Most network programs use the default
+	  range which is controlled by the
+	  <varname>net.inet.ip.portrange.first</varname> and
+	  <varname>net.inet.ip.portrange.last</varname>, which default to
+	  1024 and 5000, respectively.  Bound port ranges are used  for
+	  outgoing connections, and it is possible to run the system out of
+	  ports under certain circumstances.  This most commonly occurs
+	  when you are running a heavily loaded web proxy.  The port range
+	  is not an issue when running servers which handle mainly incoming
+	  connections, such as a normal web server, or has a limited number
+	  of outgoing connections, such as a mail relay.  For situations
+	  where you may run yourself out of ports, it is recommended to
+	  increase <varname>net.inet.ip.portrange.last</varname> modestly.
+	  A value of <literal>10000</literal>, <literal>20000</literal> or
+	  <literal>30000</literal> may be reasonable.  You should also
+	  consider firewall effects when changing the port range.  Some
+	  firewalls may block large ranges of ports (usually low-numbered
+	  ports) and expect systems to use higher ranges of ports for
+	  outgoing connections &mdash; for this reason it is not recommended that
+	  <varname>net.inet.ip.portrange.first</varname> be lowered.</para>
+      </sect3>
+
+      <sect3>
+	<title>TCP Bandwidth Delay Product</title>
+
+	<indexterm>
+	  <primary>TCP Bandwidth Delay Product Limiting</primary>
+	  <secondary><varname>net.inet.tcp.inflight.enable</varname></secondary>
+	</indexterm>
+
+	<para>The TCP Bandwidth Delay Product Limiting is similar to
+	  TCP/Vegas in NetBSD.  It can be
+	  enabled by setting <varname>net.inet.tcp.inflight.enable</varname>
+	  sysctl variable to <literal>1</literal>.  The system will attempt
+	  to calculate the bandwidth delay product for each connection and
+	  limit the amount of data queued to the network to just the amount
+	  required to maintain optimum throughput.</para>
+
+	<para>This feature is useful if you are serving data over modems,
+	  Gigabit Ethernet, or even high speed WAN links (or any other link
+	  with a high bandwidth delay product), especially if you are also
+	  using window scaling or have configured a large send window.  If
+	  you enable this option, you should also be sure to set
+	  <varname>net.inet.tcp.inflight.debug</varname> to
+	  <literal>0</literal> (disable debugging), and for production use
+	  setting <varname>net.inet.tcp.inflight.min</varname> to at least
+	  <literal>6144</literal> may be beneficial.  However, note that
+	  setting high minimums may effectively disable bandwidth limiting
+	  depending on the link.  The limiting feature reduces the amount of
+	  data built up in intermediate route and switch packet queues as
+	  well as reduces the amount of data built up in the local host's
+	  interface queue.  With fewer packets queued up, interactive
+	  connections, especially over slow modems, will also be able to
+	  operate with lower <emphasis>Round Trip Times</emphasis>.  However,
+	  note that this feature only effects data transmission (uploading
+	  / server side).  It has no effect on data reception (downloading).
+	</para>
+
+	<para>Adjusting <varname>net.inet.tcp.inflight.stab</varname> is
+	  <emphasis>not</emphasis> recommended.  This parameter defaults to
+	  20, representing 2 maximal packets added to the bandwidth delay
+	  product window calculation.  The additional window is required to
+	  stabilize the algorithm and improve responsiveness to changing
+	  conditions, but it can also result in higher ping times over slow
+	  links (though still much lower than you would get without the
+	  inflight algorithm).  In such cases, you may wish to try reducing
+	  this parameter to 15, 10, or 5; and may also have to reduce
+	  <varname>net.inet.tcp.inflight.min</varname> (for example, to
+	  3500) to get the desired effect.  Reducing these parameters
+	  should be done as a last resort only.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Virtual Memory</title>
+
+      <sect3>
+        <title><varname>kern.maxvnodes</varname></title>
+
+        <para>A vnode is the internal representation of a file or
+          directory.  So increasing the number of vnodes available to
+          the operating system cuts down on disk I/O.  Normally this
+          is handled by the operating system and does not need to be
+          changed.  In some cases where disk I/O is a bottleneck and
+          the system is running out of vnodes, this setting will need
+          to be increased.  The amount of inactive and free RAM will
+          need to be taken into account.</para>
+
+        <para>To see the current number of vnodes in use:</para>
+
+        <programlisting>&prompt.root; sysctl vfs.numvnodes
+vfs.numvnodes: 91349</programlisting>
+
+        <para>To see the maximum vnodes:</para>
+
+        <programlisting>&prompt.root; sysctl kern.maxvnodes
+kern.maxvnodes: 100000</programlisting>
+
+        <para>If the current vnode usage is near the maximum, increasing
+          <varname>kern.maxvnodes</varname> by a value of 1,000 is
+          probably a good idea.  Keep an eye on the number of
+          <varname>vfs.numvnodes</varname>.  If it climbs up to the
+          maximum again, <varname>kern.maxvnodes</varname> will need to
+          be increased further.  A shift in your memory usage as
+          reported by &man.top.1; should be visible.  More memory should
+          be active.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="adding-swap-space">
+    <title>Adding Swap Space</title>
+
+    <para>No matter how well you plan, sometimes a system does not run
+      as you expect.  If you find you need more swap space, it is
+      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>
+
+    <para>For information on how to encrypt swap space, what options
+      for this task exist and why it should be done, please refer to
+      <xref linkend="swap-encrypting"> of the Handbook.</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 swap space
+	in <xref linkend="configtuning-initial">
+	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; 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 &os;</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 &amp;&amp; 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>Power and Resource Management</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
+      controlled by some sort of <acronym>BIOS</acronym> embedded
+      interface, such as <emphasis>Plug and Play BIOS (PNPBIOS)</emphasis>, or
+      <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 may want an operating system to
+      monitor system limits (and possibly alert you) in case your system
+      temperature increased unexpectedly.</para>
+
+    <para>In this section of the &os; Handbook, we will provide
+      comprehensive information about <acronym>ACPI</acronym>.  References
+      will be provided for further reading at the end.</para>
+
+    <sect2 id="acpi-intro">
+      <title>What Is ACPI?</title>
+
+      <indexterm>
+	<primary>ACPI</primary>
+      </indexterm>
+
+      <indexterm>
+	<primary>APM</primary>
+      </indexterm>
+
+      <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 prior to the introduction of
+	<acronym>ACPI</acronym>.  <acronym>ACPI</acronym> is the direct
+	successor to <acronym>APM</acronym>
+	(Advanced Power Management).</para>
+    </sect2>
+
+    <sect2 id="acpi-old-spec">
+      <title>Shortcomings of Advanced Power Management (APM)</title>
+
+      <para>The <emphasis>Advanced Power Management (APM)</emphasis>
+      facility controls the power usage of a system based on its
+      activity.  The APM BIOS is supplied by the (system) vendor and
+      it is specific to the hardware platform.  An APM driver in the
+      OS mediates access to the <emphasis>APM Software Interface</emphasis>,
+      which allows management of power levels.</para>
+
+      <para>There are four major problems in APM.  Firstly, power
+      management is done by the (vendor-specific) BIOS, and the OS
+      does not have any knowledge of it.  One example of this, is when
+      the user sets idle-time values for a hard drive in the APM BIOS,
+      that when exceeded, it (BIOS) would spin down the hard drive,
+      without the consent of the OS.  Secondly, the APM logic is
+      embedded in the BIOS, and it operates outside the scope of the
+      OS.  This means users can only fix problems in their APM BIOS by
+      flashing a new one into the ROM; which is a very dangerous
+      procedure with the potential to leave the system in an
+      unrecoverable state if it fails. Thirdly, APM is a vendor-specific
+      technology, which means that there is a lot of parity
+      (duplication of efforts) and bugs found in one vendor's BIOS,
+      may not be solved in others.  Last but not the least, the APM
+      BIOS did not have enough room to implement a sophisticated power
+      policy, or one that can adapt very well to the purpose of the
+      machine.</para>
+
+      <para><emphasis>Plug and Play BIOS (PNPBIOS)</emphasis> was
+      unreliable in many situations.  PNPBIOS is 16-bit technology,
+      so the OS has to use 16-bit emulation in order to
+      <quote>interface</quote> with PNPBIOS methods.</para>
+
+      <para>The &os; <acronym>APM</acronym> driver is documented in
+      the &man.apm.4; manual page.</para>
+    </sect2>
+
+    <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>
+  </sect1>
+
+  <sect1 id="ACPI-debug">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Nate</firstname>
+          <surname>Lawson</surname>
+          <contrib>Written by </contrib>
+        </author>
+      </authorgroup>
+      <authorgroup>
+        <author>
+          <firstname>Peter</firstname>
+          <surname>Schultz</surname>
+          <contrib>With contributions from </contrib>
+        </author>
+        <author>
+          <firstname>Tom</firstname>
+          <surname>Rhodes</surname>
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Using and Debugging &os; <acronym>ACPI</acronym></title>
+
+    <indexterm>
+      <primary>ACPI</primary>
+      <secondary>problems</secondary>
+    </indexterm>
+
+    <para><acronym>ACPI</acronym> is a fundamentally new way of
+      discovering devices, managing power usage, and providing
+      standardized access to various hardware previously managed
+      by the <acronym>BIOS</acronym>.  Progress is being made toward
+      <acronym>ACPI</acronym> working on all systems, but bugs in some
+      motherboards' <firstterm><acronym>ACPI</acronym> Machine
+      Language</firstterm> (<acronym>AML</acronym>) bytecode,
+      incompleteness in &os;'s kernel subsystems, and bugs in the &intel;
+      <acronym>ACPI-CA</acronym> interpreter continue to appear.</para>
+
+    <para>This document is intended to help you assist the &os;
+      <acronym>ACPI</acronym> maintainers in identifying the root cause
+      of problems you observe and debugging and developing a solution.
+      Thanks for reading this and we hope we can solve your system's
+      problems.</para>
+
+    <sect2 id="ACPI-submitdebug">
+      <title>Submitting Debugging Information</title>
+
+      <note>
+	<para>Before submitting a problem, be sure you are running the latest
+	  <acronym>BIOS</acronym> version and, if available, embedded
+	  controller firmware version.</para>
+      </note>
+
+      <para>For those of you that want to submit a problem right away,
+	please send the following information to
+	<ulink url="mailto:freebsd-acpi@FreeBSD.org">
+	freebsd-acpi@FreeBSD.org</ulink>:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Description of the buggy behavior, including system type
+	    and model and anything that causes the bug to appear.  Also,
+	    please note as accurately as possible when the bug began
+	    occurring if it is new for you.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The &man.dmesg.8; output after <command>boot
+	    -v</command>, including any error messages
+	    generated by you exercising the bug.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The &man.dmesg.8; output from <command>boot
+	    -v</command> with <acronym>ACPI</acronym>
+	    disabled, if disabling it helps fix the problem.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Output from <command>sysctl hw.acpi</command>.  This is also
+	    a good way of figuring out what features your system
+	    offers.</para>
+	</listitem>
+
+	<listitem>
+	  <para><acronym>URL</acronym> where your
+	    <firstterm><acronym>ACPI</acronym> Source Language</firstterm>
+	    (<acronym>ASL</acronym>)
+	    can be found.  Do <emphasis>not</emphasis> send the
+	    <acronym>ASL</acronym> directly to the list as it can be
+	    very large.  Generate a copy of your <acronym>ASL</acronym>
+	    by running this command:</para>
+
+	  <screen>&prompt.root; <userinput>acpidump -t -d &gt; <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen>
+
+	  <para>(Substitute your login name for
+	    <replaceable>name</replaceable> and manufacturer/model for
+	    <replaceable>system</replaceable>.  Example:
+	    <filename>njl-FooCo6000.asl</filename>)</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Most of the developers watch the &a.current;
+        but please submit problems to &a.acpi.name; to be sure it is
+	seen.  Please be patient, all of us have full-time jobs
+	elsewhere.  If your bug is not immediately apparent, we will
+	probably ask you to submit a <acronym>PR</acronym> via
+	&man.send-pr.1;.  When entering a <acronym>PR</acronym>, please
+	include the same information as requested above.  This will help
+	us track the problem and resolve it.  Do not send a
+	<acronym>PR</acronym> without emailing &a.acpi.name; first as we use
+	<acronym>PR</acronym>s as reminders of existing problems, not a
+	reporting mechanism.  It is likely that your problem has been
+	reported by someone before.</para>
+    </sect2>
+
+    <sect2 id="ACPI-background">
+      <title>Background</title>
+
+      <indexterm>
+	<primary>ACPI</primary>
+      </indexterm>
+
+      <para><acronym>ACPI</acronym> is present in all modern computers
+	that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD)
+	architectures.  The full standard has many features including
+	<acronym>CPU</acronym> performance management, power planes
+	control, thermal zones, various battery systems, embedded
+	controllers, and bus enumeration.  Most systems implement less
+	than the full standard.  For instance, a desktop system usually
+	only implements the bus enumeration parts while a laptop might
+	have cooling and battery management support as well.  Laptops
+	also have suspend and resume, with their own associated
+	complexity.</para>
+
+      <para>An <acronym>ACPI</acronym>-compliant system has various
+	components.  The <acronym>BIOS</acronym> and chipset vendors
+	provide various fixed tables (e.g., <acronym>FADT</acronym>)
+	in memory that specify things like the <acronym>APIC</acronym>
+	map (used for <acronym>SMP</acronym>), config registers, and
+	simple configuration values.  Additionally, a table of bytecode
+	(the <firstterm>Differentiated System Description Table</firstterm>
+	<acronym>DSDT</acronym>) is provided that specifies a
+	tree-like name space of devices and methods.</para>
+
+      <para>The <acronym>ACPI</acronym> driver must parse the fixed
+	tables, implement an interpreter for the bytecode, and modify
+	device drivers and the kernel to accept information from the
+	<acronym>ACPI</acronym> subsystem.  For &os;, &intel; has
+	provided an interpreter (<acronym>ACPI-CA</acronym>) that is
+	shared with Linux and NetBSD.  The path to the
+	<acronym>ACPI-CA</acronym> source code is
+	<filename class="directory">src/sys/contrib/dev/acpica</filename>.
+	The glue code that allows <acronym>ACPI-CA</acronym> to work on
+	&os; is in
+	<filename>src/sys/dev/acpica/Osd</filename>.  Finally, drivers
+	that implement various <acronym>ACPI</acronym> devices are found
+	in
+	<filename class="directory">src/sys/dev/acpica</filename>.</para>
+    </sect2>
+
+    <sect2 id="ACPI-comprob">
+      <title>Common Problems</title>
+
+      <indexterm>
+	<primary>ACPI</primary>
+	<secondary>problems</secondary>
+      </indexterm>
+
+      <para>For <acronym>ACPI</acronym> to work correctly, all the parts
+	have to work correctly.  Here are some common problems, in order
+	of frequency of appearance, and some possible workarounds or
+	fixes.</para>
+
+      <sect3>
+	<title>Mouse Issues</title>
+
+	<para>In some cases, resuming from a suspend operation will
+	  cause the mouse to fail.  A known work around is to add
+	  <literal>hint.psm.0.flags="0x3000"</literal> to the
+	  <filename>/boot/loader.conf</filename> file.  If this
+	  does not work then please consider sending a bug report
+	  as described above.</para>
+      </sect3>
+
+      <sect3>
+	<title>Suspend/Resume</title>
+
+	<para><acronym>ACPI</acronym> has three suspend to
+	  <acronym>RAM</acronym> (<acronym>STR</acronym>) states,
+	  <literal>S1</literal>-<literal>S3</literal>, and one suspend
+	  to disk state (<literal>STD</literal>), called
+	  <literal>S4</literal>.  <literal>S5</literal> is
+	  <quote>soft off</quote> and is the normal state your system
+	  is in when plugged in but not powered up.
+	  <literal>S4</literal> can actually be implemented two separate
+	  ways.  <literal>S4</literal><acronym>BIOS</acronym> is a
+	  <acronym>BIOS</acronym>-assisted suspend to disk.
+	  <literal>S4</literal><acronym>OS</acronym> is implemented
+	  entirely by the operating system.</para>
+
+	<para>Start by checking <command>sysctl hw.acpi</command>
+	  for the suspend-related items.  Here
+	  are the results for a Thinkpad:</para>
+
+	<screen>hw.acpi.supported_sleep_state: S3 S4 S5
+hw.acpi.s4bios: 0</screen>
+
+	<para>This means that we can use <command>acpiconf -s</command>
+	  to test <literal>S3</literal>,
+	  <literal>S4</literal><acronym>OS</acronym>, and
+	  <literal>S5</literal>.  If <option>s4bios</option> was one
+	  (<literal>1</literal>), we would have
+	  <literal>S4</literal><acronym>BIOS</acronym>
+	  support instead of <literal>S4</literal>
+	  <acronym>OS</acronym>.</para>
+
+	<para>When testing suspend/resume, start with
+	  <literal>S1</literal>, if supported.  This state is most
+	  likely to work since it does not require much driver support.
+	  No one has implemented <literal>S2</literal> but if you have
+	  it, it is similar to <literal>S1</literal>.  The next thing
+	  to try is <literal>S3</literal>.  This is the deepest
+	  <acronym>STR</acronym> state and requires a lot of driver
+	  support to properly reinitialize your hardware.  If you have
+	  problems resuming, feel free to email the &a.acpi.name; list but
+	  do not expect the problem to be resolved since there are a lot
+	  of drivers/hardware that need more testing and work.</para>
+
+	<para>To help isolate the problem, remove as many drivers from
+	  your kernel as possible.  If it works, you can narrow down
+	  which driver is the problem by loading drivers until it fails
+	  again.  Typically binary drivers like
+	  <filename>nvidia.ko</filename>, X11
+	  display drivers, and <acronym>USB</acronym> will have the most
+	  problems while Ethernet interfaces usually work fine.  If you
+	  can properly load/unload the drivers, you can automate this by
+	  putting the appropriate commands in
+	  <filename>/etc/rc.suspend</filename> and
+	  <filename>/etc/rc.resume</filename>.  There is a
+	  commented-out example for unloading and loading a driver.  Try
+	  setting <option>hw.acpi.reset_video</option> to zero (<literal>0</literal>) if
+	  your display is messed up after resume.  Try setting longer or
+	  shorter values for <option>hw.acpi.sleep_delay</option> to see
+	  if that helps.</para>
+
+	<para>Another thing to try is load a recent Linux distribution
+	  with <acronym>ACPI</acronym> support and test their
+	  suspend/resume support on the same hardware.  If it works
+	  on Linux, it is likely a &os; driver problem and narrowing down
+	  which driver causes the problems will help us fix the problem.
+	  Note that the <acronym>ACPI</acronym> maintainers do not
+	  usually maintain other drivers (e.g sound,
+	  <acronym>ATA</acronym>, etc.) so any work done on tracking
+	  down a driver problem should probably eventually be posted
+	  to the &a.current.name; list and mailed to the driver
+	  maintainer.  If you are feeling adventurous, go ahead and
+	  start putting some debugging &man.printf.3;s in a problematic
+	  driver to track down where in its resume function it
+	  hangs.</para>
+
+	<para>Finally, try disabling <acronym>ACPI</acronym> and
+	  enabling <acronym>APM</acronym> instead.  If suspend/resume
+	  works with <acronym>APM</acronym>, you may be better off
+	  sticking with <acronym>APM</acronym>, especially on older
+	  hardware (pre-2000).  It took vendors a while to get
+	  <acronym>ACPI</acronym> support correct and older hardware is
+	  more likely to have <acronym>BIOS</acronym> problems with
+	  <acronym>ACPI</acronym>.</para>
+      </sect3>
+
+      <sect3>
+	<title>System Hangs (temporary or permanent)</title>
+
+	<para>Most system hangs are a result of lost interrupts or an
+	  interrupt storm.  Chipsets have a lot of problems based on how
+	  the <acronym>BIOS</acronym> configures interrupts before boot,
+	  correctness of the <acronym>APIC</acronym>
+	  (<acronym>MADT</acronym>) table, and routing of the
+	  <firstterm>System Control Interrupt</firstterm>
+	  (<acronym>SCI</acronym>).</para>
+
+	<indexterm>
+	  <primary>interrupt storms</primary>
+	</indexterm>
+
+	<para>Interrupt storms can be distinguished from lost interrupts
+	  by checking the output of <command>vmstat -i</command>
+	  and looking at the line that has
+	  <literal>acpi0</literal>.  If the counter is increasing at more
+	  than a couple per second, you have an interrupt storm.  If the
+	  system appears hung, try breaking to <acronym>DDB</acronym>
+	  (<keycombo action="simul"><keycap>CTRL</keycap>
+	  <keycap>ALT</keycap><keycap>ESC</keycap></keycombo> on
+	  console) and type <literal>show interrupts</literal>.</para>
+
+	<indexterm>
+	  <primary>APIC</primary>
+	  <secondary>disabling</secondary>
+	</indexterm>
+
+	<para>Your best hope when dealing with interrupt problems is to
+	  try disabling <acronym>APIC</acronym> support with
+	  <literal>hint.apic.0.disabled="1"</literal> in
+	  <filename>loader.conf</filename>.</para>
+      </sect3>
+
+      <sect3>
+	<title>Panics</title>
+
+	<para>Panics are relatively rare for <acronym>ACPI</acronym> and
+	  are the top priority to be fixed.  The first step is to
+	  isolate the steps to reproduce the panic (if possible)
+	  and get a backtrace.  Follow the advice for enabling
+	  <literal>options DDB</literal> and setting up a serial console
+	  (see <xref linkend="serialconsole-ddb">)
+	  or setting up a &man.dump.8; partition.  You can get a
+	  backtrace in <acronym>DDB</acronym> with
+	  <literal>tr</literal>.  If you have to handwrite the
+	  backtrace, be sure to at least get the lowest five (5) and top
+	  five (5) lines in the trace.</para>
+
+	<para>Then, try to isolate the problem by booting with
+	  <acronym>ACPI</acronym> disabled.  If that works, you can
+	  isolate the <acronym>ACPI</acronym> subsystem by using various
+	  values of <option>debug.acpi.disable</option>.  See the
+	  &man.acpi.4; manual page for some examples.</para>
+      </sect3>
+
+      <sect3>
+	<title>System Powers Up After Suspend or Shutdown</title>
+	<para>First, try setting
+	  <literal>hw.acpi.disable_on_poweroff="0"</literal>
+	  in &man.loader.conf.5;.  This keeps <acronym>ACPI</acronym>
+	  from disabling various events during the shutdown process.
+	  Some systems need this value set to <literal>1</literal> (the
+	  default) for the same reason.  This usually fixes
+	  the problem of a system powering up spontaneously after a
+	  suspend or poweroff.</para>
+      </sect3>
+
+      <sect3>
+	<title>Other Problems</title>
+
+	<para>If you have other problems with <acronym>ACPI</acronym>
+	  (working with a docking station, devices not detected, etc.),
+	  please email a description to the mailing list as well;
+	  however, some of these issues may be related to unfinished
+	  parts of the <acronym>ACPI</acronym> subsystem so they might
+	  take a while to be implemented.  Please be patient and
+	  prepared to test patches we may send you.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="ACPI-aslanddump">
+      <title><acronym>ASL</acronym>, <command>acpidump</command>, and
+        <acronym>IASL</acronym></title>
+
+      <indexterm>
+	<primary>ACPI</primary>
+	<secondary>ASL</secondary>
+      </indexterm>
+
+      <para>The most common problem is the <acronym>BIOS</acronym>
+	vendors providing incorrect (or outright buggy!) bytecode.  This
+	is usually manifested by kernel console messages like
+	this:</para>
+
+      <screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\
+(Node 0xc3f6d160), AE_NOT_FOUND</screen>
+
+      <para>Often, you can resolve these problems by updating your
+	<acronym>BIOS</acronym> to the latest revision.  Most console
+	messages are harmless but if you have other problems like
+	battery status not working, they are a good place to start
+	looking for problems in the <acronym>AML</acronym>.  The
+	bytecode, known as <acronym>AML</acronym>, is compiled from a
+	source language called <acronym>ASL</acronym>.  The
+	<acronym>AML</acronym> is found in the table known as the
+	<acronym>DSDT</acronym>.  To get a copy of your
+	<acronym>ASL</acronym>, use &man.acpidump.8;.  You should use
+	both the <option>-t</option> (show contents of the fixed tables)
+	and <option>-d</option> (disassemble <acronym>AML</acronym> to
+	<acronym>ASL</acronym>) options.  See the
+	<link linkend="ACPI-submitdebug">Submitting Debugging
+	Information</link> section for an example syntax.</para>
+
+      <para>The simplest first check you can do is to recompile your
+	<acronym>ASL</acronym> to check for errors.  Warnings can
+	usually be ignored but errors are bugs that will usually prevent
+	<acronym>ACPI</acronym> from working correctly.  To recompile
+	your <acronym>ASL</acronym>, issue the following command:</para>
+
+      <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
+    </sect2>
+
+    <sect2 id="ACPI-fixasl">
+      <title>Fixing Your <acronym>ASL</acronym></title>
+
+      <indexterm>
+	<primary>ACPI</primary>
+	<secondary>ASL</secondary>
+      </indexterm>
+
+      <para>In the long run, our goal is for almost everyone to have
+	<acronym>ACPI</acronym> work without any user intervention.  At
+	this point, however, we are still developing workarounds for
+	common mistakes made by the <acronym>BIOS</acronym> vendors.
+	The &microsoft; interpreter (<filename>acpi.sys</filename> and
+	<filename>acpiec.sys</filename>) does not strictly check for
+	adherence to the standard, and thus many <acronym>BIOS</acronym>
+	vendors who only test <acronym>ACPI</acronym> under &windows;
+	never fix their <acronym>ASL</acronym>.  We hope to continue to
+	identify and document exactly what non-standard behavior is
+	allowed by &microsoft;'s interpreter and replicate it so &os; can
+	work without forcing users to fix the <acronym>ASL</acronym>.
+	As a workaround and to help us identify behavior, you can fix
+	the <acronym>ASL</acronym> manually.  If this works for you,
+	please send a &man.diff.1; of the old and new
+	<acronym>ASL</acronym> so we can possibly work around the buggy
+	behavior in <acronym>ACPI-CA</acronym> and thus make your fix
+	unnecessary.</para>
+
+      <indexterm>
+	<primary>ACPI</primary>
+	<secondary>error messages</secondary>
+      </indexterm>
+
+      <para>Here is a list of common error messages, their cause, and
+	how to fix them:</para>
+
+      <sect3>
+	<title>_OS dependencies</title>
+
+	<para>Some <acronym>AML</acronym> assumes the world consists of
+	  various &windows; versions.  You can tell &os; to claim it is
+	  any <acronym>OS</acronym> to see if this fixes problems you
+	  may have.  An easy way to override this is to set
+	  <literal>hw.acpi.osname="Windows 2001"</literal>
+	  in <filename>/boot/loader.conf</filename> or other similar
+	  strings you find in the <acronym>ASL</acronym>.</para>
+      </sect3>
+
+      <sect3>
+	<title>Missing Return statements</title>
+
+	<para>Some methods do not explicitly return a value as the
+	  standard requires.  While <acronym>ACPI-CA</acronym>
+	  does not handle this, &os; has a workaround that allows it to
+	  return the value implicitly.  You can also add explicit
+	  Return statements where required if you know what value should
+	  be returned.  To force <command>iasl</command> to compile the
+	  <acronym>ASL</acronym>, use the <option>-f</option>
+	  flag.</para>
+      </sect3>
+
+      <sect3>
+	<title>Overriding the Default <acronym>AML</acronym></title>
+
+	<para>After you customize <filename>your.asl</filename>, you
+	  will want to compile it, run:</para>
+
+	<screen>&prompt.root; <userinput>iasl your.asl</userinput></screen>
+
+	<para>You can add the <option>-f</option> flag to force creation
+	  of the <acronym>AML</acronym>, even if there are errors during
+	  compilation.  Remember that some errors (e.g., missing Return
+	  statements) are automatically worked around by the
+	  interpreter.</para>
+
+	<para><filename>DSDT.aml</filename> is the default output
+	  filename for <command>iasl</command>.  You can load this
+	  instead of your <acronym>BIOS</acronym>'s buggy copy (which
+	  is still present in flash memory) by editing
+	  <filename>/boot/loader.conf</filename> as
+	  follows:</para>
+
+	<programlisting>acpi_dsdt_load="YES"
+acpi_dsdt_name="/boot/DSDT.aml"</programlisting>
+
+	<para>Be sure to copy your <filename>DSDT.aml</filename> to the
+	  <filename class="directory">/boot</filename> directory.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="ACPI-debugoutput">
+      <title>Getting Debugging Output From
+	<acronym>ACPI</acronym></title>
+
+      <indexterm>
+	<primary>ACPI</primary>
+	<secondary>problems</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>ACPI</primary>
+	<secondary>debugging</secondary>
+      </indexterm>
+
+      <para>The <acronym>ACPI</acronym> driver has a very flexible
+	debugging facility.  It allows you to specify a set of subsystems
+	as well as the level of verbosity.  The subsystems you wish to
+	debug are specified as <quote>layers</quote> and are broken down
+	into <acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS)
+	and <acronym>ACPI</acronym> hardware support (ACPI_ALL_DRIVERS).
+	The verbosity of debugging output is specified as the
+	<quote>level</quote> and ranges from ACPI_LV_ERROR (just report
+	errors) to ACPI_LV_VERBOSE (everything).  The
+	<quote>level</quote> is a bitmask so multiple options can be set
+	at once, separated by spaces.  In practice, you will want to use
+	a serial console to log the output if it is so long
+	it flushes the console message buffer.  A full list of the
+	individual layers and levels is found in the &man.acpi.4; manual
+	page.</para>
+
+      <para>Debugging output is not enabled by default.  To enable it,
+	add <literal>options ACPI_DEBUG</literal> to your kernel configuration file
+	if <acronym>ACPI</acronym> is compiled into the kernel.  You can
+	add <literal>ACPI_DEBUG=1</literal> to your
+	<filename>/etc/make.conf</filename> to enable it globally.  If
+	it is a module, you can recompile just your
+	<filename>acpi.ko</filename> module as follows:</para>
+
+      <screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi
+&amp;&amp; make clean &amp;&amp;
+make ACPI_DEBUG=1</userinput></screen>
+
+      <para>Install <filename>acpi.ko</filename> in
+	<filename class="directory">/boot/kernel</filename> and add your
+	desired level and layer to <filename>loader.conf</filename>.
+	This example enables debug messages for all
+	<acronym>ACPI-CA</acronym> components and all
+	<acronym>ACPI</acronym> hardware drivers
+	(<acronym>CPU</acronym>, <acronym>LID</acronym>, etc.)  It will
+	only output error messages, the least verbose level.</para>
+
+      <programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS"
+debug.acpi.level="ACPI_LV_ERROR"</programlisting>
+
+      <para>If the information you want is triggered by a specific event
+	(say, a suspend and then resume), you can leave out changes to
+	<filename>loader.conf</filename> and instead use
+	<command>sysctl</command> to specify the layer and level after
+	booting and preparing your system for the specific event.  The
+	<command>sysctl</command>s are named the same as the tunables
+	in <filename>loader.conf</filename>.</para>
+    </sect2>
+
+    <sect2 id="ACPI-References">
+      <title>References</title>
+
+      <para>More information about <acronym>ACPI</acronym> may be found
+	in the following locations:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>The &a.acpi;</para>
+	</listitem>
+
+	<listitem>
+	  <para>The <acronym>ACPI</acronym> Mailing List Archives
+	    <ulink url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para>
+	</listitem>
+
+        <listitem>
+          <para>The old <acronym>ACPI</acronym> Mailing List Archives
+            <ulink url="http://home.jp.FreeBSD.org/mail-list/acpi-jp/"></ulink></para>
+        </listitem>
+
+	<listitem>
+	  <para>The <acronym>ACPI</acronym> 2.0 Specification
+	    <ulink url="http://acpi.info/spec.htm"></ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para>&os; Manual pages: &man.acpi.4;,
+	    &man.acpi.thermal.4;, &man.acpidump.8;, &man.iasl.8;,
+	    &man.acpidb.8;</para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	    url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt">
+	    <acronym>DSDT</acronym> debugging resource</ulink>.
+	    (Uses Compaq as an example but generally useful.)</para>
+	</listitem>
+      </itemizedlist>
+    </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/pl_PL.ISO8859-2/books/handbook/cutting-edge/Makefile b/pl_PL.ISO8859-2/books/handbook/cutting-edge/Makefile
new file mode 100644
index 0000000000..29da7845dd
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/cutting-edge/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	cutting-edge/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/cutting-edge/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/cutting-edge/chapter.sgml
new file mode 100644
index 0000000000..63f4f9bcd0
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/cutting-edge/chapter.sgml
@@ -0,0 +1,1732 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="cutting-edge">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Jim</firstname>
+	<surname>Mock</surname>
+	<contrib>Restructured, reorganized, and parts updated by </contrib>
+      </author>
+      <!-- Mar 2000 -->
+    </authorgroup>
+    <authorgroup>
+      <author>
+	<firstname>Jordan</firstname>
+	<surname>Hubbard</surname>
+	<contrib>Original work by </contrib>
+      </author>
+      <author>
+	<firstname>Poul-Henning</firstname>
+	<surname>Kamp</surname>
+      </author>
+      <author>
+	<firstname>John</firstname>
+	<surname>Polstra</surname>
+      </author>
+      <author>
+	<firstname>Nik</firstname>
+	<surname>Clayton</surname>
+      </author>
+    </authorgroup>
+    <!-- with feedback from various others -->
+  </chapterinfo>
+
+  <title>The Cutting Edge</title>
+
+  <sect1 id="cutting-edge-synopsis">
+    <title>Synopsis</title>
+
+    <para>&os; is under constant development between releases.  For
+      people who want to be on the cutting edge, there are several easy
+      mechanisms for keeping your system in sync with the latest
+      developments.  Be warned&mdash;the cutting edge is not for everyone!
+      This chapter will help you decide if you want to track the
+      development system, or stick with one of the released
+      versions.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem><para>The difference between the two development
+      branches: &os.stable; and &os.current;.</para>
+      </listitem>
+      <listitem><para>How to keep your system up to date with
+	  <application>CVSup</application>,
+	  <application>CVS</application>, or
+	  <application>CTM</application>.</para>
+      </listitem>
+      <listitem><para>How to rebuild and reinstall the entire base
+      system with <command>make buildworld</command> (etc).</para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem><para>Properly set up your network connection (<xref
+      linkend="advanced-networking">).</para>
+      </listitem>
+      <listitem><para>Know how to install additional third-party
+        software (<xref linkend="ports">).</para></listitem>
+    </itemizedlist>
+  </sect1>
+  
+  <sect1 id="current-stable">
+    <title>&os.current; vs. &os.stable;</title>
+    <indexterm><primary>-CURRENT</primary></indexterm>
+    <indexterm><primary>-STABLE</primary></indexterm>
+
+    <para>There are two development branches to FreeBSD: &os.current; and
+      &os.stable;.  This section will explain a bit about each and describe
+      how to keep your system up-to-date with each respective tree.
+      &os.current; will be discussed first, then &os.stable;.</para>
+
+    <sect2 id="current">
+      <title>Staying Current with &os;</title>
+
+      <para>As you read this, keep in mind that &os.current; is the
+	<quote>bleeding edge</quote> of &os; development.
+	&os.current; users are expected to have a high degree of
+	technical skill, and should be capable of solving difficult
+	system problems on their own.  If you are new to &os;, think
+	twice before installing it.  </para>
+
+      <sect3>
+	<title>What Is &os.current;?</title>
+	<indexterm><primary>snapshot</primary></indexterm>
+
+	<para>&os.current; is the latest working sources for &os;.
+	  This includes work in progress, experimental changes, and
+	  transitional mechanisms that might or might not be present
+	  in the next official release of the software.  While many
+	  &os; developers compile the &os.current; source code daily,
+	  there are periods of time when the sources are not
+	  buildable.  These problems are resolved as expeditiously as
+	  possible, but whether or not &os.current; brings disaster or
+	  greatly desired functionality can be a matter of which exact
+	  moment you grabbed the source code in!</para>
+      </sect3>
+
+      <sect3>
+	<title>Who Needs &os.current;?</title>
+
+	<para>&os.current; is made available for 3 primary
+	  interest groups:</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>Members of the &os; community who are actively working
+	      on some part of the source tree and for whom keeping
+	      <quote>current</quote> is an absolute
+	      requirement.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Members of the &os; community who are active testers,
+	      willing to spend time solving problems in order to
+	      ensure that &os.current; remains as sane as possible.
+	      These are also people who wish to make topical
+	      suggestions on changes and the general direction of
+	      &os;, and submit patches to implement them.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Those who merely wish to keep an eye on things, or
+	      to use the current sources for reference purposes
+	      (e.g. for <emphasis>reading</emphasis>, not running).
+	      These people also make the occasional comment or
+	      contribute code.</para>
+	  </listitem>
+	</orderedlist>
+      </sect3>
+
+      <sect3>
+	<title>What Is &os.current; <emphasis>Not</emphasis>?</title>
+
+	<orderedlist>
+	  <listitem>
+	    <para>A fast-track to getting pre-release bits because you
+	      heard there is some cool new feature in there and you
+	      want to be the first on your block to have it.  Being
+	      the first on the block to get the new feature means that
+	      you are the first on the block to get the new
+	      bugs.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>A quick way of getting bug fixes.  Any given version
+	      of &os.current; is just as likely to introduce new bugs
+	      as to fix existing ones.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>In any way <quote>officially supported</quote>.  We
+	      do our best to help people genuinely in one of the 3
+	      <quote>legitimate</quote> &os.current; groups, but we
+	      simply <emphasis>do not have the time</emphasis> to
+	      provide tech support.  This is not because we are mean
+	      and nasty people who do not like helping people out (we
+	      would not even be doing &os; if we were).  We simply
+	      cannot answer hundreds messages a day
+	      <emphasis>and</emphasis> work on FreeBSD!  Given the
+	      choice between improving &os; and answering lots of
+	      questions on experimental code, the developers opt for
+	      the former.</para>
+	  </listitem>
+	</orderedlist>
+      </sect3>
+
+      <sect3>
+	<title>Using &os.current;</title>
+      
+	<indexterm>
+	  <primary>-CURRENT</primary>
+	  <secondary>using</secondary>
+	</indexterm>
+	<orderedlist>
+	  <listitem>
+	    <para>Join the &a.current.name; and the &a.cvsall.name; lists.  This is not
+	      just a good idea, it is <emphasis>essential</emphasis>.  If
+	      you are not on the <emphasis>&a.current.name;</emphasis> list,
+	      you will not see the comments that people are
+	      making about the current state of the system and thus will
+	      probably end up stumbling over a lot of problems that others
+	      have already found and solved.  Even more importantly, you
+	      will miss out on important bulletins which may be critical
+	      to your system's continued health.</para>
+
+	    <para>The &a.cvsall.name; list will allow you to see the
+	      commit log entry for each change as it is made along with
+	      any pertinent information on possible side-effects.</para>
+
+	    <para>To join these lists, or one of the others available
+	      go to &a.mailman.lists.link; and click on the list that
+	      you wish to subscribe to.  Instructions on the rest of
+	      the procedure are available there.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Grab the sources from a &os; <link linkend="mirrors">mirror
+	      site</link>.  You can do this in one of two ways:</para>
+
+	    <orderedlist>
+              <indexterm>
+                <primary><command>cvsup</command></primary>
+              </indexterm>
+              <indexterm>
+                <primary><command>cron</command></primary>
+              </indexterm>
+              <indexterm>
+	        <primary>-CURRENT</primary>
+		<secondary>Syncing with <application>CVSup</application></secondary>
+	      </indexterm>
+
+	      <listitem>
+		<para>Use the <link linkend="cvsup">cvsup</link> program
+                  with the <filename>supfile</filename> named <filename>standard-supfile</filename>
+                  available from <filename>/usr/share/examples/cvsup</filename>.
+		  This is the most recommended
+		  method, since it allows you to grab the entire
+		  collection once and then only what has changed from then
+		  on.  Many people run <command>cvsup</command> from 
+		  <command>cron</command> and keep their
+ 		  sources up-to-date automatically.  You have to 
+ 		  customize the sample <filename>supfile</filename> above, and configure 
+ 		  <link linkend="cvsup">cvsup</link> for your environment.</para>
+	      </listitem>
+
+              <indexterm>
+	        <primary>-CURRENT</primary>
+		<secondary>Syncing with CTM</secondary>
+	      </indexterm>
+	      <listitem>
+		<para>Use the <application><link
+		  linkend="ctm">CTM</link></application> facility.  If you
+		  have very bad connectivity (high price connections or
+		  only email access) <application>CTM</application> is an option.
+		  However, it is a lot of hassle and can give you broken files.
+		  This leads to it being rarely used, which again increases
+		  the chance of it not working for fairly long periods of
+		  time.  We recommend using
+		  <application><link linkend="cvsup">CVSup</link></application>
+		  for anybody with a 9600&nbsp;bps modem or faster connection.
+		</para>
+	      </listitem>
+	    </orderedlist>
+	  </listitem>
+
+	  <listitem>
+	    <para>If you are grabbing the sources to run, and not just
+	      look at, then grab <emphasis>all</emphasis> of &os.current;, not
+	      just selected portions.  The reason for this is that various
+	      parts of the source depend on updates elsewhere, and trying
+	      to compile just a subset is almost guaranteed to get you
+	      into trouble.</para>
+
+	  <indexterm>
+	    <primary>-CURRENT</primary>
+	    <secondary>compiling</secondary>
+	  </indexterm>
+	    <para>Before compiling &os.current;, read the
+	      <filename>Makefile</filename> in <filename>/usr/src</filename>
+	      carefully.  You should at least <link
+	      linkend="makeworld">install a new kernel and rebuild the world</link> the first time through
+	      as part of the upgrading process.  Reading the &a.current;
+	      and <filename>/usr/src/UPDATING</filename> will keep you up-to-date on other bootstrapping procedures
+	      that sometimes become necessary as we move toward the next
+	      release.</para>
+	  </listitem>
+	      
+	  <listitem>
+	    <para>Be active! If you are running &os.current;, we want
+	      to know what you have to say about it, especially if you
+	      have suggestions for enhancements or bug fixes.  Suggestions
+	      with accompanying code are received most
+	      enthusiastically!</para>
+	  </listitem>
+	</orderedlist>
+      </sect3>
+    </sect2>
+  
+    <sect2 id="stable">
+      <title>Staying Stable with &os;</title>
+
+      <sect3>
+	<title>What Is &os.stable;?</title>
+	<indexterm><primary>-STABLE</primary></indexterm>
+
+	<para>&os.stable; is our development branch from which major releases
+	  are made.  Changes go into this branch at a different pace, and
+	  with the general assumption that they have first gone into
+	  &os.current; for testing.  This is <emphasis>still</emphasis>
+	  a development branch, however, and this means that at any given time,
+	  the sources for &os.stable; may or may not be suitable for any
+	  particular purpose.  It is simply another engineering development
+	  track, not a resource for end-users.</para>
+      </sect3>
+
+      <sect3>
+	<title>Who Needs &os.stable;?</title>
+
+	<para>If you are interested in tracking or contributing to the
+          FreeBSD development process, especially as it relates to the
+	  next <quote>point</quote> release of FreeBSD, then you should
+	  consider following &os.stable;.</para>
+
+	<para>While it is true that security fixes also go into the
+	  &os.stable; branch, you do not <emphasis>need</emphasis> to
+	  track &os.stable; to do this. Every security advisory for
+	  FreeBSD explains how to fix the problem for the releases it
+	  affects
+	  <footnote><para>That is not quite true.  We can not continue to
+  	    support old releases of FreeBSD forever, although we do
+  	    support them for many years.  For a complete description
+  	    of the current security policy for old releases of
+  	    FreeBSD, please see <ulink
+  	    url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para>
+	  </footnote>
+	  , and tracking an entire development branch just
+	  for security reasons is likely to bring in a lot of unwanted
+	  changes as well.</para>
+
+	<para>Although we endeavor to ensure that the &os.stable; branch
+	  compiles and runs at all times, this cannot be guaranteed.  In
+	  addition, while code is developed in &os.current; before including
+	  it in &os.stable;, more people run &os.stable; than &os.current;, so
+	  it is inevitable that bugs and corner cases will sometimes be found
+	  in &os.stable; that were not apparent in &os.current;.</para>
+
+	<para>For these reasons, we do <emphasis>not</emphasis> recommend that
+	  you blindly track &os.stable;, and it is particularly important that
+	  you do not update any production servers to &os.stable; without
+	  first thoroughly testing the code in your development
+	  environment.</para>
+
+	<para>If you do not have the resources to do this then we recommend
+	  that you run the most recent release of FreeBSD, and use the binary
+	  update mechanism to move from release to release.</para>
+      </sect3>
+
+      <sect3>
+	<title>Using &os.stable;</title>
+      
+	<indexterm>
+	  <primary>-STABLE</primary>
+	  <secondary>using</secondary>
+	</indexterm>
+	<orderedlist>
+	  <listitem>
+	    <para>Join the &a.stable.name; list.  This will keep you informed of
+	      build-dependencies that may appear in &os.stable;
+	      or any other issues requiring
+	      special attention.  Developers will also make announcements
+	      in this mailing list when they are contemplating some
+	      controversial fix or update, giving the users a chance to
+	      respond if they have any issues to raise concerning the
+	      proposed change.</para>
+
+	    <para>The &a.cvsall.name; list will allow you to see the
+	      commit log entry for each change as it is made along with
+	      any pertinent information on possible side-effects.</para>
+
+	    <para>To join these lists, or one of the others available
+	      go to &a.mailman.lists.link; and click on the list that
+	      you wish to subscribe to.  Instructions on the rest of
+	      the procedure are available there.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>If you are going to install a new system and want it
+	      to run monthly snapshot built from &os.stable;, please
+	      check the <ulink url="&url.base;/snapshots/">
+		Snapshots</ulink> web page for more information.
+	      Alternatively, it is possible to
+	      install the most recent &os.stable; release from the
+	      <link linkend="mirrors">mirror sites</link> and follow
+	      the instructions below to upgrade your system to the
+	      most up to date &os.stable; source code.</para>
+
+	    <para>If you are already running a previous release of &os;
+	      and wish to upgrade via sources then you can easily do so
+	      from &os; <link linkend="mirrors">mirror site</link>.  This can
+	      be done in one of two ways:</para>
+
+	    <orderedlist>
+	      <indexterm>
+		<primary><command>cvsup</command></primary>
+	      </indexterm>
+	      <indexterm>
+		<primary><command>cron</command></primary>
+	      </indexterm>
+	      <indexterm>
+	        <primary>-STABLE</primary>
+		<secondary>syncing with <application>CVSup</application></secondary>
+	      </indexterm>
+	      <listitem>
+		<para>Use the <link linkend="cvsup">cvsup</link> program
+                  with the <filename>supfile</filename> named <filename>stable-supfile</filename>
+                  from the directory
+                  <filename>/usr/share/examples/cvsup</filename>.
+		  This is the most recommended
+		  method, since it allows you to grab the entire
+		  collection once and then only what has changed from then
+		  on.  Many people run <command>cvsup</command> from 
+		  <command>cron</command> to keep their
+		  sources up-to-date automatically.  You have to
+		  customize the sample <filename>supfile</filename> above,
+		  and configure <link linkend="cvsup">cvsup</link> for your
+		  environment.</para>
+	      </listitem>
+
+	      <indexterm>
+	        <primary>-STABLE</primary>
+		<secondary>syncing with CTM</secondary>
+	      </indexterm>
+	      <listitem>
+		<para>Use the <application><link
+		  linkend="ctm">CTM</link></application> facility.  If
+		  you do not have a fast and inexpensive connection to
+		  the Internet, this is the method you should consider
+		  using.
+		  </para>
+	      </listitem>
+	   </orderedlist>
+	 </listitem>
+
+	  <listitem>
+	    <para>Essentially, if you need rapid on-demand access to the
+	      source and communications bandwidth is not a consideration,
+	      use <command>cvsup</command> or <command>ftp</command>.
+	      Otherwise, use <application>CTM</application>.</para>
+	  </listitem>
+
+	  <indexterm>
+	    <primary>-STABLE</primary>
+	    <secondary>compiling</secondary>
+	  </indexterm>
+	  <listitem>
+	    <para>Before compiling &os.stable;, read the
+	    <filename>Makefile</filename> in <filename>/usr/src</filename>
+	    carefully.  You should at least <link
+	    linkend="makeworld">install a new kernel and rebuild the world</link> the first time through
+	    as part of the upgrading process.  Reading the &a.stable; and <filename>/usr/src/UPDATING</filename> will
+	    keep you up-to-date on other bootstrapping procedures that
+	    sometimes become necessary as we move toward the next
+	    release.</para>
+	  </listitem>
+	</orderedlist>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="synching">
+    <title>Synchronizing Your Source</title>
+    
+    <para>There are various ways of using an Internet (or email)
+      connection to stay up-to-date with any given area of the &os;
+      project sources, or all areas, depending on what interests you.  The
+      primary services we offer are <link linkend="anoncvs">Anonymous
+      CVS</link>, <link linkend="cvsup">CVSup</link>, and <link
+      linkend="ctm">CTM</link>.</para>
+
+    <warning>
+      <para>While it is possible to update only parts of your source tree,
+        the only supported update procedure is to update the entire tree
+        and recompile both userland (i.e., all the programs that run in
+        user space, such as those in <filename>/bin</filename> and
+        <filename>/sbin</filename>) and kernel sources.  Updating only part
+        of your source tree, only the kernel, or only userland will often
+        result in problems.  These problems may range from compile errors
+        to kernel panics or data corruption.</para>
+    </warning>
+
+    <indexterm>
+      <primary>CVS</primary>
+      <secondary>anonymous</secondary>
+    </indexterm>
+
+    <para><application>Anonymous CVS</application> and
+      <application>CVSup</application> use the <emphasis>pull</emphasis>
+      model of updating sources.  In the case of
+      <application>CVSup</application> the user (or a 
+      <command>cron</command> script) invokes
+      the <command>cvsup</command> program, and it interacts with a
+      <command>cvsupd</command> server somewhere to bring your files
+      up-to-date.  The updates you receive are up-to-the-minute and you
+      get them when, and only when, you want them.  You can easily
+      restrict your updates to the specific files or directories that are
+      of interest to you.  Updates are generated on the fly by the server,
+      according to what you have and what you want to have.
+      <application>Anonymous CVS</application> is quite a bit more
+      simplistic than <application>CVSup</application> in that it is just an extension to
+      <application>CVS</application> which allows it to pull changes
+      directly from a remote CVS repository.
+      <application>CVSup</application> can do this far more efficiently,
+      but <application>Anonymous CVS</application> is easier to
+      use.</para>
+
+    <indexterm>
+      <primary><application>CTM</application></primary>
+    </indexterm>
+    <para><application>CTM</application>, on the other hand, does not
+      interactively compare the sources you have with those on the master
+      archive or otherwise pull them across.  Instead, a script which
+      identifies changes in files since its previous run is executed
+      several times a day on the master CTM machine, any detected changes
+      being compressed, stamped with a sequence-number and encoded for
+      transmission over email (in printable ASCII only).  Once received,
+      these <quote>CTM deltas</quote> can then be handed to the
+      &man.ctm.rmail.1; utility which will automatically decode, verify
+      and apply the changes to the user's copy of the sources.  This
+      process is far more efficient than <application>CVSup</application>,
+      and places less strain on our server resources since it is a
+      <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis>
+      model.</para>
+
+    <para>There are other trade-offs, of course.  If you inadvertently
+      wipe out portions of your archive, <application>CVSup</application>
+      will detect and rebuild the damaged portions for you.
+      <application>CTM</application> will not do this, and if you wipe some
+      portion of your source tree out (and do not have it backed up) then
+      you will have to start from scratch (from the most recent CVS
+      <quote>base delta</quote>) and rebuild it all with <application>CTM</application> or, with
+      <application>Anonymous CVS</application>, simply delete the bad bits and resync.</para>
+  </sect1>
+
+  <sect1 id="makeworld">
+    <title>Rebuilding <quote>world</quote></title>
+
+    <indexterm>
+      <primary>Rebuilding <quote>world</quote></primary>
+    </indexterm>
+    <para>Once you have synchronized your local source tree against a
+      particular version of &os; (&os.stable;, &os.current;, and so on)
+      you can then use the source
+      tree to rebuild the system.</para>
+
+    <warning>
+      <title>Make a Backup</title>
+
+      <para>It cannot be stressed enough how important it is to make a
+	backup of your system <emphasis>before</emphasis> you do this.
+	While rebuilding the world is (as long as you follow these
+	instructions) an easy task to do, there will inevitably be times
+	when you make mistakes, or when mistakes made by others in the
+	source tree render your system unbootable.</para>
+
+      <para>Make sure you have taken a backup.  And have a fixit floppy or
+	bootable CD at
+	hand.  You will probably never have to use it, but it is better to be
+	safe than sorry!</para>
+    </warning>
+
+    <warning>
+      <title>Subscribe to the Right Mailing List</title>
+
+      <indexterm><primary>mailing list</primary></indexterm>
+      <para>The &os.stable; and &os.current; branches are, by their
+	nature, <emphasis>in development</emphasis>.  People that
+	contribute to &os; are human, and mistakes occasionally
+	happen.</para>
+
+      <para>Sometimes these mistakes can be quite harmless, just causing
+	your system to print a new diagnostic warning.  Or the change may
+	be catastrophic, and render your system unbootable or destroy your
+	file systems (or worse).</para>
+
+      <para>If problems like these occur, a <quote>heads up</quote> is
+        posted to the appropriate mailing list, explaining the nature of
+	the problem and which systems it affects.  And an <quote>all
+	clear</quote> announcement is posted when the problem has been
+	solved.</para>
+
+      <para>If you try to track &os.stable; or &os.current; and do
+	not read the &a.stable; or the
+	&a.current; respectively, then you are
+	asking for trouble.</para>
+    </warning>
+
+    <warning>
+      <title>Do not use <command>make world</command></title>
+
+      <para>A lot of older documentation recommends using
+	<command>make world</command> for this.  Doing that skips
+	some important steps and should only be used if you are
+	sure of what you are doing.  For almost all circumstances
+	<command>make world</command> is the wrong thing to do, and
+	the procedure described here should be used instead.</para>
+    </warning>
+
+    <sect2>
+      <title>The Canonical Way to Update Your System</title>
+
+      <para>To update your system, you should check
+	<filename>/usr/src/UPDATING</filename> for any pre-buildworld steps
+	necessary for your version of the sources and then use the following
+	procedure:</para>
+
+      <screen>&prompt.root; <userinput>make buildworld</userinput>
+&prompt.root; <userinput>make buildkernel</userinput>
+&prompt.root; <userinput>make installkernel</userinput>
+&prompt.root; <userinput>reboot</userinput></screen>
+
+      <note>
+	<para>There are a few rare cases when an extra run of
+	  <command>mergemaster -p</command> is needed before the
+	  <maketarget>buildworld</maketarget> step.  These are
+	  described in <filename>UPDATING</filename>.  In general,
+	  though, you can safely omit this step if you are not
+	  updating across one or more major &os; versions.</para>
+      </note>
+
+      <para>After <maketarget>installkernel</maketarget> finishes
+	successfully, you should boot in single user mode
+	(i.e.&nbsp;using <command>boot -s</command> from the loader
+	prompt).  Then run:</para>
+
+      <screen>&prompt.root; <userinput>mergemaster -p</userinput>
+&prompt.root; <userinput>make installworld</userinput>
+&prompt.root; <userinput>mergemaster</userinput>
+&prompt.root; <userinput>reboot</userinput></screen>
+
+      <warning>
+	<title>Read Further Explanations</title>
+
+	<para>The sequence described above is only a short resume to
+	  help you getting started.  You should however read the
+	  following sections to clearly understand each step, especially
+	  if you want to use a custom kernel configuration.</para>
+      </warning>
+    </sect2>
+
+    <sect2>
+      <title>Read <filename>/usr/src/UPDATING</filename></title>
+
+      <para>Before you do anything else, read
+	<filename>/usr/src/UPDATING</filename> (or the equivalent file
+	wherever you have a copy of the source code).  This file should
+	contain important information about problems you might encounter, or
+	specify the order in which you might have to run certain commands.
+	If <filename>UPDATING</filename> contradicts something you read here,
+	<filename>UPDATING</filename> takes precedence.</para>
+
+      <important>
+	<para>Reading <filename>UPDATING</filename> is not an acceptable
+	  substitute for subscribing to the correct mailing list, as described 
+	  previously.  The two requirements are complementary, not
+	  exclusive.</para>
+      </important>
+    </sect2>
+
+    <sect2>
+      <title>Check <filename>/etc/make.conf</filename></title>
+      <indexterm>
+        <primary><filename>make.conf</filename></primary>
+      </indexterm>
+
+      <para>Examine the files
+	<filename>/usr/share/examples/etc/make.conf</filename>
+	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>NO_PROFILE</makevar> lines found in
+	<filename>/usr/share/examples/etc/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
+        <command>make installworld</command> has expected certain usernames or groups
+	to exist.  When performing an upgrade it is likely that these
+	users or groups did not exist. This caused problems when upgrading.
+	In some cases <command>make buildworld</command> will check to see if
+	these users or groups exist.</para>
+
+      <para>An 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 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,
+        select the <quote>single user</quote> option.  The system will then boot
+	single user.  At the shell prompt you should then run:</para>
+
+      <screen>&prompt.root; <userinput>fsck -p</userinput>
+&prompt.root; <userinput>mount -u /</userinput>
+&prompt.root; <userinput>mount -a -t ufs</userinput>
+&prompt.root; <userinput>swapon -a</userinput></screen>
+
+      <para>This checks the file systems, remounts <filename>/</filename>
+	read/write, mounts all the other UFS file systems referenced in
+	<filename>/etc/fstab</filename> and then turns swapping on.</para>
+
+
+        <note>
+          <para>If your CMOS clock is set to local time and not to GMT
+	    (this is true if the output of the &man.date.1; command
+	    does not show the correct time and zone),
+            you may also need to run the following command:</para>
+<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
+
+          <para>This will make sure that your local time-zone settings
+            get set up correctly &mdash; without this, you may later run into some
+            problems.
+          </para>
+        </note>
+
+    </sect2>
+
+    <sect2>
+      <title>Remove <filename>/usr/obj</filename></title>
+
+      <para>As parts of the system are rebuilt they are placed in
+	directories which (by default) go under
+	<filename>/usr/obj</filename>.  The directories shadow those under
+	<filename>/usr/src</filename>.</para>
+
+      <para>You can speed up the <command>make buildworld</command> process, and
+	possibly save yourself some dependency headaches by removing this
+	directory as well.</para>
+
+      <para>Some files below <filename>/usr/obj</filename> may have the
+	immutable flag set (see &man.chflags.1; for more information)
+	which must be removed first.</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
+&prompt.root; <userinput>chflags -R noschg *</userinput>
+&prompt.root; <userinput>rm -rf *</userinput></screen>
+    </sect2>
+
+    <sect2 id="cutting-edge-compilebase">
+      <title>Recompile the Base System</title>
+
+      <sect3>
+	<title>Saving the Output</title>
+
+	<para>It is a good idea to save the output you get from running
+	  &man.make.1; to another file.  If something goes wrong you will
+	  have a copy of the error message.  While this might not help you
+	  in diagnosing what has gone wrong, it can help others if you post
+	  your problem to one of the &os; mailing lists.</para>
+
+	<para>The easiest way to do this is to use the &man.script.1;
+	  command, with a parameter that specifies the name of the file to
+	  save all output to.  You would do this immediately before
+	  rebuilding the world, and then type <userinput>exit</userinput>
+	  when the process has finished.</para>
+
+	<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
+Script started, output file is /var/tmp/mw.out	 
+&prompt.root; <userinput>make TARGET</userinput>
+<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>	  
+&prompt.root; <userinput>exit</userinput>
+Script done, &hellip;</screen>
+
+	<para>If you do this, <emphasis>do not</emphasis> save the output
+	  in <filename>/tmp</filename>.  This directory may be cleared
+	  next time you reboot.  A better place to store it is in
+	  <filename>/var/tmp</filename> (as in the previous example) or
+	  in <username>root</username>'s home directory.</para>
+      </sect3>
+
+      <sect3 id="make-buildworld">
+	<title>Compile the Base System</title>
+
+	<para>You must be in the <filename>/usr/src</filename>
+	  directory:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
+
+	<para>(unless, of course, your source code is elsewhere, in which
+	  case change to that directory instead).</para>
+	<indexterm><primary><command>make</command></primary></indexterm>
+
+	<para>To rebuild the world you use the &man.make.1; command.  This
+          command reads instructions from the <filename>Makefile</filename>,
+          which describes how the programs that comprise &os; should be
+          rebuilt, the order in which they should be built, and so on.</para>
+
+	<para>The general format of the command line you will type is as
+	  follows:</para>
+
+	<screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
+
+	<para>In this example, <option>-<replaceable>x</replaceable></option>
+	  is an option that you would pass to &man.make.1;.  See the
+	  &man.make.1; manual page for an example of the options you can
+	  pass.</para>
+
+	<para><option>-D<replaceable>VARIABLE</replaceable></option>
+	  passes a variable to the <filename>Makefile</filename>.  The
+	  behavior of the <filename>Makefile</filename> is controlled by
+	  these variables.  These are the same variables as are set in
+	  <filename>/etc/make.conf</filename>, and this provides another
+	  way of setting them.</para>
+
+	<screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
+
+	<para>is another way of specifying that profiled libraries should
+	  not be built, and corresponds with the</para>
+
+	<programlisting>NO_PROFILE=    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>Where <replaceable>target</replaceable> will be one of
+	  many build options.  The first target should always be
+	  <makevar>buildworld</makevar>.</para>
+
+	<para>As the names imply, <maketarget>buildworld</maketarget>
+	  builds a complete new tree under <filename>/usr/obj</filename>,
+	  and <maketarget>installworld</maketarget>, another target, installs this tree on
+	  the current machine.</para>
+
+	<para>Having separate options is very useful for two 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 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>
+      </sect3>
+      
+      <sect3>
+	<title>Timings</title>
+	<indexterm>
+	  <primary>rebuilding <quote>world</quote></primary>
+	  <secondary>timings</secondary>
+	</indexterm>
+
+        <para>Many factors influence the build time, but fairly recent
+          machines may only take a one or two hours to build
+          the &os.stable; tree, with no tricks or shortcuts used during the
+          process.  A &os.current; tree will take somewhat longer.</para>
+      </sect3>
+    </sect2>
+    
+    <sect2>
+      <title>Compile and Install a New Kernel</title>
+      <indexterm>
+        <primary>kernel</primary>
+	<secondary>compiling</secondary>
+      </indexterm>
+
+      <para>To take full advantage of your new system you should recompile the
+	kernel.  This is practically a necessity, as certain memory structures
+	may have changed, and programs like &man.ps.1; and &man.top.1; will
+	fail to work until the kernel and source code versions are the
+	same.</para>
+
+      <para>The simplest, safest way to do this is to build and install a
+	kernel based on <filename>GENERIC</filename>.  While
+	<filename>GENERIC</filename> may not have all the necessary devices
+	for your system, it should contain everything necessary to boot your
+	system back to single user mode.  This is a good test that the new
+	system works properly.  After booting from
+	<filename>GENERIC</filename> and verifying that your system works you
+	can then build a new kernel based on your normal kernel	configuration
+	file.</para>
+
+      <para>On &os; it is important to <link
+        linkend="make-buildworld">build world</link> before building a
+        new kernel.</para>
+
+      <note><para>If you want to build a custom kernel, and already have a configuration
+	file, just use <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>
+	like this:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput>
+&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
+      </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>
+    </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 id="make-installworld">
+      <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 -DNO_PROFILE buildworld</userinput></screen>
+
+	<para>you must install the results with:</para>
+
+	<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
+
+	<para>otherwise it would try to install profiled libraries that
+	  had not been built during the <command>make buildworld</command>
+	  phase.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Update Files Not Updated by <command>make installworld</command></title>
+      
+      <para>Remaking the world will not update certain directories (in
+	particular, <filename>/etc</filename>, <filename>/var</filename> and
+	<filename>/usr</filename>) with new or changed configuration files.</para>
+
+      <para>The simplest way to update these files is to use
+        &man.mergemaster.8;, though it is possible to do it manually
+        if you would prefer to do that.  Regardless of which way you
+	choose, be sure to make a backup of <filename>/etc</filename> in
+	case anything goes wrong.</para>
+
+    <sect3 id="mergemaster">
+      <sect3info>
+	<authorgroup>
+	  <author>
+	    <firstname>Tom</firstname>
+	    <surname>Rhodes</surname>
+	    <contrib>Contributed by </contrib>
+	  </author>
+	</authorgroup>
+      </sect3info>
+      <title><command>mergemaster</command></title>
+        <indexterm><primary><command>mergemaster</command></primary></indexterm>
+
+      <para>The &man.mergemaster.8; utility is a Bourne script that will
+        aid you in determining the differences between your configuration files
+        in <filename>/etc</filename>, and the configuration files in
+        the source tree <filename>/usr/src/etc</filename>. This is
+        the recommended solution for keeping the system configuration files up to date
+        with those located in the source tree.</para>
+
+      <para>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 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="cutting-edge-rebooting">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="cutting-edge-rebooting">
+      <title>Rebooting</title>
+      
+      <para>You are now done.  After you have verified that everything appears
+	to be in the right place you can reboot the system.  A simple
+	&man.shutdown.8; should do it:</para>
+
+      <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Finished</title>
+      
+      <para>You should now have successfully upgraded your &os; system.
+	Congratulations.</para>
+      
+      <para>If things went slightly wrong, it is easy to rebuild a particular
+        piece of the system.  For example, if you accidentally deleted
+        <filename>/etc/magic</filename> as part of the upgrade or merge of
+        <filename>/etc</filename>, the &man.file.1; command will stop working.
+        In this case, the fix would be to run:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
+&prompt.root; <userinput>make all install</userinput></screen>
+    </sect2>    
+    
+    <sect2>
+      <title>Questions</title>
+
+      <qandaset>
+	<qandaentry>
+	  <question>
+	    <para>Do I need to re-make the world for every change?</para>
+	  </question>
+
+	  <answer>
+            <para>There is no easy answer to this one, as it depends on the
+	      nature of the change.  For example, if you just ran <application>CVSup</application>, and
+	      it has shown the following files as being updated:</para>
+      
+	    <screen><filename>src/games/cribbage/instr.c</filename>
+<filename>src/games/sail/pl_main.c</filename>
+<filename>src/release/sysinstall/config.c</filename>
+<filename>src/release/sysinstall/media.c</filename>
+<filename>src/share/mk/bsd.port.mk</filename></screen>
+
+	    <para>it probably is not worth rebuilding the entire world.
+	      You could just go to the appropriate sub-directories and
+	      <command>make all install</command>, and that's about it.  But
+	      if something major changed, for example
+	      <filename>src/lib/libc/stdlib</filename> then you should either
+	      re-make the world, or at least those parts of it that are
+	      statically linked (as well as anything else you might have added
+	      that is statically linked).</para>
+      
+	    <para>At the end of the day, it is your call.  You might be happy
+	      re-making the world every fortnight say, and let changes
+	      accumulate over that fortnight.  Or you might want to re-make
+	      just those things that have changed, and be confident you can
+	      spot all the dependencies.</para>
+      
+	    <para>And, of course, this all depends on how often you want to
+	      upgrade, and whether you are tracking &os.stable; or
+	      &os.current;.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>My compile failed with lots of signal 11 (or other signal
+	      number) errors.  What has happened?</para>
+	  </question>
+    <indexterm><primary>signal 11</primary></indexterm>
+
+	  <answer>
+
+	    <para>This is normally indicative of hardware problems.
+	      (Re)making the world is an effective way to stress test your
+	      hardware, and will frequently throw up memory problems.  These
+	      normally manifest themselves as the compiler mysteriously dying
+	      on receipt of strange signals.</para>
+      
+	    <para>A sure indicator of this is if you can restart the make and
+	      it dies at a different point in the process.</para>
+      
+	    <para>In this instance there is little you can do except start
+	      swapping around the components in your machine to determine
+	      which one is failing.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>Can I remove <filename>/usr/obj</filename> when I have
+	      finished?</para>
+	  </question>
+	  
+	  <answer>
+	    <para>The short answer is yes.</para>
+      
+	    <para><filename>/usr/obj</filename> contains all the object files
+	      that were produced during the compilation phase.  Normally, one
+	      of the first steps in the <command>make buildworld</command> process is to
+	      remove this directory and start afresh.  In this case, keeping
+	      <filename>/usr/obj</filename> around after you have finished
+	      makes little sense, and will free up a large chunk of disk space
+	      (currently about 340&nbsp;MB).</para>
+      
+	    <para>However, if you know what you are doing you can have
+	      <command>make buildworld</command> skip this step.  This will make subsequent
+	      builds run much faster, since most of sources will not need to
+	      be recompiled.  The flip side of this is that subtle dependency
+	      problems can creep in, causing your build to fail in odd ways.
+	      This frequently generates noise on the &os; mailing lists,
+	      when one person complains that their build has failed, not
+	      realizing that it is because they have tried to cut
+	      corners.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>Can interrupted builds be resumed?</para>
+	  </question>
+
+	  <answer>
+	    <para>This depends on how far through the process you got before
+	      you found a problem.</para>
+
+	    <para><emphasis>In general</emphasis> (and this is not a hard and
+	      fast rule) the <command>make buildworld</command> process builds new
+	      copies of essential tools (such as &man.gcc.1;, and
+	      &man.make.1;) and the system libraries.  These tools and
+	      libraries are then installed.  The new tools and libraries are
+	      then used to rebuild themselves, and are installed again. The
+	      entire system (now including regular user programs, such as
+		&man.ls.1; or &man.grep.1;) is then rebuilt with the new
+	      system files.</para>
+
+	    <para>If you are at the last stage, and you know it (because you
+	      have looked through the output that you were storing) then you
+	      can (fairly safely) do:</para>
+
+	    <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
+&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
+
+	    <para>This will not undo the work of the previous
+	      <command>make buildworld</command>.</para>
+
+	    <para>If you see the message:</para>
+
+	      <screen>--------------------------------------------------------------
+Building everything..
+--------------------------------------------------------------</screen>
+
+	    <para>in the <command>make buildworld</command> output then it is
+	      probably fairly safe to do so.</para>
+	    
+	    <para>If you do not see that message, or you are not sure, then it
+	      is always better to be safe than sorry, and restart the build
+	      from scratch.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>How can I speed up making the world?</para>
+          </question>
+
+          <answer>
+	    <itemizedlist>
+	      <listitem>
+		<para>Run in single user mode.</para>
+	      </listitem>
+	      
+	      <listitem>
+		<para>Put the <filename>/usr/src</filename> and
+		  <filename>/usr/obj</filename> directories on separate
+		  file systems held on separate disks.  If possible, put these
+		  disks on separate disk controllers.</para>
+	      </listitem>
+	      
+	      <listitem>
+		<para>Better still, put these file systems across multiple
+		  disks using the &man.ccd.4; (concatenated disk
+		  driver) device.</para>
+	      </listitem>
+	      
+	      <listitem>
+		<para>Turn off profiling (set <quote>NO_PROFILE=true</quote> in
+		  <filename>/etc/make.conf</filename>).  You almost certainly
+		  do not need it.</para>
+	      </listitem>
+	      
+	      <listitem>
+		<para>Also in <filename>/etc/make.conf</filename>, set
+		  <makevar>CFLAGS</makevar> to something like <option>-O
+		  -pipe</option>.  The optimization <option>-O2</option> is much
+		  slower, and the optimization difference between
+		  <option>-O</option> and <option>-O2</option> is normally
+		  negligible.  <option>-pipe</option> lets the compiler use
+		  pipes rather than temporary files for communication, which
+		  saves disk access (at the expense of memory).</para>
+	      </listitem>
+	      
+	      <listitem>
+		<para>Pass the <option>-j<replaceable>n</replaceable></option> option to &man.make.1; to
+		  run multiple processes in parallel.  This usually helps 
+		  regardless of whether you have a single or a multi processor
+		  machine.</para>
+	      </listitem>
+	      
+	      <listitem><para>The file system holding
+		  <filename>/usr/src</filename> can be mounted (or remounted)
+		  with the <option>noatime</option> option.  This prevents the
+		  file system from recording the file access time.  You probably
+		  do not need this information anyway.</para>
+		  
+		  <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
+		  
+		  <warning>
+		    <para>The example assumes <filename>/usr/src</filename> is
+		      on its own file system.  If it is not (if it is a part of
+		      <filename>/usr</filename> for example) then you will
+		      need to use that file system mount point, and not
+		      <filename>/usr/src</filename>.</para>
+		  </warning>
+	      </listitem>
+	      
+	      <listitem>
+		<para>The file system holding <filename>/usr/obj</filename> can
+		  be mounted (or remounted) with the <option>async</option>
+		  option.  This causes disk writes to happen asynchronously.
+		  In other words, the write completes immediately, and the
+		  data is written to the disk a few seconds later.  This
+		  allows writes to be clustered together, and can be a
+		  dramatic performance boost.</para>
+
+		<warning>
+		  <para>Keep in mind that this option makes your file system
+		    more fragile.  With this option there is an increased
+		    chance that, should power fail, the file system will be in
+		    an unrecoverable state when the machine restarts.</para>
+	   
+		  <para>If <filename>/usr/obj</filename> is the only thing on
+		    this file system then it is not a problem.  If you have
+		    other, valuable data on the same file system then ensure
+		    your backups are fresh before you enable this
+		    option.</para>
+		</warning>
+		
+		<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
+		
+		<warning>
+		  <para>As above, if <filename>/usr/obj</filename> is not on
+		    its own file system, replace it in the example with the
+		    name of the appropriate mount point.</para>
+		</warning>
+	      </listitem>
+	    </itemizedlist>
+	  </answer>
+	</qandaentry>
+
+        <qandaentry>
+          <question>
+            <para>What do I do if something goes wrong?</para>
+          </question>
+
+          <answer>
+            <para>Make absolutely sure your environment has no
+              extraneous cruft from earlier builds.  This is simple
+              enough.</para>
+
+            <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
+&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
+&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make cleandir</userinput>
+&prompt.root; <userinput>make cleandir</userinput></screen>
+
+            <para>Yes, <command>make cleandir</command> really should
+              be run twice.</para>
+
+            <para>Then restart the whole process, starting
+              with <command>make buildworld</command>.</para>
+
+            <para>If you still have problems, send the error and the
+              output of <command>uname -a</command> to &a.questions;.
+              Be prepared to answer other questions about your
+              setup!</para>
+          </answer>
+        </qandaentry>
+      </qandaset>
+    </sect2>
+  </sect1>
+
+  <sect1 id="small-lan">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Mike</firstname>
+	  <surname>Meyer</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Tracking for Multiple Machines</title>
+    <indexterm>
+      <primary>NFS</primary>
+      <secondary>installing multiple machines</secondary>
+    </indexterm>
+    
+    <para>If you have multiple machines that you want to track the
+      same source tree, then having all of them download sources and
+      rebuild everything seems like a waste of resources: disk space,
+      network bandwidth, and CPU cycles.  It is, and the solution is
+      to have one machine do most of the work, while the rest of the
+      machines mount that work via NFS.  This section outlines a
+      method of doing so.</para>
+
+    <sect2 id="small-lan-preliminaries">
+      <title>Preliminaries</title>
+
+      <para>First, identify a set of machines that is going to run
+	the same set of binaries, which we will call a
+	<emphasis>build set</emphasis>.  Each machine can have a
+	custom kernel, but they will be running the same userland
+	binaries.  From that set, choose a machine to be the
+	<emphasis>build machine</emphasis>.  It is going to be the
+	machine that the world and kernel are built on. Ideally, it
+	should be a fast machine that has sufficient spare CPU to
+	run <command>make buildworld</command> and
+	<command>make buildkernel</command>.  You will also want to
+	choose a machine to be the <emphasis>test
+	machine</emphasis>, which will test software updates before they
+	are put into production.  This <emphasis>must</emphasis> be a
+	machine that you can afford to have down for an extended
+	period of time.  It can be the build machine, but need not be.</para>
+
+      <para>All the machines in this build set need to mount
+	<filename>/usr/obj</filename> and
+	<filename>/usr/src</filename> from the same machine, and at
+	the same point.  Ideally, those are on two different drives
+	on the build machine, but they can be NFS mounted on that machine
+	as well.  If you have multiple build sets,
+	<filename>/usr/src</filename> should be on one build machine, and
+	NFS mounted on the rest.</para>
+	  
+      <para>Finally make sure that
+	<filename>/etc/make.conf</filename> on all the machines in
+	the build set agrees with the build machine.  That means that
+	the build machine must build all the parts of the base
+	system that any machine in the build set is going to
+	install.  Also, each build machine should have its kernel
+	name set with <makevar>KERNCONF</makevar> in
+	<filename>/etc/make.conf</filename>, and the build machine
+	should list them all in <makevar>KERNCONF</makevar>, listing
+	its own kernel first.  The build machine must have the kernel
+	configuration files for each machine in
+	<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>
+	if it is going to build their kernels.</para>
+    </sect2>
+
+    <sect2>
+      <title>The Base System</title>
+
+      <para>Now that all that is done, you are ready to build
+	everything.  Build the kernel and world as described in <xref
+	linkend="make-buildworld"> on the build machine,
+	but do not install anything.  After the build has finished, go
+	to the test machine, and install the kernel you just
+	built.  If this machine mounts <filename>/usr/src</filename>
+	and <filename>/usr/obj</filename> via NFS, when you reboot
+	to single user you will need to enable the network and mount
+	them.  The easiest way to do this is to boot to multi-user,
+	then run <command>shutdown now</command> to go to single user
+	mode.  Once there, you can install the new kernel and world and run
+	<command>mergemaster</command> just as you normally would.  When
+	done, reboot to return to normal multi-user operations for this
+	machine.</para>
+
+      <para>After you are certain that everything on the test
+	machine is working properly, use the same procedure to
+	install the new software on each of the other machines in
+	the build set.</para>
+    </sect2>
+
+    <sect2>
+      <title>Ports</title>
+
+      <para>The same ideas can be used for the ports tree.  The first
+	critical step is mounting <filename>/usr/ports</filename> from
+	the same machine to all the machines in the build set.  You can
+	then set up <filename>/etc/make.conf</filename> properly to share
+	distfiles.  You should set <makevar>DISTDIR</makevar> to a
+	common shared directory that is writable by whichever user
+	<username>root</username> is mapped to by your NFS mounts.  Each
+	machine should set <makevar>WRKDIRPREFIX</makevar> to a
+	local build directory.  Finally, if you are going to be
+	building and distributing packages, you should set
+	<makevar>PACKAGES</makevar> to a directory similar to
+	<makevar>DISTDIR</makevar>.</para> 
+    </sect2>
+  </sect1>
+</chapter>
+<!-- 
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->
+
diff --git a/pl_PL.ISO8859-2/books/handbook/desktop/Makefile b/pl_PL.ISO8859-2/books/handbook/desktop/Makefile
new file mode 100644
index 0000000000..6dd222f080
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/desktop/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	desktop/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/desktop/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/desktop/chapter.sgml
new file mode 100644
index 0000000000..e317670c06
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/desktop/chapter.sgml
@@ -0,0 +1,1117 @@
+<!--
+     The FreeBSD Documentation Project
+     $FreeBSD$
+-->
+
+<chapter id="desktop">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+        <firstname>Christophe</firstname>
+        <surname>Juniet</surname>
+        <contrib>Contributed by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Desktop Applications</title>
+
+  <sect1 id="desktop-synopsis">
+    <title>Synopsis</title>
+
+    <para>FreeBSD can run a wide variety of desktop applications, such
+      as browsers and word processors.  Most of these are available as
+      packages or can be automatically built from the ports
+      collection.  Many new users expect to find these kinds of
+      applications on their desktop.  This chapter will show you how
+      to install some popular desktop applications effortlessly,
+      either from their packages or from the Ports Collection.</para>
+
+    <para>Note that when installing programs from the ports, they are
+      compiled from source.  This can take a very long time, depending
+      on what you are compiling and the processing power of your
+      machine(s).  If building from source takes a prohibitively long
+      amount of time for you, you can install most of the programs of
+      the Ports Collection from pre-built packages.</para>
+
+    <para>As FreeBSD features Linux binary compatibility, many
+      applications originally developed for Linux are available for
+      your desktop.  It is strongly recommended that you read
+      <xref linkend="linuxemu"> before installing any of the Linux
+      applications.  Many of the ports using the Linux binary
+      compatibility start with <quote>linux-</quote>.  Remember this
+      when you search for a particular port, for instance with
+      &man.whereis.1;.  In the following text, it is assumed that you
+      have enabled Linux binary compatibility before installing any of
+      the Linux applications.</para>
+
+    <para>Here are the categories covered by this chapter:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Browsers (such as <application>Mozilla</application>,
+          <application>Opera</application>,
+          <application>Firefox</application>,
+	  <application>Konqueror</application>)</para>
+      </listitem>
+
+      <listitem>
+        <para>Productivity (such as
+          <application>KOffice</application>,
+          <application>AbiWord</application>,
+          <application>The GIMP</application>,
+          <application>OpenOffice.org</application>)</para>
+      </listitem>
+
+      <listitem>
+        <para>Document Viewers (such as <application>&acrobat.reader;</application>,
+          <application>gv</application>,
+          <application>Xpdf</application>,
+          <application>GQview</application>)</para>
+      </listitem>
+
+      <listitem>
+        <para>Finance (such as
+          <application>GnuCash</application>,
+          <application>Gnumeric</application>,
+          <application>Abacus</application>)</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Know how to install additional third-party software
+          (<xref linkend="ports">).</para>
+      </listitem>
+
+      <listitem>
+        <para>Know how to install additional Linux software
+	  (<xref linkend="linuxemu">).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>For information on how to get a multimedia environment, read
+      <xref linkend="multimedia">.  If you want to set up and use
+      electronic mail, please refer to <xref linkend="mail">.</para>
+  </sect1>
+
+  <sect1 id="desktop-browsers">
+    <title>Browsers</title>
+
+    <indexterm>
+      <primary>browsers</primary>
+      <secondary>web</secondary>
+    </indexterm>
+
+    <para>FreeBSD does not come with a particular browser
+      pre-installed.  Instead, the
+      <ulink url="http://www.FreeBSD.org/ports/www.html">www</ulink>
+      directory of the Ports Collection contains a lot of browsers
+      ready to be installed.  If you do not have time to compile
+      everything (this can take a very long time in some cases) many
+      of them are available as packages.</para>
+
+    <para><application>KDE</application> and
+      <application>GNOME</application> already provide HTML browsers.
+      Please refer to <xref linkend="x11-wm"> for more information on
+      how to set up these complete desktops.</para>
+
+    <para>If you are looking for light-weight browsers, you should
+      investigate the Ports Collection for
+      <filename role="package">www/dillo</filename>,
+      <filename role="package">www/links</filename>, or
+      <filename role="package">www/w3m</filename>.</para>
+
+    <para>This section covers these applications:</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="4">
+        <thead>
+          <row>
+            <entry>Application Name</entry>
+            <entry>Resources Needed</entry>
+            <entry>Installation from Ports</entry>
+            <entry>Major Dependencies</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><application>Mozilla</application></entry>
+            <entry>heavy</entry>
+            <entry>heavy</entry>
+            <entry><application>Gtk+</application></entry>
+          </row>
+
+          <row>
+            <entry><application>Opera</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+	    <entry>FreeBSD and Linux versions available.  The Linux
+	      version depends on the Linux Binary Compatibility and
+	      <application>linux-openmotif</application>.</entry>
+          </row>
+
+          <row>
+            <entry><application>Firefox</application></entry>
+            <entry>medium</entry>
+            <entry>heavy</entry>
+            <entry><application>Gtk+</application></entry>
+          </row>
+          
+	  <row>
+	    <entry><application>Konqueror</application></entry>
+	    <entry>medium</entry>
+	    <entry>heavy</entry>
+	    <entry><application>KDE</application> Libraries</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <sect2>
+      <title>Mozilla</title>
+      <indexterm>
+	<primary><application>Mozilla</application></primary>
+      </indexterm>
+
+      <para><application>Mozilla</application> is a modern,
+        stable browser that is fully ported to FreeBSD.  It features a very
+        standards-compliant HTML display engine.  It provides a mail
+        and news reader.  It even has a HTML composer if you plan to
+        write some web pages yourself.  Users of
+        <application>&netscape;</application> will recognize the
+        similarities with <application>Communicator</application>
+        suite, as both browsers shared the same basis.</para>
+
+      <para>On slow machines, with a CPU speed less than 233MHz or
+        with less than 64MB of RAM, <application>Mozilla</application>
+        can be too resource-consuming to be fully usable.  You may
+        want to look at the <application>Opera</application> browser
+        instead, described a little later in this chapter.</para>
+
+      <para>If you cannot or do not want to compile
+        <application>Mozilla</application> for any reason, the FreeBSD
+        GNOME team has already done this for you.  Just install the
+        package from the network by:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r mozilla</userinput></screen>
+
+      <para>If the package is not available, and you have enough time
+        and disk space, you can get the source for
+        <application>Mozilla</application>, compile it and install it
+        on your system.  This is accomplished by:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/www/mozilla</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <para>The <application>Mozilla</application> port ensures a
+        correct initialization by running the chrome registry setup
+        with <username>root</username> privileges.  However, if you
+        want to fetch some add-ons like mouse gestures, you must run
+        <application>Mozilla</application> as
+        <username>root</username> to get them properly
+        installed.</para>
+
+      <para>Once you have completed the installation of
+        <application>Mozilla</application>, you do not need to be
+        <username>root</username> any longer.  You can start
+        <application>Mozilla</application> as a browser by typing:</para>
+
+      <screen>&prompt.user; <userinput>mozilla</userinput></screen>
+
+      <para>You can start it directly as a mail and news reader as
+        shown below:</para>
+
+      <screen>&prompt.user; <userinput>mozilla -mail</userinput></screen>
+    </sect2>
+    
+    <sect2>
+      <title>Firefox</title>
+      <indexterm>
+	<primary><application>Firefox</application></primary>
+      </indexterm>
+
+      <para><application>Firefox</application> is the next-generation
+         browser based on the <application>Mozilla</application>
+         codebase. <application>Mozilla</application> is a complete
+         suite of applications, such as a browser, a mail client, a chat
+         client and much more. <application>Firefox</application> is
+         just a browser, which makes it smaller and faster.</para>
+
+      <para>Install the package by typing:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r firefox</userinput></screen>
+
+      <para>You can also use the Ports Collection if you
+         prefer to compile from source code:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/www/firefox</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+
+    <sect2 id="moz-java-plugin">
+      <title>Firefox, Mozilla and &java; plugin</title>
+
+      <note>
+	<para>In this section and in the next one, we assume you
+	  already installed <application>Firefox</application> or
+	  <application>Mozilla</application>.</para>
+      </note>
+
+      <para>The &os; Foundation has a license with Sun Microsystems to
+	distribute &os; binaries for the Java Runtime Environment
+	(&jre;) and Java Development Kit (&jdk;).  Binary packages for
+	&os; are available on the <ulink
+	url="http://www.freebsdfoundation.org/downloads/java.shtml">&os;
+	Foundation</ulink> web site.</para>
+
+      <para>To add &java; support to
+	<application>Firefox</application> or
+	<application>Mozilla</application>, you have to install, at
+	first, the <filename
+	role="package">java/javavmwrapper</filename> port.  Then,
+	download the <application>Diablo &jre;</application> package
+	from <ulink
+	url="http://www.freebsdfoundation.org/downloads/java.shtml"></ulink>,
+	and install it with &man.pkg.add.1;.</para>
+
+      <para>Start your browser, enter
+	<literal>about:plugins</literal> in the location bar and press
+	<keycap>Enter</keycap>.  A page regarding installed plugins
+	will be displayed, the <application>&java;</application>
+	plugin should be listed there now.</para>
+
+    </sect2>
+
+    <sect2 id="moz-flash-plugin">
+
+      <title>Firefox, Mozilla and &macromedia; &flash; plugin</title>
+
+      <para>&macromedia; &flash; plugin is not available for &os;. However,
+	a software layer (wrapper) for running the Linux version of the plugin
+	exists.  This wrapper also supports &adobe; &acrobat; plugin,
+	RealPlayer plugin and more.</para>
+
+      <para>Install the <filename role="package">www/linuxpluginwrapper</filename>
+	port.  This port requires
+	<filename role="package">emulators/linux_base</filename> which is a
+	large port.  Follow the instructions displayed by the port to set up
+	your <filename>/etc/libmap.conf</filename> correctly!  Example
+	configurations are installed into
+	<filename>/usr/local/share/examples/linuxpluginwrapper/</filename>
+	directory.</para>
+
+      <para>The next step is to install the <filename
+	role="package">www/linux-flashplugin7</filename> port.  Once
+	the plugin is installed, start your browser, enter
+	<literal>about:plugins</literal> in the location bar and press
+	<keycap>Enter</keycap>.
+	A list should appear with all the currently
+	available plugins.</para>
+
+      <para>If the &flash; plugin is not listed, this is, most of time,
+	caused by a missing symlink.  As <username>root</username>,
+	run the following commands:</para>
+
+      <screen>&prompt.root; <userinput>ln -s /usr/X11R6/lib/linux-flashplugin7/libflashplayer.so \
+  /usr/X11R6/lib/browser_plugins/</userinput>
+&prompt.root; <userinput>ln -s /usr/X11R6/lib/linux-flashplugin7/flashplayer.xpt \
+  /usr/X11R6/lib/browser_plugins/</userinput></screen>
+
+      <para>If you restart your browser the plugin should now appears
+	in the previously mentioned list.  Your browser may also crash
+	when playing some &flash; animations, in this case a patch
+	can help you:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>fetch http://people.FreeBSD.org/~nork/rtld_dlsym_hack.diff</userinput>
+&prompt.root; <userinput>patch < rtld_dlsym_hack.diff</userinput>
+&prompt.root; <userinput>cd libexec/rtld-elf/</userinput>
+&prompt.root; <userinput>make clean</userinput>
+&prompt.root; <userinput>make obj</userinput>
+&prompt.root; <userinput>make depend</userinput>
+&prompt.root; <userinput>make && make install</userinput></screen>
+
+      <para>Then reboot your machine.</para>
+
+      <note>
+	<para>The <application>linuxpluginwrapper</application> only works on
+	  the &i386; system architecture.</para>
+      </note>
+
+    </sect2>
+
+    <sect2>
+      <title>Opera</title>
+      <indexterm>
+	<primary><application>Opera</application></primary>
+      </indexterm>
+
+      <para><application>Opera</application> is a
+        full-featured and standards-compliant browser.  It also
+        comes with a built-in mail and news reader, an IRC client,
+        an RSS/Atom feeds reader and much more.  Despite this, 
+        <application>Opera</application> is relatively lightweight
+        and very fast. It comes in two flavors: a <quote>native</quote> 
+        FreeBSD version and a version that runs under Linux 
+        emulation.</para>
+
+      <para>To browse the Web with the FreeBSD version of <application>Opera</application>,
+        install the package:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r opera</userinput></screen>
+
+      <para>Some FTP sites do not have all the packages, but the same
+        result can be obtained with the Ports Collection by
+        typing:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/www/opera</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <para>To install the Linux version of
+	<application>Opera</application>, substitute
+	<literal>linux-opera</literal> in place of
+	<literal>opera</literal> in the examples above.  The Linux
+	version is useful in situations requiring the use of plug-ins
+	that are only available for Linux, such as <application>Adobe
+	&acrobat.reader;</application>.  In all other respects, the
+	FreeBSD and Linux versions appear to be functionally
+	identical.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Konqueror</title>
+      <indexterm>
+        <primary><application>Konqueror</application></primary>
+      </indexterm>
+
+      <para><application>Konqueror</application> is part of
+	<application>KDE</application> but it can also be used outside
+       	of <application>KDE</application> by installing
+	<filename role="package">x11/kdebase3</filename>.
+	<application>Konqueror</application> is much more than a browser,
+	it is also a file manager and a multimedia viewer.</para>
+
+      <para><application>Konqueror</application> also comes with a set of plugins,
+	available in <filename role="package">misc/konq-plugins</filename>.</para>
+
+      <para><application>Konqueror</application> also supports <application>&flash;</application> and a How To
+	is available at <ulink url="http://freebsd.kde.org/howto.php"></ulink>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="desktop-productivity">
+    <title>Productivity</title>
+
+    <para>When it comes to productivity, new users often look for a
+       good office suite or a friendly word processor.  While some
+       <link linkend="x11-wm">desktop environments</link> like
+       <application>KDE</application> already provide an office suite,
+       there is no default application.  FreeBSD provides all that is
+       needed, regardless of your desktop environment.</para>
+
+    <para>This section covers these applications:</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="4">
+        <thead>
+          <row>
+            <entry>Application Name</entry>
+            <entry>Resources Needed</entry>
+            <entry>Installation from Ports</entry>
+            <entry>Major Dependencies</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><application>KOffice</application></entry>
+            <entry>light</entry>
+            <entry>heavy</entry>
+            <entry><application>KDE</application></entry>
+          </row>
+
+          <row>
+            <entry><application>AbiWord</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+            <entry><application>Gtk+</application> or <application>GNOME</application></entry>
+          </row>
+
+          <row>
+            <entry><application>The Gimp</application></entry>
+            <entry>light</entry>
+            <entry>heavy</entry>
+            <entry><application>Gtk+</application></entry>
+          </row>
+
+          <row>
+            <entry><application>OpenOffice.org</application></entry>
+            <entry>heavy</entry>
+            <entry>huge</entry>
+            <entry><application>&jdk; 1.4</application>, <application>Mozilla</application></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+   
+    <sect2>
+      <title>KOffice</title>
+      <indexterm>
+	<primary><application>KOffice</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>office suite</primary>
+	<secondary><application>KOffice</application></secondary>
+      </indexterm>
+
+      <para>The KDE community has provided its desktop environment
+        with an office suite which can be used outside
+        <application>KDE</application>.  It includes the four standard
+        components that can be found in other office suites.
+        <application>KWord</application> is the word processor,
+        <application>KSpread</application> is the spreadsheet program,
+        <application>KPresenter</application> manages slide
+        presentations, and <application>Kontour</application> lets you
+        draw graphical documents.</para>
+
+      <para>Before installing the latest
+        <application>KOffice</application>, make sure you have an
+        up-to-date version of <application>KDE</application>.</para>
+
+      <para>To install <application>KOffice</application> as a
+        package, issue the following command:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r koffice</userinput></screen>
+
+      <para>If the package is not available, you can use the ports
+        collection.  For instance, to install
+        <application>KOffice</application> for
+        <application>KDE3</application>, do:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/editors/koffice-kde3</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>AbiWord</title>
+      <indexterm>
+	<primary><application>AbiWord</application></primary>
+      </indexterm>
+
+      <para><application>AbiWord</application> is a free word
+        processing program similar in look and feel to <application>&microsoft; Word</application>.
+        It is suitable for typing papers, letters, reports, memos, and
+        so forth.  It is very fast, contains many features, and is
+        very user-friendly.</para>
+
+      <para><application>AbiWord</application> can import or export
+        many file formats, including some proprietary ones like
+        Microsoft <filename>.doc</filename>.</para>
+
+      <para><application>AbiWord</application> is available as a
+        package.  You can install it by:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r abiword</userinput></screen>
+
+      <para>If the package is not available, it can be compiled from
+        the Ports Collection.  The Ports Collection should be more
+        up to date.  It can be done as follows:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/editors/abiword</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>The GIMP</title>
+      <indexterm>
+	<primary><application>The GIMP</application></primary>
+      </indexterm>
+
+      <para>For image authoring or picture retouching,
+        <application>The GIMP</application> is a very sophisticated
+        image manipulation program.  It can be used as a simple paint
+        program or as a quality photo retouching suite.  It supports a
+        large number of plug-ins and features a scripting interface.
+        <application>The GIMP</application> can read and write a wide
+        range of file formats.  It supports interfaces with scanners
+        and tablets.</para>
+
+      <para>You can install the package by issuing this
+        command:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r gimp</userinput></screen>
+
+      <para>If your FTP site does not have this package, you can use
+        the Ports Collection.  The
+        <ulink url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink>
+        directory of the Ports Collection also contains
+        <application>The Gimp Manual</application>.  Here is how to
+        get them installed:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gimp</userinput>
+&prompt.root; <userinput>make install clean</userinput>
+&prompt.root; <userinput>cd /usr/ports/graphics/gimp-manual-pdf</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <note>
+        <para>The
+          <ulink url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink>
+          directory of the Ports Collection holds the development
+          version of <application>The GIMP</application> in
+          <filename role="package">graphics/gimp-devel</filename>.
+          An HTML version of
+          <application>The Gimp Manual</application> is available from
+          <filename role="package">graphics/gimp-manual-html</filename>.</para>
+       </note>
+    </sect2>
+
+    <sect2>
+      <title>OpenOffice.org</title>
+      <indexterm>
+	<primary><application>OpenOffice.org</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>office suite</primary>
+	<secondary><application>OpenOffice.org</application></secondary>
+      </indexterm>
+
+      <para><application>OpenOffice.org</application> includes all of the
+        mandatory applications in a complete office productivity
+        suite: a word processor, a spreadsheet, a presentation manager,
+        and a drawing program.  Its user interface is very similar
+        to other office suites, and it can import and export in various
+        popular file formats.  It is available in a number of
+        different languages including interfaces, spell checkers, and
+        dictionaries.</para>
+
+      <para>The word processor of
+        <application>OpenOffice.org</application> uses a native XML
+        file format for increased portability and flexibility.  The
+        spreadsheet program features a macro language and it can be
+        interfaced with external databases.
+        <application>OpenOffice.org</application> is already stable
+        and runs natively on &windows;, &solaris;, Linux, FreeBSD,
+        and &macos;&nbsp;X.  More
+        information about <application>OpenOffice.org</application>
+        can be found on the
+	<ulink url="http://www.openoffice.org/">OpenOffice.org web site</ulink>.
+	For FreeBSD specific information, and to directly
+	download packages use the <ulink
+	url="http://porting.openoffice.org/freebsd/">FreeBSD OpenOffice.org
+	Porting Team</ulink>'s web site.</para>
+
+      <para>To install <application>OpenOffice.org</application>,
+        do:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r openoffice</userinput></screen>
+
+      <note>
+	<para>When running a -RELEASE version of &os;, this should work.
+	  Otherwise, you should look on the &os; <application>OpenOffice.org</application> Porting Team's
+	  web site to download and install the appropriate package
+	  using &man.pkg.add.1;.  Both the current release and
+	  development version are available for download at this
+	  location.</para>
+      </note>
+
+      <para>Once the package is installed, you just have to type the
+	following command to run
+        <application>OpenOffice.org</application>:</para>
+
+      <screen>&prompt.user; <userinput>openoffice.org</userinput></screen>
+
+      <note>
+	<para>During the first launch, you will be asked some
+	  questions and a <filename>.openoffice.org2</filename> folder
+	  will be created in your home directory.</para>
+      </note>
+
+      <para>If the <application>OpenOffice.org</application> packages
+        are not available, you still have the option to compile the
+        port.  However, you must bear in mind that it requires a lot of
+        disk space and a fairly long time to compile.</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/editors/openoffice.org-2.0</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <note>
+	<para>If you want to build a localized version, replace the
+	  previous command line with the following:</para>
+
+	<screen>&prompt.root; <userinput>make LOCALIZED_LANG=<replaceable>your_language</replaceable> install clean</userinput></screen>
+
+	<para>You have to replace
+	  <replaceable>your_language</replaceable> with the correct
+	  language ISO-code.  A list of supported language codes is
+	  available in the
+	  <filename>files/Makefile.localized</filename> file, located
+	  in the port directory.</para>
+      </note>
+
+      <para>Once this is done,
+	<application>OpenOffice.org</application> can be launched with
+	the command:</para>
+
+      <screen>&prompt.user; <userinput>openoffice.org</userinput></screen>
+    </sect2>
+  </sect1>
+
+  <sect1 id="desktop-viewers">
+    <title>Document Viewers</title>
+
+    <para>Some new document formats have recently gained popularity.
+      The standard viewers they require may not be available in the
+      base system.  We will see how to install them in this
+      section.</para>
+
+    <para>This section covers these applications:</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="4">
+        <thead>
+          <row>
+            <entry>Application Name</entry>
+            <entry>Resources Needed</entry>
+            <entry>Installation from Ports</entry>
+            <entry>Major Dependencies</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><application>&acrobat.reader;</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+            <entry>Linux Binary Compatibility</entry>
+          </row>
+
+          <row>
+            <entry><application>gv</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+            <entry><application>Xaw3d</application></entry>
+          </row>
+
+          <row>
+            <entry><application>Xpdf</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+            <entry><application>FreeType</application></entry>
+          </row>
+
+          <row>
+            <entry><application>GQview</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+            <entry><application>Gtk+</application> or <application>GNOME</application></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+
+    <sect2>
+      <title>&acrobat.reader;</title>
+      <indexterm>
+	<primary><application>Acrobat Reader</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>PDF</primary>
+	<secondary>viewing</secondary>
+      </indexterm>
+
+      <para>Many documents are now distributed as PDF files,
+        which stands for <quote>Portable Document Format</quote>.  One
+        of the recommended viewers for these types of files is
+        <application>&acrobat.reader;</application>, released by Adobe
+        for Linux.  As FreeBSD can run Linux binaries, it is also
+        available for FreeBSD.</para>
+
+      <para>To install <application>&acrobat.reader; 7</application> from
+	the Ports collection, do:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/print/acroread7</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <para>A package is not available due to licencing restrictions.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>gv</title>
+      <indexterm>
+	<primary><application>gv</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>PDF</primary>
+	<secondary>viewing</secondary>
+      </indexterm>
+      <indexterm>
+	<primary>PostScript</primary>
+	<secondary>viewing</secondary>
+      </indexterm>
+
+      <para><application>gv</application> is a &postscript; and PDF
+        viewer.  It is originally based on
+        <application>ghostview</application> but it has a nicer look
+        thanks to the <application>Xaw3d</application> library.  It is fast and its interface is
+        clean.  <application>gv</application> has many features like
+        orientation, paper size, scale, or antialias.  Almost any
+        operation can be done either from the keyboard or the
+        mouse.</para>
+
+      <para>To install <application>gv</application> as a package,
+        do:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r gv</userinput></screen>
+
+      <para>If you cannot get the package, you can use the Ports
+        collection:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/print/gv</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Xpdf</title>
+      <indexterm>
+	<primary><application>Xpdf</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>PDF</primary>
+	<secondary>viewing</secondary>
+      </indexterm>
+
+      <para>If you want a small FreeBSD PDF viewer,
+        <application>Xpdf</application> is a light-weight and
+        efficient viewer.  It requires very few resources and is
+        very stable.  It uses the standard X fonts and does not
+        require <application>&motif;</application> or any other X toolkit.</para>
+
+      <para>To install the <application>Xpdf</application> package,
+        issue this command:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r xpdf</userinput></screen>
+
+      <para>If the package is not available or you prefer to use the
+        Ports Collection, do:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/graphics/xpdf</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <para>Once the installation is complete, you can launch
+        <application>Xpdf</application> and use the right mouse button
+        to activate the menu.</para>
+    </sect2>
+
+    <sect2>
+      <title>GQview</title>
+      <indexterm>
+	<primary><application>GQview</application></primary>
+      </indexterm>
+
+      <para><application>GQview</application> is an image manager.
+        You can view a file with a single click, launch an external
+        editor, get thumbnail previews, and much more.  It also
+        features a slideshow mode and some basic file operations.  You
+        can manage image collections and easily find duplicates.
+        <application>GQview</application> can do full screen viewing
+        and supports internationalization.</para>
+
+      <para>If you want to install the
+        <application>GQview</application> package, do:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r gqview</userinput></screen>
+
+      <para>If the package is not available or you prefer to use the
+        Ports Collection, do:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gqview</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+  </sect1>
+
+  <sect1 id="desktop-finance">
+    <title>Finance</title>
+
+    <para>If, for any reason, you would like to manage your personal
+      finances on your FreeBSD Desktop, there are some powerful and
+      easy to use applications ready to be installed.  Some of them
+      are compatible with widespread file formats like those of
+      <application><trademark class="registered">Quicken</trademark></application> or <application>Excel</application> documents.</para>
+
+    <para>This section covers these applications:</para>
+     
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="4">
+        <thead>
+          <row>
+            <entry>Application Name</entry>
+            <entry>Resources Needed</entry>
+            <entry>Installation from Ports</entry>
+            <entry>Major Dependencies</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><application>GnuCash</application></entry>
+            <entry>light</entry>
+            <entry>heavy</entry>
+            <entry><application>GNOME</application></entry>
+          </row>
+
+          <row>
+            <entry><application>Gnumeric</application></entry>
+            <entry>light</entry>
+            <entry>heavy</entry>
+            <entry><application>GNOME</application></entry>
+          </row>
+
+          <row>
+            <entry><application>Abacus</application></entry>
+            <entry>light</entry>
+            <entry>light</entry>
+            <entry><application>Tcl/Tk</application></entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+   
+    <sect2>
+      <title>GnuCash</title>
+      <indexterm>
+	<primary><application>GnuCash</application></primary>
+      </indexterm>
+
+      <para><application>GnuCash</application> is part of the
+        <application>GNOME</application> effort to provide
+        user-friendly yet powerful applications to end-users.  With
+        <application>GnuCash</application>, you can keep track of your
+        income and expenses, your bank accounts, or your stocks.  It
+        features an intuitive interface while remaining very
+        professional.</para>
+
+      <para><application>GnuCash</application> provides a smart
+        register, a hierarchical system of accounts, many keyboard
+        accelerators and auto-completion methods.  It can split a
+        single transaction into several more detailed pieces.
+        <application>GnuCash</application> can import and merge
+        <application>Quicken</application> QIF files.  It also handles most international date
+        and currency formats.</para>
+
+      <para>To install <application>GnuCash</application> on your
+        system, do:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r gnucash</userinput></screen>
+
+      <para>If the package is not available, you can use the ports
+        collection:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/finance/gnucash</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Gnumeric</title>
+      <indexterm>
+	<primary><application>Gnumeric</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>spreadsheet</primary>
+	<secondary><application>Gnumeric</application></secondary>
+      </indexterm>
+
+      <para><application>Gnumeric</application> is a spreadsheet, part
+        of the <application>GNOME</application> desktop environment.
+        It features convenient automatic <quote>guessing</quote> of user
+        input according to the cell format and an autofill system for
+        many sequences.  It can import files in a number of popular
+        formats like those of <application>Excel</application>, <application>Lotus 1-2-3</application>, or <application>Quattro Pro</application>.
+        <application>Gnumeric</application> supports graphs through
+        the <filename role="package">math/guppi</filename> graphing
+        program.  It has a large number of built-in functions and
+        allows all of the usual cell formats such as number, currency,
+        date, time, and much more.</para>
+
+      <para>To install <application>Gnumeric</application> as a
+        package, type in:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r gnumeric</userinput></screen>
+
+      <para>If the package is not available, you can use the ports
+        collection by doing:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/math/gnumeric</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Abacus</title>
+      <indexterm>
+	<primary><application>Abacus</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary>spreadsheet</primary>
+	<secondary><application>Abacus</application></secondary>
+      </indexterm>
+
+      <para><application>Abacus</application> is a small and easy to
+        use spreadsheet.  It includes many built-in functions useful
+        in several domains such as statistics, finances, and
+        mathematics.  It can import and export the <application>Excel</application> file format.
+        <application>Abacus</application> can produce &postscript;
+        output.</para>
+
+      <para>To install <application>Abacus</application> from its
+        package, do:</para>
+
+      <screen>&prompt.root; <userinput>pkg_add -r abacus</userinput></screen>
+
+      <para>If the package is not available, you can use the ports
+        collection by doing:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/deskutils/abacus</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+    </sect2>
+  </sect1>
+
+  <sect1 id="desktop-summary">
+    <title>Summary</title>
+
+    <para>While FreeBSD is popular among ISPs for its performance and
+      stability, it is quite ready for day-to-day use as a desktop.
+      With several thousand applications available as
+      <ulink url="http://www.FreeBSD.org/where.html">packages</ulink> or
+      <ulink url="http://www.FreeBSD.org/ports/index.html">ports</ulink>,
+      you can build a perfect desktop that suits all your needs.</para>
+
+    <para>Once you have achieved the installation of your desktop, you
+      may want to go one step further with
+      <filename role="package">misc/instant-workstation</filename>.
+      This <quote>meta-port</quote> allows you to build a typical set
+      of ports for a workstation.  You can customize it by editing
+      <filename>/usr/ports/misc/instant-workstation/Makefile</filename>.
+      Follow the syntax used for the default set to add or remove
+      ports, and build it with the usual procedure.
+      Eventually, you will be able to create a big package that
+      corresponds to your very own desktop and install it to your
+      other workstations!</para>
+
+    <para>Here is a quick review of all the desktop applications
+      covered in this chapter:</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="3">
+        <thead>
+          <row>
+            <entry>Application Name</entry>
+	    <entry>Package Name</entry>
+	    <entry>Ports Name</entry>
+	  </row>
+	</thead>
+
+	<tbody>
+	  <row>
+            <entry><application>Mozilla</application></entry>
+	    <entry><literal>mozilla</literal></entry>
+	    <entry><filename role="package">www/mozilla</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>Opera</application></entry>
+	    <entry><literal>opera</literal></entry>
+	    <entry><filename role="package">www/opera</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>Firefox</application></entry>
+	    <entry><literal>firefox</literal></entry>
+	    <entry><filename role="package">www/firefox</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>KOffice</application></entry>
+	    <entry><literal>koffice-kde3</literal></entry>
+	    <entry><filename role="package">editors/koffice-kde3</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>AbiWord</application></entry>
+	    <entry><literal>abiword</literal></entry>
+	    <entry><filename role="package">editors/abiword</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>The GIMP</application></entry>
+	    <entry><literal>gimp</literal></entry>
+	    <entry><filename role="package">graphics/gimp</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>OpenOffice.org</application></entry>
+	    <entry><literal>openoffice</literal></entry>
+	    <entry><filename role="package">editors/openoffice-1.1</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>&acrobat.reader;</application></entry>
+	    <entry><literal>acroread</literal></entry>
+	    <entry><filename role="package">print/acroread7</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>gv</application></entry>
+	    <entry><literal>gv</literal></entry>
+	    <entry><filename role="package">print/gv</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>Xpdf</application></entry>
+	    <entry><literal>xpdf</literal></entry>
+	    <entry><filename role="package">graphics/xpdf</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>GQview</application></entry>
+	    <entry><literal>gqview</literal></entry>
+	    <entry><filename role="package">graphics/gqview</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>GnuCash</application></entry>
+	    <entry><literal>gnucash</literal></entry>
+	    <entry><filename role="package">finance/gnucash</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>Gnumeric</application></entry>
+	    <entry><literal>gnumeric</literal></entry>
+	    <entry><filename role="package">math/gnumeric</filename></entry>
+	  </row>
+
+	  <row>
+            <entry><application>Abacus</application></entry>
+	    <entry><literal>abacus</literal></entry>
+	    <entry><filename role="package">deskutils/abacus</filename></entry>
+	  </row>
+        </tbody>
+      </tgroup>
+    </informaltable>
+  </sect1>
+</chapter>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/disks/Makefile b/pl_PL.ISO8859-2/books/handbook/disks/Makefile
new file mode 100644
index 0000000000..140975c79e
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/disks/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	disks/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/disks/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/disks/chapter.sgml
new file mode 100644
index 0000000000..1b12843d99
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/disks/chapter.sgml
@@ -0,0 +1,4061 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="disks">
+  <title>Storage</title>
+
+  <sect1 id="disks-synopsis">
+    <title>Synopsis</title>
+
+
+    <para>This chapter covers the use of disks in FreeBSD.  This
+      includes memory-backed disks, network-attached disks,
+      standard SCSI/IDE storage devices, and devices using the USB
+      interface.</para>
+
+    <para>After reading this chapter, you will know:</para>
+    <itemizedlist>
+      <listitem><para>The terminology FreeBSD uses to describe the
+      organization of data on a physical disk (partitions and slices).</para>
+      </listitem>
+      <listitem><para>How to add additional hard disks to your system.</para>
+      </listitem>
+      <listitem>
+	<para>How to configure &os; to use USB storage devices.</para>
+      </listitem>
+      <listitem><para>How to set up virtual file systems, such as memory
+      disks.</para></listitem>
+      <listitem>
+	<para>How to use quotas to limit disk space usage.</para>
+      </listitem>
+      <listitem>
+	<para>How to encrypt disks to secure them against attackers.</para>
+      </listitem>
+      <listitem>
+	<para>How to create and burn CDs and DVDs on FreeBSD.</para>
+      </listitem>
+      <listitem>
+        <para>The various storage media options for backups.</para>
+      </listitem>
+      <listitem>
+        <para>How to use backup programs available under FreeBSD.</para>
+      </listitem>
+      <listitem>
+        <para>How to backup to floppy disks.</para>
+      </listitem>
+      <listitem>
+        <para>What file system snapshots are and how to use them efficiently.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Know how to configure and install a new FreeBSD kernel
+          (<xref linkend="kernelconfig">).</para>
+      </listitem>
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="disks-naming">
+    <title>Device Names</title>
+
+    <para>The following is a list of physical storage devices
+      supported in FreeBSD, and the device names associated with
+      them.</para>
+
+    <table id="disk-naming-physical-table" frame="none">
+      <title>Physical Disk Naming Conventions</title>
+
+      <tgroup cols="2">
+	<thead>
+	  <row>
+	    <entry>Drive type</entry>
+	    <entry>Drive device name</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry>IDE hard drives</entry>
+	    <entry><literal>ad</literal></entry>
+	  </row>
+	  <row>
+	    <entry>IDE CDROM drives</entry>
+	    <entry><literal>acd</literal></entry>
+	  </row>
+	  <row>
+	    <entry>SCSI hard drives and USB Mass storage devices</entry>
+	    <entry><literal>da</literal></entry>
+	  </row>
+	  <row>
+	    <entry>SCSI CDROM drives</entry>
+	    <entry><literal>cd</literal></entry>
+	  </row>
+	  <row>
+	    <entry>Assorted non-standard CDROM drives</entry>
+	    <entry><literal>mcd</literal> for Mitsumi CD-ROM and
+	      <literal>scd</literal> for Sony CD-ROM devices
+	    </entry>
+	  </row>
+	  <row>
+	    <entry>Floppy drives</entry>
+	    <entry><literal>fd</literal></entry>
+	  </row>
+	  <row>
+	    <entry>SCSI tape drives</entry>
+	    <entry><literal>sa</literal></entry>
+            </row>
+	  <row>
+	    <entry>IDE tape drives</entry>
+	    <entry><literal>ast</literal></entry>
+	  </row>
+	  <row>
+	    <entry>Flash drives</entry>
+	    <entry><literal>fla</literal> for &diskonchip; Flash device</entry>
+	  </row>
+	  <row>
+	    <entry>RAID drives</entry>
+	    <entry><literal>aacd</literal> for &adaptec; AdvancedRAID,
+	      <literal>mlxd</literal> and <literal>mlyd</literal>
+	      for &mylex;,
+	      <literal>amrd</literal> for AMI &megaraid;,
+	      <literal>idad</literal> for Compaq Smart RAID,
+	      <literal>twed</literal> for &tm.3ware; RAID.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </table>
+  </sect1>
+
+  <sect1 id="disks-adding">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>David</firstname>
+	  <surname>O'Brien</surname>
+	  <contrib>Originally contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 26 Apr 1998 -->
+    </sect1info>
+
+    <title>Adding Disks</title>
+
+    <indexterm>
+      <primary>disks</primary>
+      <secondary>adding</secondary>
+    </indexterm>
+
+    <para>Lets say we want to add a new SCSI disk to a machine that
+      currently only has a single drive.  First turn off the computer
+      and install the drive in the computer following the instructions
+      of the computer, controller, and drive manufacturer.  Due to the
+      wide variations of procedures to do this, the details are beyond
+      the scope of this document.</para>
+
+    <para>Login as user <username>root</username>.  After you have installed the
+      drive, inspect <filename>/var/run/dmesg.boot</filename> to ensure the new
+      disk was found.  Continuing with our example, the newly added drive will
+      be <devicename>da1</devicename> and we want to mount it on
+      <filename>/1</filename> (if you are adding an IDE drive, the device name
+      will be <devicename>ad1</devicename>).</para>
+
+    <indexterm><primary>partitions</primary></indexterm>
+    <indexterm><primary>slices</primary></indexterm>
+    <indexterm>
+      <primary><command>fdisk</command></primary>
+    </indexterm>
+
+    <para>FreeBSD runs on IBM-PC compatible computers, therefore it must
+      take into account the PC BIOS partitions.  These are different
+      from the traditional BSD partitions.  A PC disk has up to four
+      BIOS partition entries.  If the disk is going to be truly
+      dedicated to FreeBSD, you can use the
+      <emphasis>dedicated</emphasis> mode.  Otherwise, FreeBSD will
+      have to live within one of the PC BIOS partitions.  FreeBSD
+      calls the PC BIOS partitions <emphasis>slices</emphasis> so as
+      not to confuse them with traditional BSD partitions.  You may
+      also use slices on a disk that is dedicated to FreeBSD, but used
+      in a computer that also has another operating system installed.
+      This is a good way to avoid confusing the <command>fdisk</command> utility of
+      other, non-FreeBSD operating systems.</para>
+
+    <para>In the slice case the drive will be added as
+      <filename>/dev/da1s1e</filename>.  This is read as: SCSI disk,
+      unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1),
+      and <filename>e</filename> BSD partition.  In the dedicated
+      case, the drive will be added simply as
+      <filename>/dev/da1e</filename>.</para>
+
+    <para>Due to the use of 32-bit integers to store the number of sectors,
+      &man.bsdlabel.8; is
+      limited to 2^32-1 sectors per disk or 2TB in most cases.  The
+      &man.fdisk.8; format allows a starting sector of no more than
+      2^32-1 and a length of no more than 2^32-1, limiting partitions to
+      2TB and disks to 4TB in most cases.  The &man.sunlabel.8; format
+      is limited to 2^32-1 sectors per partition and 8 partitions for
+      a total of 16TB. For larger disks, &man.gpt.8; partitions may be
+      used.</para>
+
+    <sect2>
+      <title>Using &man.sysinstall.8;</title>
+      <indexterm>
+        <primary><application>sysinstall</application></primary>
+        <secondary>adding disks</secondary>
+      </indexterm>
+      <indexterm>
+	<primary>su</primary>
+      </indexterm>
+      <procedure>
+	<step>
+	  <title>Navigating <application>Sysinstall</application></title>
+
+	  <para>You may use <command>sysinstall</command> to
+	    partition and label a new disk using its easy to use menus.
+	    Either login as user <username>root</username> or use the
+	    <command>su</command> command.  Run
+	    <command>sysinstall</command> and enter the
+	    <literal>Configure</literal> menu.  Within the
+	    <literal>FreeBSD Configuration Menu</literal>, scroll down and
+	    select the <literal>Fdisk</literal> option.</para>
+	</step>
+
+	<step>
+	  <title><application>fdisk</application> Partition Editor</title>
+	  <para>Once inside <application>fdisk</application>, typing <userinput>A</userinput> will
+	    use the entire disk for FreeBSD.  When asked if you want to
+	    <quote>remain cooperative with any future possible operating
+	      systems</quote>, answer <literal>YES</literal>.  Write the
+	    changes to the disk using <userinput>W</userinput>.  Now exit the
+	    FDISK editor by typing <userinput>q</userinput>.  Next you will be
+	    asked about the <quote>Master Boot Record</quote>.  Since you are adding a
+	    disk to an already running system, choose
+	    <literal>None</literal>.</para>
+	</step>
+
+	<step>
+	  <title>Disk Label Editor</title>
+	  <indexterm><primary>BSD partitions</primary></indexterm>
+
+	  <para>Next, you need to exit <application>sysinstall</application>
+            and start it again.  Follow the directions above, although this
+            time choose the <literal>Label</literal> option. This will
+	    enter the <literal>Disk Label Editor</literal>.  This
+	    is where you will create the traditional BSD partitions.  A
+	    disk can have up to eight partitions, labeled
+	    <literal>a-h</literal>.
+	    A few of the partition labels have special uses.  The
+	    <literal>a</literal> partition is used for the root partition
+	    (<filename>/</filename>).  Thus only your system disk (e.g,
+	    the disk you boot from) should have an <literal>a</literal>
+	    partition.  The <literal>b</literal> partition is used for
+	    swap partitions, and you may have many disks with swap
+	    partitions.  The <literal>c</literal> partition addresses the
+	    entire disk in dedicated mode, or the entire FreeBSD slice in
+	    slice mode.  The other partitions are for general use.</para>
+
+	  <para><application>sysinstall</application>'s Label editor
+	    favors the <literal>e</literal>
+	    partition for non-root, non-swap partitions.  Within the
+	    Label editor, create a single file system by typing
+	    <userinput>C</userinput>.  When prompted if this will be a FS
+	    (file system) or swap, choose <literal>FS</literal> and type in a
+	    mount point (e.g, <filename>/mnt</filename>).  When adding a
+	    disk in post-install mode, <application>sysinstall</application>
+	    will not create entries
+	    in <filename>/etc/fstab</filename> for you, so the mount point
+	    you specify is not important.</para>
+
+	  <para>You are now ready to write the new label to the disk and
+	    create a file system on it.  Do this by typing
+	    <userinput>W</userinput>.  Ignore any errors from
+	    <application>sysinstall</application> that
+	    it could not mount the new partition.  Exit the Label Editor
+	    and <application>sysinstall</application> completely.</para>
+	</step>
+
+	<step>
+	  <title>Finish</title>
+
+	  <para>The last step is to edit <filename>/etc/fstab</filename>
+	    to add an entry for your new disk.</para>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2>
+      <title>Using Command Line Utilities</title>
+
+      <sect3>
+	<title>Using Slices</title>
+
+	<para>This setup will allow your disk to work correctly with
+	  other operating systems that might be installed on your
+	  computer and will not confuse other operating systems'
+	  <command>fdisk</command> utilities.  It is recommended
+	  to use this method for new disk installs.  Only use
+	  <literal>dedicated</literal> mode if you have a good reason
+	  to do so!</para>
+
+	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
+&prompt.root; <userinput>fdisk -BI da1</userinput> #Initialize your new disk
+&prompt.root; <userinput>bsdlabel -B -w -r da1s1 auto</userinput> #Label it.
+&prompt.root; <userinput>bsdlabel -e da1s1</userinput> # Edit the bsdlabel just created and add any partitions.
+&prompt.root; <userinput>mkdir -p /1</userinput>
+&prompt.root; <userinput>newfs /dev/da1s1e</userinput> # Repeat this for every partition you created.
+&prompt.root; <userinput>mount /dev/da1s1e /1</userinput> # Mount the partition(s)
+&prompt.root; <userinput>vi /etc/fstab</userinput> # Add the appropriate entry/entries to your <filename>/etc/fstab</filename>.</screen>
+
+	<para>If you have an IDE disk, substitute <filename>ad</filename>
+	  for <filename>da</filename>.</para>
+      </sect3>
+
+      <sect3>
+	<title>Dedicated</title>
+	<indexterm><primary>OS/2</primary></indexterm>
+
+	<para>If you will not be sharing the new drive with another operating
+	  system, you may use the <literal>dedicated</literal> mode.  Remember
+	  this mode can confuse Microsoft operating systems; however, no damage
+	  will be done by them.  IBM's &os2; however, will
+	  <quote>appropriate</quote> any partition it finds which it does not
+	  understand.</para>
+
+	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput>
+&prompt.root; <userinput>bsdlabel -Brw da1 auto</userinput>
+&prompt.root; <userinput>bsdlabel -e da1</userinput>				# create the `e' partition
+&prompt.root; <userinput>newfs -d0 /dev/da1e</userinput>
+&prompt.root; <userinput>mkdir -p /1</userinput>
+&prompt.root; <userinput>vi /etc/fstab</userinput>				# add an entry for /dev/da1e
+&prompt.root; <userinput>mount /1</userinput></screen>
+
+	<para>An alternate method is:</para>
+
+	<screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 count=2</userinput>
+&prompt.root; <userinput>bsdlabel /dev/da1 | bsdlabel -BrR da1 /dev/stdin</userinput>
+&prompt.root; <userinput>newfs /dev/da1e</userinput>
+&prompt.root; <userinput>mkdir -p /1</userinput>
+&prompt.root; <userinput>vi /etc/fstab</userinput>					# add an entry for /dev/da1e
+&prompt.root; <userinput>mount /1</userinput></screen>
+
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="raid">
+    <title>RAID</title>
+
+    <sect2 id="raid-soft">
+      <title>Software RAID</title>
+
+      <sect3 id="ccd">
+	<sect3info>
+	  <authorgroup>
+	    <author>
+	      <firstname>Christopher</firstname>
+	      <surname>Shumway</surname>
+	      <contrib>Original work by </contrib>
+	    </author>
+	  </authorgroup>
+	  <authorgroup>
+	    <author>
+	      <firstname>Jim</firstname>
+	      <surname>Brown</surname>
+	      <contrib>Revised by </contrib>
+	    </author>
+	  </authorgroup>
+	</sect3info>
+
+<indexterm><primary>RAID</primary><secondary>software</secondary></indexterm>
+<indexterm>
+  <primary>RAID</primary><secondary>CCD</secondary>
+</indexterm>
+
+	<title>Concatenated Disk Driver (CCD) Configuration</title>
+	<para>When choosing a mass storage solution the most important
+	  factors to consider are speed, reliability, and cost.  It is
+	  rare to have all three in balance; normally a fast, reliable mass
+	  storage device is expensive, and to cut back on cost either speed
+	  or reliability must be sacrificed.</para>
+
+          <para>In designing the system described below, cost was chosen
+          as  the most important factor, followed by speed, then reliability.
+          Data transfer speed for this system is ultimately
+          constrained by the network.  And while reliability is very important,
+          the CCD drive described below serves online data that is already
+          fully backed up on CD-R's and can easily be replaced.</para>
+
+          <para>Defining your own requirements is the first step
+          in choosing a mass storage solution.  If your requirements prefer
+          speed or reliability over cost, your solution will differ from
+          the system described in this section.</para>
+
+
+	<sect4 id="ccd-installhw">
+	  <title>Installing the Hardware</title>
+
+	  <para>In addition to the IDE system disk, three Western
+            Digital 30GB, 5400 RPM IDE disks form the core
+            of the CCD disk described below providing approximately
+	    90GB of online storage.  Ideally,
+	    each IDE disk would have its own IDE controller
+	    and cable, but to minimize cost, additional
+	    IDE controllers were not used.  Instead the disks were
+	    configured with jumpers so that each IDE controller has
+            one master, and one slave.</para>
+
+	  <para>Upon reboot, the system BIOS was configured to
+	    automatically detect the disks attached.  More importantly,
+	    FreeBSD detected them on reboot:</para>
+
+	  <programlisting>ad0: 19574MB &lt;WDC WD205BA&gt; [39770/16/63] at ata0-master UDMA33
+ad1: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata0-slave UDMA33
+ad2: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata1-master UDMA33
+ad3: 29333MB &lt;WDC WD307AA&gt; [59598/16/63] at ata1-slave UDMA33</programlisting>
+
+ 	  <note><para>If FreeBSD does not detect all the disks, ensure
+ 	    that you have jumpered them correctly.  Most IDE drives
+ 	    also have a <quote>Cable Select</quote> jumper.  This is
+ 	    <emphasis>not</emphasis> the jumper for the master/slave
+ 	    relationship.  Consult the drive documentation for help in
+ 	    identifying the correct jumper.</para></note>
+
+ 	  <para>Next, consider how to attach them as part of the file
+ 	    system.  You should research both &man.vinum.8; (<xref
+ 	    linkend="vinum-vinum">) and &man.ccd.4;.  In this
+ 	    particular configuration, &man.ccd.4; was chosen.</para>
+	</sect4>
+
+	<sect4 id="ccd-setup">
+	  <title>Setting Up the CCD</title>
+
+ 	  <para>The &man.ccd.4; driver allows you to take
+  	    several identical disks and concatenate them into one
+  	    logical file system.  In order to use
+ 	    &man.ccd.4;, you need a kernel with
+ 	    &man.ccd.4; support built in.
+ 	    Add this line to your kernel configuration file, rebuild, and
+ 	    reinstall the kernel:</para>
+
+	  <programlisting>device   ccd</programlisting>
+
+	  <para>The &man.ccd.4; support can also be
+	    loaded as a kernel loadable module.</para>
+
+ 	  <para>To set up &man.ccd.4;, you must first use
+ 	    &man.bsdlabel.8; to label the disks:</para>
+
+	  <programlisting>bsdlabel -r -w ad1 auto
+bsdlabel -r -w ad2 auto
+bsdlabel -r -w ad3 auto</programlisting>
+
+ 	  <para>This creates a bsdlabel for <devicename>ad1c</devicename>, <devicename>ad2c</devicename> and <devicename>ad3c</devicename> that
+  	    spans the entire disk.</para>
+
+ 	  <para>The next step is to change the disk label type.  You
+ 	    can use &man.bsdlabel.8; to edit the
+ 	    disks:</para>
+
+	  <programlisting>bsdlabel -e ad1
+bsdlabel -e ad2
+bsdlabel -e ad3</programlisting>
+
+ 	  <para>This opens up the current disk label on each disk with
+ 	    the editor specified by the <envar>EDITOR</envar>
+ 	    environment variable, typically &man.vi.1;.</para>
+
+	  <para>An unmodified disk label will look something like
+	    this:</para>
+
+	  <programlisting>8 partitions:
+#        size   offset    fstype   [fsize bsize bps/cpg]
+  c: 60074784        0    unused        0     0     0   # (Cyl.    0 - 59597)</programlisting>
+
+ 	  <para>Add a new <literal>e</literal> partition for &man.ccd.4; to use. This
+ 	    can usually be copied from the <literal>c</literal> partition,
+ 	    but the <option>fstype</option> <emphasis>must</emphasis>
+ 	    be <userinput>4.2BSD</userinput>.  The disk label should
+ 	    now look something like this:</para>
+
+	  <programlisting>8 partitions:
+#        size   offset    fstype   [fsize bsize bps/cpg]
+  c: 60074784        0    unused        0     0     0   # (Cyl.    0 - 59597)
+  e: 60074784        0    4.2BSD        0     0     0   # (Cyl.    0 - 59597)</programlisting>
+
+	</sect4>
+
+	<sect4 id="ccd-buildingfs">
+	  <title>Building the File System</title>
+
+	  <para>Now that you have all the disks labeled, you must
+	    build the &man.ccd.4;.  To do that,
+	    use  &man.ccdconfig.8;, with options similar to the following:</para>
+
+	    <programlisting>ccdconfig ccd0<co id="co-ccd-dev"> 32<co id="co-ccd-interleave"> 0<co id="co-ccd-flags"> /dev/ad1e<co id="co-ccd-devs"> /dev/ad2e /dev/ad3e</programlisting>
+
+	  <para>The use and meaning of each option is shown below:</para>
+
+          <calloutlist>
+            <callout arearefs="co-ccd-dev">
+	    <para>The first argument is the device to configure, in this case,
+	    <filename>/dev/ccd0c</filename>. The <filename>/dev/</filename>
+            portion is optional.</para>
+            </callout>
+
+            <callout arearefs="co-ccd-interleave">
+
+	    <para>The interleave for the file system.  The interleave
+	    defines the size of a stripe in disk blocks, each normally 512 bytes.
+	    So, an interleave of 32 would be 16,384 bytes.</para>
+            </callout>
+
+            <callout arearefs="co-ccd-flags">
+	    <para>Flags for &man.ccdconfig.8;.  If you want to enable drive
+	    mirroring, you can specify a flag here. This
+	    configuration does not provide mirroring for
+	    &man.ccd.4;, so it is set at 0 (zero).</para>
+            </callout>
+
+            <callout arearefs="co-ccd-devs">
+	    <para>The final arguments to &man.ccdconfig.8;
+	    are the devices to place into the array.  Use the complete pathname
+	    for each device.</para>
+            </callout>
+          </calloutlist>
+
+
+	  <para>After running &man.ccdconfig.8; the &man.ccd.4;
+          is configured. A file system can be installed. Refer to &man.newfs.8;
+          for options, or simply run: </para>
+
+	  <programlisting>newfs /dev/ccd0c</programlisting>
+
+
+	</sect4>
+
+	<sect4 id="ccd-auto">
+	  <title>Making it All Automatic</title>
+
+	  <para>Generally, you will want to mount the
+	    &man.ccd.4; upon each reboot. To do this, you must
+	    configure it first.  Write out your current configuration to
+	    <filename>/etc/ccd.conf</filename> using the following command:</para>
+
+	  <programlisting>ccdconfig -g &gt; /etc/ccd.conf</programlisting>
+
+	  <para>During reboot, the script <command>/etc/rc</command>
+	    runs <command>ccdconfig -C</command> if <filename>/etc/ccd.conf</filename>
+	    exists. This automatically configures the
+	    &man.ccd.4; so it can be mounted.</para>
+
+	  <note><para>If you are booting into single user mode, before you can
+	    &man.mount.8; the &man.ccd.4;, you
+	    need to issue the following command to configure the
+	    array:</para>
+
+	  <programlisting>ccdconfig -C</programlisting>
+          </note>
+
+	  <para>To automatically mount the &man.ccd.4;,
+            place an entry for the &man.ccd.4; in
+	    <filename>/etc/fstab</filename> so it will be mounted at
+	    boot time:</para>
+
+	  <programlisting>/dev/ccd0c              /media       ufs     rw      2       2</programlisting>
+	</sect4>
+      </sect3>
+
+      <sect3 id="vinum">
+	<title>The Vinum Volume Manager</title>
+
+<indexterm><primary>RAID</primary><secondary>software</secondary></indexterm>
+<indexterm>
+  <primary>RAID</primary>
+  <secondary>Vinum</secondary>
+</indexterm>
+
+	<para>The Vinum Volume Manager is a block device driver which
+	  implements virtual disk drives.  It isolates disk hardware
+	  from the block device interface and maps data in ways which
+	  result in an increase in flexibility, performance and
+	  reliability compared to the traditional slice view of disk
+	  storage.  &man.vinum.8; implements the RAID-0, RAID-1 and
+	  RAID-5 models, both individually and in combination.</para>
+
+	<para>See <xref linkend="vinum-vinum"> for more
+	  information about &man.vinum.8;.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="raid-hard">
+      <title>Hardware RAID</title>
+
+      <indexterm>
+	<primary>RAID</primary>
+	<secondary>hardware</secondary>
+      </indexterm>
+
+      <para>FreeBSD also supports a variety of hardware <acronym>RAID</acronym>
+        controllers.  These devices control a <acronym>RAID</acronym> subsystem
+        without the need for FreeBSD specific software to manage the
+        array.</para>
+
+      <para>Using an on-card <acronym>BIOS</acronym>, the card controls most  of the disk operations
+	itself.  The following is a brief setup description using a Promise <acronym>IDE</acronym> <acronym>RAID</acronym>
+	controller.  When this card is installed and the system is started up, it
+	displays a prompt requesting information.  Follow the instructions
+	to enter the card's setup screen.  From here, you have the ability to
+	combine all the attached drives.  After doing so, the disk(s) will look like
+	a single drive to FreeBSD.  Other <acronym>RAID</acronym> levels can be set up
+	accordingly.
+      </para>
+    </sect2>
+
+    <sect2>
+      <title>Rebuilding ATA RAID1 Arrays</title>
+
+      <para>FreeBSD allows you to hot-replace a failed disk in an array. This requires
+	that you catch it before you reboot.</para>
+
+      <para>You will probably see something like the following in <filename>/var/log/messages</filename> or in the &man.dmesg.8;
+	output:</para>
+
+      <programlisting>ad6 on monster1 suffered a hard error.
+ad6: READ command timeout tag=0 serv=0 - resetting
+ad6: trying fallback to PIO mode
+ata3: resetting devices .. done
+ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11)\\
+status=59 error=40
+ar0: WARNING - mirror lost</programlisting>
+
+      <para>Using &man.atacontrol.8;, check for further information:</para>
+
+      <screen>&prompt.root; <userinput>atacontrol list</userinput>
+ATA channel 0:
+	Master:      no device present
+	Slave:   acd0 &lt;HL-DT-ST CD-ROM GCR-8520B/1.00&gt; ATA/ATAPI rev 0
+
+ATA channel 1:
+	Master:      no device present
+	Slave:       no device present
+
+ATA channel 2:
+	Master:  ad4 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
+	Slave:       no device present
+
+ATA channel 3:
+	Master:  ad6 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
+	Slave:       no device present
+
+&prompt.root; <userinput>atacontrol status ar0</userinput>
+ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED</screen>
+
+      <procedure>
+	<step>
+	  <para>You will first need to detach the ata channel with the failed
+	    disk so you can safely remove it:</para>
+
+	  <screen>&prompt.root; <userinput>atacontrol detach ata3</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Replace the disk.</para>
+	</step>
+
+	<step>
+	  <para>Reattach the ata channel:</para>
+
+	  <screen>&prompt.root; <userinput>atacontrol attach ata3</userinput>
+Master:  ad6 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
+Slave:   no device present</screen>
+	</step>
+
+	<step>
+	  <para>Add the new disk to the array as a spare:</para>
+
+	  <screen>&prompt.root; <userinput>atacontrol addspare ar0 ad6</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Rebuild the array:</para>
+
+	  <screen>&prompt.root; <userinput>atacontrol rebuild ar0</userinput></screen>
+	</step>
+
+	<step>
+	  <para>It is possible to check on the progress by issuing the
+	    following command:</para>
+
+	  <screen>&prompt.root; <userinput>dmesg | tail -10</userinput>
+[output removed]
+ad6: removed from configuration
+ad6: deleted from ar0 disk1
+ad6: inserted into ar0 disk1 as spare
+
+&prompt.root; <userinput>atacontrol status ar0</userinput>
+ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed</screen>
+	</step>
+
+	<step>
+	  <para>Wait until this operation completes.</para>
+	</step>
+      </procedure>
+    </sect2>
+  </sect1>
+
+  <sect1 id="usb-disks">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Fonvieille</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- Jul 2004 -->
+    </sect1info>
+
+    <title>USB Storage Devices</title>
+    <indexterm>
+      <primary>USB</primary>
+      <secondary>disks</secondary>
+    </indexterm>
+
+    <para>A lot of external storage solutions, nowadays, use the
+      Universal Serial Bus (USB): hard drives, USB thumbdrives, CD-R
+      burners, etc.  &os; provides support for these devices.</para>
+
+    <sect2>
+      <title>Configuration</title>
+
+      <para>The USB mass storage devices driver, &man.umass.4;,
+	provides the support for USB storage devices.  If you use the
+	<filename>GENERIC</filename> kernel, you do not have to change
+	anything in your configuration.  If you use a custom kernel,
+	be sure that the following lines are present in your kernel
+	configuration file:</para>
+
+      <programlisting>device scbus
+device da
+device pass
+device uhci
+device ohci
+device usb
+device umass</programlisting>
+
+      <para>The &man.umass.4; driver uses the SCSI subsystem to access
+	to the USB storage devices, your USB device will be seen as a
+	SCSI device by the system.  Depending on the USB chipset on
+	your motherboard, you only need either <literal>device
+	uhci</literal> or <literal>device ohci</literal>, however
+	having both in the kernel configuration file is harmless.  Do
+	not forget to compile and install the new kernel if you added
+	any lines.</para>
+
+      <note>
+	<para>If your USB device is a CD-R or DVD burner, the SCSI CD-ROM
+	  driver, &man.cd.4;, must be added to the kernel via the
+	  line:</para>
+
+	<programlisting>device cd</programlisting>
+
+	<para>Since the burner is seen as a SCSI drive, the driver
+	  &man.atapicam.4; should not be used in the kernel
+	  configuration.</para>
+      </note>
+
+      <para>Support for USB 2.0 controllers is provided on
+	&os;; however, you must add:</para>
+
+      <programlisting>device ehci</programlisting>
+
+      <para>to your configuration file for USB 2.0 support.  Note
+	&man.uhci.4; and &man.ohci.4; drivers are still needed if you
+	want USB 1.X support.</para>
+    </sect2>
+
+    <sect2>
+      <title>Testing the Configuration</title>
+
+      <para>The configuration is ready to be tested: plug in your USB
+	device, and in the system message buffer (&man.dmesg.8;), the
+	drive should appear as something like:</para>
+
+      <screen>umass0: USB Solid state disk, rev 1.10/1.00, addr 2
+GEOM: create disk da0 dp=0xc2d74850
+da0 at umass-sim0 bus 0 target 0 lun 0
+da0: &lt;Generic Traveling Disk 1.11&gt; Removable Direct Access SCSI-2 device
+da0: 1.000MB/s transfers
+da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen>
+
+      <para>Of course, the brand, the device node
+	(<devicename>da0</devicename>) and other details can differ
+	according to your configuration.</para>
+
+      <para>Since the USB device is seen as a SCSI one, the
+	<command>camcontrol</command> command can be used to list the
+	USB storage devices attached to the system:</para>
+
+      <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
+&lt;Generic Traveling Disk 1.11&gt;      at scbus0 target 0 lun 0 (da0,pass0)</screen>
+
+      <para>If the drive comes with a file system, you should be able
+	to mount it.  The <xref linkend="disks-adding"> will help you
+	to format and create partitions on the USB drive if
+	needed.</para>
+
+      <para>If you unplug the device (the disk must be unmounted
+	before), you should see, in the system message buffer,
+	something like the following:</para>
+
+      <screen>umass0: at uhub0 port 1 (addr 2) disconnected
+(da0:umass-sim0:0:0:0): lost device
+(da0:umass-sim0:0:0:0): removing device entry
+GEOM: destroy disk da0 dp=0xc2d74850
+umass0: detached</screen>
+    </sect2>
+
+    <sect2>
+      <title>Further Reading</title>
+
+      <para>Beside the <link linkend="disks-adding">Adding
+	Disks</link> and <link linkend="mount-unmount">Mounting and
+	Unmounting File Systems</link> sections, reading various
+	manual pages may be also useful: &man.umass.4;,
+	&man.camcontrol.8;, and &man.usbdevs.8;.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="creating-cds">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Mike</firstname>
+	  <surname>Meyer</surname>
+	  <contrib>Contributed by </contrib>
+	  <!-- mwm@mired.org -->
+	</author>
+      </authorgroup>
+      <!-- Apr 2001 -->
+    </sect1info>
+
+    <title>Creating and Using Optical Media (CDs)</title>
+    <indexterm>
+      <primary>CDROMs</primary>
+      <secondary>creating</secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Introduction</title>
+
+      <para>CDs have a number of features that differentiate them from
+	conventional disks. Initially, they were not writable by the
+	user. They are designed so that they can be read continuously without
+	delays to move the head between tracks. They are also much easier
+	to transport between systems than similarly sized media were at the
+	time.</para>
+
+      <para>CDs do have tracks, but this refers to a section of data to
+	be read continuously and not a physical property of the disk. To
+	produce a CD on FreeBSD, you prepare the data files that are going
+	to make up the tracks on the CD, then write the tracks to the
+	CD.</para>
+
+      <indexterm><primary>ISO 9660</primary></indexterm>
+      <indexterm>
+        <primary>file systems</primary>
+        <secondary>ISO 9660</secondary>
+      </indexterm>
+      <para>The ISO 9660 file system was designed to deal with these
+	differences. It unfortunately codifies file system limits that were
+	common then. Fortunately, it provides an extension mechanism that
+	allows properly written CDs to exceed those limits while still
+	working with systems that do not support those extensions.</para>
+
+      <indexterm>
+        <primary><filename role="package">sysutils/cdrtools</filename></primary>
+      </indexterm>
+      <para>The <filename role="package">sysutils/cdrtools</filename>
+	port includes &man.mkisofs.8;, a program that you can use to
+	produce a data file containing an ISO 9660 file
+	system. It has options that support various extensions, and is
+	described below.</para>
+
+      <indexterm>
+        <primary>CD burner</primary>
+        <secondary>ATAPI</secondary>
+      </indexterm>
+      <para>Which tool to use to burn the CD depends on whether your CD burner
+	is ATAPI or something else. ATAPI CD burners use the <command><link
+	linkend="burncd">burncd</link></command> program that is part of
+	the base system. SCSI and USB CD burners should use
+	<command><link linkend="cdrecord">cdrecord</link></command> from
+	the <filename role="package">sysutils/cdrtools</filename> port.
+	It is also possible to use <command><link
+	  linkend="cdrecord">cdrecord</link></command> and other tools
+	for SCSI drives on ATAPI hardware with the <link
+	  linkend="atapicam">ATAPI/CAM module</link>.</para>
+
+      <para>If you want CD burning software with a graphical user
+	interface, you may wish to take a look at either
+	<application>X-CD-Roast</application> or
+	<application>K3b</application>.  These tools are available as
+	packages or from the <filename
+	role="package">sysutils/xcdroast</filename> and <filename
+	role="package">sysutils/k3b</filename> ports.
+	<application>X-CD-Roast</application> and
+	<application>K3b</application> require the <link
+	linkend="atapicam">ATAPI/CAM module</link> with ATAPI
+	hardware.</para>
+    </sect2>
+
+    <sect2 id="mkisofs">
+      <title>mkisofs</title>
+
+      <para>The &man.mkisofs.8; program, which is part of the
+	<filename role="package">sysutils/cdrtools</filename> port,
+        produces an ISO 9660 file system
+	that is an image of a directory tree in the &unix; file system name
+	space. The simplest usage is:</para>
+
+      <screen>&prompt.root; <userinput>mkisofs -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/tree</replaceable></userinput></screen>
+
+      <indexterm>
+        <primary>file systems</primary>
+        <secondary>ISO 9660</secondary>
+      </indexterm>
+      <para>This command will create an <replaceable>imagefile.iso</replaceable>
+	containing an ISO 9660 file system that is a copy of the tree at
+	<replaceable>/path/to/tree</replaceable>. In the process, it will
+	map the file names to names that fit the limitations of the
+	standard ISO 9660 file system, and will exclude files that have
+	names uncharacteristic of ISO file systems.</para>
+
+      <indexterm>
+        <primary>file systems</primary>
+        <secondary>HFS</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>file systems</primary>
+        <secondary>Joliet</secondary>
+      </indexterm>
+      <para>A number of options are available to overcome those
+	restrictions. In particular, <option>-R</option> enables the
+	Rock Ridge extensions common to &unix; systems, <option>-J</option>
+	enables Joliet extensions used by Microsoft systems, and
+	<option>-hfs</option> can be used to create HFS file systems used
+	by &macos;.</para>
+
+      <para>For CDs that are going to be used only on FreeBSD systems,
+	<option>-U</option> can be used to disable all filename
+	restrictions. When used with <option>-R</option>, it produces a
+	file system image that is identical to the FreeBSD tree you started
+	from, though it may violate the ISO 9660 standard in a number of
+	ways.</para>
+
+      <indexterm>
+        <primary>CDROMs</primary>
+        <secondary>creating bootable</secondary>
+      </indexterm>
+      <para>The last option of general use is <option>-b</option>. This is
+	used to specify the location of the boot image for use in producing an
+	<quote>El Torito</quote> bootable CD. This option takes an
+	argument which is the path to a boot image from the top of the
+	tree being written to the CD. By default, &man.mkisofs.8; creates an
+	ISO image in the so-called <quote>floppy disk emulation</quote> mode,
+	and thus expects the boot image to be exactly 1200, 1440 or
+	2880&nbsp;KB in size. Some boot loaders, like the one used by the
+	FreeBSD distribution disks, do not use emulation mode; in this case,
+	the <option>-no-emul-boot</option> option should be used. So, if
+	<filename>/tmp/myboot</filename> holds a bootable FreeBSD system
+	with the boot image in
+	<filename>/tmp/myboot/boot/cdboot</filename>, you could produce the
+	image of an ISO 9660 file system in
+	<filename>/tmp/bootable.iso</filename> like so:</para>
+
+      <screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen>
+
+      <para>Having done that, if you have <devicename>md</devicename>
+	configured in your kernel, you can mount the file system with:</para>
+
+      <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /tmp/bootable.iso -u 0</userinput>
+&prompt.root; <userinput>mount -t cd9660 /dev/md0 /mnt</userinput></screen>
+
+      <para>At which point you can verify that <filename>/mnt</filename>
+	and <filename>/tmp/myboot</filename> are identical.</para>
+
+      <para>There are many other options you can use with
+	&man.mkisofs.8; to fine-tune its behavior.  In particular:
+	modifications to an ISO 9660 layout and the creation of Joliet
+	and HFS discs.  See the	&man.mkisofs.8; manual page for details.</para>
+    </sect2>
+
+    <sect2 id="burncd">
+      <title>burncd</title>
+      <indexterm>
+        <primary>CDROMs</primary>
+        <secondary>burning</secondary>
+      </indexterm>
+      <para>If you have an ATAPI CD burner, you can use the
+	<command>burncd</command> command to burn an ISO image onto a
+	CD. <command>burncd</command> is part of the base system, installed
+	as <filename>/usr/sbin/burncd</filename>.  Usage is very simple, as
+	it has few options:</para>
+
+      <screen>&prompt.root; <userinput>burncd -f <replaceable>cddevice</replaceable> data <replaceable>imagefile.iso</replaceable> fixate</userinput></screen>
+
+      <para>Will burn a copy of <replaceable>imagefile.iso</replaceable> on
+	<replaceable>cddevice</replaceable>. The default device is
+	<filename>/dev/acd0</filename>.  See &man.burncd.8; for options to
+	set the write speed, eject the CD after burning, and write audio
+	data.</para>
+    </sect2>
+
+    <sect2 id="cdrecord">
+      <title>cdrecord</title>
+
+      <para>If you do not have an ATAPI CD burner, you will have to use
+	<command>cdrecord</command> to burn your
+	CDs. <command>cdrecord</command> is not part of the base system;
+	you must install it from either the port at <filename role="package">sysutils/cdrtools</filename>
+	or the appropriate
+	package. Changes to the base system can cause binary versions of
+	this program to fail, possibly resulting in a
+	<quote>coaster</quote>. You should therefore either upgrade the
+	port when you upgrade your system, or if you are <link
+	linkend="stable">tracking -STABLE</link>, upgrade the port when a
+	new version becomes available.</para>
+
+      <para>While <command>cdrecord</command> has many options, basic usage
+	is even simpler than <command>burncd</command>. Burning an ISO 9660
+	image is done with:</para>
+
+      <screen>&prompt.root; <userinput>cdrecord dev=<replaceable>device</replaceable> <replaceable>imagefile.iso</replaceable></userinput></screen>
+
+      <para>The tricky part of using <command>cdrecord</command> is finding
+	the <option>dev</option> to use. To find the proper setting, use
+	the <option>-scanbus</option> flag of <command>cdrecord</command>,
+	which might produce results like this:</para>
+      <indexterm>
+        <primary>CDROMs</primary>
+        <secondary>burning</secondary>
+      </indexterm>
+      <screen>&prompt.root; <userinput>cdrecord -scanbus</userinput>
+Cdrecord-Clone 2.01 (i386-unknown-freebsd7.0) Copyright (C) 1995-2004 J&ouml;rg Schilling
+Using libscg version 'schily-0.1'
+scsibus0:
+        0,0,0     0) 'SEAGATE ' 'ST39236LW       ' '0004' Disk
+        0,1,0     1) 'SEAGATE ' 'ST39173W        ' '5958' Disk
+        0,2,0     2) *
+        0,3,0     3) 'iomega  ' 'jaz 1GB         ' 'J.86' Removable Disk
+        0,4,0     4) 'NEC     ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM
+        0,5,0     5) *
+        0,6,0     6) *
+        0,7,0     7) *
+scsibus1:
+        1,0,0   100) *
+        1,1,0   101) *
+        1,2,0   102) *
+        1,3,0   103) *
+        1,4,0   104) *
+        1,5,0   105) 'YAMAHA  ' 'CRW4260         ' '1.0q' Removable CD-ROM
+        1,6,0   106) 'ARTEC   ' 'AM12S           ' '1.06' Scanner
+        1,7,0   107) *</screen>
+
+      <para>This lists the appropriate <option>dev</option> value for the
+	devices on the list. Locate your CD burner, and use the three
+	numbers separated by commas as the value for
+	<option>dev</option>. In this case, the CRW device is 1,5,0, so the
+	appropriate input would be
+	<option>dev=1,5,0</option>. There are easier
+	ways to specify this value; see &man.cdrecord.1; for
+	details. That is also the place to look for information on writing
+	audio tracks, controlling the speed, and other things.</para>
+    </sect2>
+
+    <sect2 id="duplicating-audiocds">
+      <title>Duplicating Audio CDs</title>
+
+      <para>You can duplicate an audio CD by extracting the audio data from
+	the CD to a series of files, and then writing these files to a blank
+	CD.  The process is slightly different for ATAPI and SCSI
+	drives.</para>
+
+      <procedure>
+	<title>SCSI Drives</title>
+
+	<step>
+	  <para>Use <command>cdda2wav</command> to extract the audio.</para>
+
+	  <screen>&prompt.user; <userinput>cdda2wav -v255 -D2,0 -B -Owav</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Use <command>cdrecord</command> to write the
+	    <filename>.wav</filename> files.</para>
+
+	  <screen>&prompt.user; <userinput>cdrecord -v dev=<replaceable>2,0</replaceable> -dao -useinfo  *.wav</userinput></screen>
+
+	  <para>Make sure that <replaceable>2,0</replaceable> is set
+	    appropriately, as described in <xref linkend="cdrecord">.</para>
+	</step>
+      </procedure>
+
+      <procedure>
+	<title>ATAPI Drives</title>
+
+	<step>
+	  <para>The ATAPI CD driver makes each track available as
+	    <filename>/dev/acd<replaceable>d</replaceable>t<replaceable>nn</replaceable></filename>,
+	    where <replaceable>d</replaceable> is the drive number, and
+	    <replaceable>nn</replaceable> is the track number written with two
+	    decimal digits, prefixed with zero as needed.
+	    So the first track on the first disk is
+	    <filename>/dev/acd0t01</filename>, the second is
+	    <filename>/dev/acd0t02</filename>, the third is
+	    <filename>/dev/acd0t03</filename>, and so on.</para>
+
+	  <para>Make sure the appropriate files exist in
+	    <filename>/dev</filename>.  If the entries are missing,
+	    force the system to retaste the media:</para>
+
+	  <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=/dev/null count=1</userinput></screen>
+	</step>
+
+	<step>
+	  <para>Extract each track using &man.dd.1;.  You must also use a
+	    specific block size when extracting the files.</para>
+
+	  <screen>&prompt.root; <userinput>dd if=/dev/acd0t01 of=track1.cdr bs=2352</userinput>
+&prompt.root; <userinput>dd if=/dev/acd0t02 of=track2.cdr bs=2352</userinput>
+...
+</screen>
+	</step>
+
+	<step>
+	  <para>Burn the extracted files to disk using
+	    <command>burncd</command>.  You must specify that these are audio
+	    files, and that <command>burncd</command> should fixate the disk
+	    when finished.</para>
+
+	  <screen>&prompt.root; <userinput>burncd -f <replaceable>/dev/acd0</replaceable> audio track1.cdr track2.cdr <replaceable>...</replaceable> fixate</userinput></screen>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2 id="imaging-cd">
+      <title>Duplicating Data CDs</title>
+
+      <para>You can copy a data CD to a image file that is
+	functionally equivalent to the image file created with
+        &man.mkisofs.8;, and you can use it to duplicate
+	any data CD.  The example given here assumes that your CDROM
+	device is <devicename>acd0</devicename>.  Substitute your
+	correct CDROM device.</para>
+
+      <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=file.iso bs=2048</userinput></screen>
+
+      <para>Now that you have an image, you can burn it to CD as
+	described above.</para>
+    </sect2>
+
+    <sect2 id="mounting-cd">
+      <title>Using Data CDs</title>
+
+      <para>Now that you have created a standard data CDROM, you
+	probably want to mount it and read the data on it.  By
+	default, &man.mount.8; assumes that a file system is of type
+	<literal>ufs</literal>.  If you try something like:</para>
+
+      <screen>&prompt.root; <userinput>mount /dev/cd0 /mnt</userinput></screen>
+
+      <para>you will get a complaint about <errorname>Incorrect super
+	  block</errorname>, and no mount. The CDROM is not a
+	  <literal>UFS</literal> file system, so attempts to mount it
+	  as such will fail.  You just need to tell &man.mount.8; that
+	  the file system is of type <literal>ISO9660</literal>, and
+	  everything will work.  You do this by specifying the
+	  <option>-t cd9660</option> option &man.mount.8;. For
+	  example, if you want to mount the CDROM device,
+	  <filename>/dev/cd0</filename>, under
+	  <filename>/mnt</filename>, you would execute:</para>
+
+          <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen>
+
+      <para>Note that your device name
+	(<filename>/dev/cd0</filename> in this example) could be
+	different, depending on the interface your CDROM uses. Also,
+	the <option>-t cd9660</option> option just executes
+	&man.mount.cd9660.8;. The above example could be shortened
+	to:</para>
+
+<screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0 /mnt</userinput></screen>
+
+      <para>You can generally use data CDROMs from any vendor in this
+	way.  Disks with certain ISO 9660 extensions might behave
+	oddly, however.  For example, Joliet disks store all filenames
+	in two-byte Unicode characters.  The FreeBSD kernel does not
+	speak Unicode (yet!), so non-English characters show up as
+	question marks.  (The FreeBSD
+	CD9660 driver includes hooks to load an appropriate Unicode
+	conversion table on the fly.  Modules for some of the common
+	encodings are available via the
+	<filename role="package">sysutils/cd9660_unicode</filename> port.)</para>
+
+      <para>Occasionally, you might get <errorname>Device not
+	configured</errorname> when trying to mount a CDROM.  This
+	usually means that the CDROM drive thinks that there is no
+	disk in the tray, or that the drive is not visible on the bus.
+	It can take a couple of seconds for a CDROM drive to realize
+	that it has been fed, so be patient.</para>
+
+      <para>Sometimes, a SCSI CDROM may be missed because it did not
+	have enough time to answer the bus reset.  If you have a SCSI
+	CDROM please add the following option to your kernel
+	configuration and <link linkend="kernelconfig-building">rebuild your kernel</link>.</para>
+
+      <programlisting>options SCSI_DELAY=15000</programlisting>
+
+      <para>This tells your SCSI bus to pause 15 seconds during boot,
+	to give your CDROM drive every possible chance to answer the
+	bus reset.</para>
+    </sect2>
+
+    <sect2 id="rawdata-cd">
+      <title>Burning Raw Data CDs</title>
+
+      <para>You can choose to burn a file directly to CD, without
+	creating an ISO 9660 file system.  Some people do this for
+	backup purposes.  This runs more quickly than burning a
+	standard CD:</para>
+
+      <screen>&prompt.root; <userinput>burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate</userinput></screen>
+
+      <para>In order to retrieve the data burned to such a CD, you
+	  must read data from the raw device node:</para>
+
+      <screen>&prompt.root; <userinput>tar xzvf /dev/acd1</userinput></screen>
+
+      <para>You cannot mount this disk as you would a normal CDROM.
+	  Such a CDROM cannot be read under any operating system
+	  except FreeBSD.  If you want to be able to mount the CD, or
+	  share data with another operating system, you must use
+	  &man.mkisofs.8; as described above.</para>
+    </sect2>
+
+    <sect2 id="atapicam">
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Marc</firstname>
+	    <surname>Fonvieille</surname>
+	    <contrib>Contributed by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+
+      <indexterm>
+	<primary>CD burner</primary>
+	<secondary>ATAPI/CAM driver</secondary>
+      </indexterm>
+      <title>Using the ATAPI/CAM Driver</title>
+
+      <para>This driver allows ATAPI devices (CD-ROM, CD-RW, DVD
+	drives etc...) to be accessed through the SCSI subsystem, and
+	so allows the use of applications like <filename
+	role="package">sysutils/cdrdao</filename> or
+	&man.cdrecord.1;.</para>
+
+      <para>To use this driver, you will need to add the following
+	line to the <filename>/boot/loader.conf</filename>
+	file:</para>
+
+      <programlisting>atapicam_load="YES"</programlisting>
+
+      <para>then, reboot your machine.</para>
+
+      <note>
+	<para>If you prefer to statically compile the &man.atapicam.4;
+	  support in your kernel, you will have to add this line to
+	  your kernel configuration file:</para>
+
+      <programlisting>device atapicam</programlisting>
+
+      <para>You also need the following lines in your kernel
+	configuration file:</para>
+
+      <programlisting>device ata
+device scbus
+device cd
+device pass</programlisting>
+
+	<para>which should already be present.  Then rebuild, install
+	  your new kernel, and reboot your machine.</para>
+      </note>
+
+      <para>During the boot process, your burner should show up,
+	like so:</para>
+
+      <screen>acd0: CD-RW &lt;MATSHITA CD-RW/DVD-ROM UJDA740&gt; at ata1-master PIO4
+cd0 at ata1 bus 0 target 0 lun 0
+cd0: &lt;MATSHITA CDRW/DVD UJDA740 1.00&gt; Removable CD-ROM SCSI-0 device
+cd0: 16.000MB/s transfers
+cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed</screen>
+
+      <para>The drive could now be accessed via the
+	<filename>/dev/cd0</filename> device name, for example to
+	mount a CD-ROM on <filename>/mnt</filename>, just type the
+	following:</para>
+
+      <screen>&prompt.root; <userinput>mount -t cd9660 <replaceable>/dev/cd0</replaceable> /mnt</userinput></screen>
+
+      <para>As <username>root</username>, you can run the following
+	command to get the SCSI address of the burner:</para>
+
+      <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
+&lt;MATSHITA CDRW/DVD UJDA740 1.00&gt;   at scbus1 target 0 lun 0 (pass0,cd0)</screen>
+
+      <para>So <literal>1,0,0</literal> will be the SCSI address to
+	use with &man.cdrecord.1; and other SCSI application.</para>
+
+      <para>For more information about ATAPI/CAM and SCSI system,
+	refer to the &man.atapicam.4; and &man.cam.4; manual
+	pages.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="creating-dvds">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Fonvieille</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Andy</firstname>
+	  <surname>Polyakov</surname>
+	  <contrib>With inputs from </contrib>
+	</author>
+      </authorgroup>
+      <!-- Feb 2004 -->
+    </sect1info>
+
+    <title>Creating and Using Optical Media (DVDs)</title>
+    <indexterm>
+      <primary>DVD</primary>
+      <secondary>burning</secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Introduction</title>
+
+      <para>Compared to the CD, the DVD is the next generation of
+	optical media storage technology.  The DVD can hold more data
+	than any CD and is nowadays the standard for video
+	publishing.</para>
+
+      <para>Five physical recordable formats can be defined for what
+	we will call a recordable DVD:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>DVD-R: This was the first DVD recordable format
+	    available.  The DVD-R standard is defined by the <ulink
+	    url="http://www.dvdforum.com/forum.shtml">DVD Forum</ulink>.
+	    This format is write once.</para>
+	</listitem>
+
+	<listitem>
+	  <para>DVD-RW: This is the rewritable version of
+	    the DVD-R standard.  A DVD-RW can be rewritten about 1000
+	    times.</para>
+	</listitem>
+
+	<listitem>
+	  <para>DVD-RAM: This is also a rewritable format
+	    supported by the DVD Forum.  A DVD-RAM can be seen as a
+	    removable hard drive.  However, this media is not
+	    compatible with most DVD-ROM drives and DVD-Video players;
+	    only a few DVD writers support the DVD-RAM format.  Read
+	    the <xref linkend="creating-dvd-ram"> for more information
+	    on DVD-RAM use.</para>
+	</listitem>
+
+	<listitem>
+	  <para>DVD+RW: This is a rewritable format defined by
+	    the <ulink url="http://www.dvdrw.com/">DVD+RW
+	    Alliance</ulink>.  A DVD+RW can be rewritten about 1000
+	    times.</para>
+	</listitem>
+
+	<listitem>
+	  <para>DVD+R: This format is the write once variation
+	    of the DVD+RW format.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>A single layer recordable DVD can hold up to
+	4,700,000,000&nbsp;bytes which is actually 4.38&nbsp;GB or
+	4485&nbsp;MB (1 kilobyte is 1024 bytes).</para>
+
+      <note>
+	<para>A distinction must be made between the physical media and
+	  the application.   For example, a DVD-Video is a specific
+	  file layout that can be written on any recordable DVD
+	  physical media: DVD-R, DVD+R, DVD-RW etc.  Before choosing
+	  the type of media, you must be sure that both the burner and the
+	  DVD-Video player (a standalone player or a DVD-ROM drive on
+	  a computer) are compatible with the media under consideration.</para></note>
+    </sect2>
+
+    <sect2>
+      <title>Configuration</title>
+
+      <para>The program &man.growisofs.1; will be used to perform DVD
+	recording.  This command is part of the
+	<application>dvd+rw-tools</application> utilities (<filename
+	role="package">sysutils/dvd+rw-tools</filename>).  The
+	<application>dvd+rw-tools</application> support all DVD media
+	types.</para>
+
+      <para>These tools use the SCSI subsystem to access to the
+	devices, therefore the <link linkend="atapicam">ATAPI/CAM
+	support</link> must be added to your kernel.  If your burner
+	uses the USB interface this addition is useless, and you should
+	read the <xref linkend="usb-disks"> for more details on USB
+	devices configuration.</para>
+
+      <para>You also have to enable DMA access for ATAPI devices, this
+	can be done in adding the following line to the
+	<filename>/boot/loader.conf</filename> file:</para>
+
+      <programlisting>hw.ata.atapi_dma="1"</programlisting>
+
+      <para>Before attempting to use the
+	<application>dvd+rw-tools</application> you should consult the
+	<ulink
+	url="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">dvd+rw-tools'
+	hardware compatibility notes</ulink> for any information
+	related to your DVD burner.</para>
+
+      <note>
+	<para>If you want a graphical user interface, you should have
+	  a look to <application>K3b</application> (<filename
+	  role="package">sysutils/k3b</filename>) which provides a
+	  user friendly interface to &man.growisofs.1; and many others
+	  burning tools.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Burning Data DVDs</title>
+
+      <para>The &man.growisofs.1; command is a frontend to <link
+	linkend="mkisofs">mkisofs</link>, it will invoke
+	&man.mkisofs.8; to create the file system layout and will
+	perform the write on the DVD.  This means you do not need to
+	create an image of the data before the burning process.</para>
+
+      <para>To burn onto a DVD+R or a DVD-R the data from the <filename
+	class="directory">/path/to/data</filename> directory, use the
+	following command:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>
+
+      <para>The options <option>-J -R</option> are passed to
+	&man.mkisofs.8; for the file system creation (in this case: an
+	ISO 9660 file system with Joliet and Rock Ridge extensions),
+	consult the &man.mkisofs.8; manual page for more
+	details.</para>
+
+      <para>The option <option>-Z</option> is used for the initial
+	session recording in any case: multiple sessions or not.  The
+	DVD device, <replaceable>/dev/cd0</replaceable>, must be
+	changed according to your configuration.  The
+	<option>-dvd-compat</option> parameter will close the disk,
+	the recording will be unappendable.  In return this should provide better
+	media compatibility with DVD-ROM drives.</para>
+
+      <para>It is also possible to burn a pre-mastered image, for
+	example to burn the image
+	<replaceable>imagefile.iso</replaceable>, we will run:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen>
+
+      <para>The write speed should be detected and automatically set
+	according to the media and the drive being used.  If you want
+	to force the write speed, use the <option>-speed=</option>
+	parameter.  For more information, read the &man.growisofs.1;
+	manual page.</para>
+    </sect2>
+
+    <indexterm>
+      <primary>DVD</primary>
+      <secondary>DVD-Video</secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Burning a DVD-Video</title>
+
+      <para>A DVD-Video is a specific file layout based on ISO 9660
+	and the micro-UDF (M-UDF) specifications.  The DVD-Video also
+	presents a specific data structure hierarchy, it is the reason
+	why you need a particular program such as <filename
+	role="package">multimedia/dvdauthor</filename> to author the
+	DVD.</para>
+
+      <para>If you already have an image of the DVD-Video file system,
+	just burn it in the same way as for any image, see the
+	previous section for an example.  If you have made the DVD
+	authoring and the result is in, for example, the directory
+	<filename class="directory">/path/to/video</filename>, the
+	following command should be used to burn the DVD-Video:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -dvd-video <replaceable>/path/to/video</replaceable></userinput></screen>
+
+      <para>The <option>-dvd-video</option> option will be passed down to
+	&man.mkisofs.8; and will instruct it to create a DVD-Video file system
+	layout.  Beside this, the <option>-dvd-video</option> option
+	implies <option>-dvd-compat</option> &man.growisofs.1;
+	option.</para>
+    </sect2>
+
+    <indexterm>
+      <primary>DVD</primary>
+      <secondary>DVD+RW</secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Using a DVD+RW</title>
+
+      <para>Unlike CD-RW, a virgin DVD+RW needs to be formatted before
+	first use.  The &man.growisofs.1; program will take care of it
+	automatically whenever appropriate, which is the
+	<emphasis>recommended</emphasis> way.  However you can use the
+	<command>dvd+rw-format</command> command to format the
+	DVD+RW:</para>
+
+      <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen>
+
+      <para>You need to perform this operation just once, keep in mind
+	that only virgin DVD+RW medias need to be formatted.  Then you
+	can burn the DVD+RW in the way seen in previous
+	sections.</para>
+
+      <para>If you want to burn new data (burn a totally new file
+	system not append some data) onto a DVD+RW, you do not need to
+	blank it, you just have to write over the previous recording
+	(in performing a new initial session), like this:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/newdata</replaceable></userinput></screen>
+
+      <para>DVD+RW format offers the possibility to easily append data
+	to a previous recording.  The operation consists in merging a
+	new session to the existing one, it is not multisession
+	writing, &man.growisofs.1; will <emphasis>grow</emphasis> the
+	ISO 9660 file system present on the media.</para>
+
+      <para>For example, if we want to append data to our previous
+	DVD+RW, we have to use the following:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen>
+
+      <para>The same &man.mkisofs.8; options we used to burn the
+	initial session should be used during next writes.</para>
+
+      <note>
+	<para>You may want to use the <option>-dvd-compat</option>
+	  option if you want better media compatibility with DVD-ROM
+	  drives.  In the DVD+RW case, this will not prevent you from
+	  adding data.</para>
+      </note>
+
+      <para>If for any reason you really want to blank the media, do
+	the following:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable>=<replaceable>/dev/zero</replaceable></userinput></screen>
+    </sect2>
+
+    <indexterm>
+      <primary>DVD</primary>
+      <secondary>DVD-RW</secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Using a DVD-RW</title>
+
+      <para>A DVD-RW accepts two disc formats: the incremental
+	sequential one and the restricted overwrite.  By default
+	DVD-RW discs are in sequential format.</para>
+
+      <para>A virgin DVD-RW can be directly written without the need
+	of a formatting operation, however a non-virgin DVD-RW in
+	sequential format needs to be blanked before to be able to
+	write a new initial session.</para>
+
+      <para>To blank a DVD-RW in sequential mode, run:</para>
+
+      <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen>
+
+      <note>
+	<para>A full blanking (<option>-blank=full</option>) will take
+	  about one hour on a 1x media.  A fast blanking can be
+	  performed using the <option>-blank</option> option if the
+	  DVD-RW will be recorded in Disk-At-Once (DAO) mode.  To burn
+	  the DVD-RW in DAO mode, use the command:</para>
+
+	<screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen>
+
+	<para>The <option>-use-the-force-luke=dao</option> option
+	  should not be required since &man.growisofs.1; attempts to
+	  detect minimally (fast blanked) media and engage DAO
+	  write.</para>
+
+	<para>In fact one should use restricted overwrite mode with
+	  any DVD-RW, this format is more flexible than the default
+	  incremental sequential one.</para>
+      </note>
+
+      <para>To write data on a sequential DVD-RW, use the same
+	instructions as for the other DVD formats:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen>
+
+      <para>If you want to append some data to your previous
+	recording, you will have to use the &man.growisofs.1;
+	<option>-M</option> option.  However, if you perform data
+	addition on a DVD-RW in incremental sequential mode, a new
+	session will be created on the disc and the result will be a
+	multi-session disc.</para>
+
+      <para>A DVD-RW in restricted overwrite format does not need to
+	be blanked before a new initial session, you just have to
+	overwrite the disc with the <option>-Z</option> option, this
+	is similar to the DVD+RW case.  It is also possible to grow an
+	existing ISO 9660 file system written on the disc in a same
+	way as for a DVD+RW with the <option>-M</option> option.  The
+	result will be a one-session DVD.</para>
+
+      <para>To put a DVD-RW in the restricted overwrite format, the
+	following command must be used:</para>
+
+      <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen>
+
+      <para>To change back to the sequential format use:</para>
+
+      <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Multisession</title>
+
+      <para>Very few DVD-ROM drives support
+	multisession DVDs, they will most of time, hopefully, only read
+	the first session.  DVD+R, DVD-R and DVD-RW in sequential
+	format can accept multiple sessions, the notion of multiple
+	sessions does not exist for the DVD+RW and the DVD-RW
+	restricted overwrite formats.</para>
+
+      <para>Using the following command after an initial (non-closed)
+	session on a DVD+R, DVD-R, or DVD-RW in sequential format,
+	will add a new session to the disc:</para>
+
+      <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen>
+
+      <para>Using this command line with a DVD+RW or a DVD-RW in restricted
+	overwrite mode, will append data in merging the new session to
+	the existing one.  The result will be a single-session disc.
+	This is the way used to add data after an initial write on these
+	medias.</para>
+
+      <note>
+	<para>Some space on the media is used between each session for
+	  end and start of sessions.  Therefore, one should add
+	  sessions with large amount of data to optimize media space.
+	  The number of sessions is limited to 154 for a DVD+R,
+	  about 2000 for a DVD-R, and 127 for a DVD+R Double
+	  Layer.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>For More Information</title>
+
+      <para>To obtain more information about a DVD, the
+	<command>dvd+rw-mediainfo
+	<replaceable>/dev/cd0</replaceable></command> command can be
+	ran with the disc in the drive.</para>
+
+      <para>More information about the
+	<application>dvd+rw-tools</application> can be found in
+	the &man.growisofs.1; manual page, on the <ulink
+	url="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools
+	web site</ulink> and in the <ulink
+	url="http://lists.debian.org/cdwrite/">cdwrite mailing
+	list</ulink> archives.</para>
+
+      <note>
+	<para>The <command>dvd+rw-mediainfo</command> output of the
+	  resulting recording or the media with issues is mandatory
+	  for any problem report.  Without this output, it will be
+	  quite impossible to help you.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="creating-dvd-ram">
+      <title>Using a DVD-RAM</title>
+      <indexterm>
+	<primary>DVD</primary>
+	<secondary>DVD-RAM</secondary>
+      </indexterm>
+
+      <sect3>
+	<title>Configuration</title>
+
+	<para>DVD-RAM writers come with either SCSI or ATAPI
+	  interface.  DMA access for ATAPI devices has to be enabled,
+	  this can be done by adding the following line to the
+	  <filename>/boot/loader.conf</filename> file:</para>
+
+	<programlisting>hw.ata.atapi_dma="1"</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>Preparing the Medium</title>
+
+	<para>As previously mentioned in the chapter introduction, a
+	  DVD-RAM can be seen as a removable hard drive.  As any other
+	  hard drive the DVD-RAM must be <quote>prepared</quote>
+	  before the first use.  In the example, the whole
+	  disk space will be used with a standard UFS2 file system:</para>
+
+	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/dev/acd0</replaceable> count=2</userinput>
+&prompt.root; <userinput>bsdlabel -Bw <replaceable>acd0</replaceable></userinput>
+&prompt.root; <userinput>newfs <replaceable>/dev/acd0</replaceable></userinput></screen>
+
+	<para>The DVD device, <devicename>acd0</devicename>, must be
+	  changed according to the configuration.</para>
+      </sect3>
+
+      <sect3>
+	<title>Using the Medium</title>
+
+	<para>Once the previous operations have been performed on the
+	  DVD-RAM, it can be mounted as a normal hard drive:</para>
+
+	<screen>&prompt.root; <userinput>mount <replaceable>/dev/acd0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+
+	<para>After this the DVD-RAM will be both readable and writeable.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="floppies">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Julio</firstname>
+	  <surname>Merino</surname>
+	  <contrib>Original work by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 24 Dec 2001 -->
+      <authorgroup>
+	<author>
+	  <firstname>Martin</firstname>
+	  <surname>Karlsson</surname>
+	  <contrib>Rewritten by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 27 Apr 2003 -->
+    </sect1info>
+
+    <title>Creating and Using Floppy Disks</title>
+
+    <para>Storing data on floppy disks is sometimes useful, for
+      example when one does not have any other removable storage media
+      or when one needs to transfer small amounts of data to another
+      computer.</para>
+
+    <para>This section will explain how to use floppy disks in
+      FreeBSD.  It will primarily cover formatting and usage of
+      3.5inch DOS floppies, but the concepts are similar for other
+      floppy disk formats.</para>
+
+    <sect2>
+      <title>Formatting Floppies</title>
+
+      <sect3>
+	<title>The Device</title>
+
+	<para>Floppy disks are accessed through entries in
+	  <filename>/dev</filename>, just like other devices.  To
+	  access the raw floppy disk, simply use
+	  <filename>/dev/fd<replaceable>N</replaceable></filename>.</para>
+      </sect3>
+
+      <sect3>
+	<title>Formatting</title>
+
+	<para>A floppy disk needs to be low-level formated before it
+	  can be used.  This is usually done by the vendor, but
+	  formatting is a good way to check media integrity.  Although
+	  it is possible to force larger (or smaller) disk sizes,
+	  1440kB is what most floppy disks are designed for.</para>
+
+	<para>To low-level format the floppy disk you need to use
+	  &man.fdformat.1;.  This utility expects the device name as an
+	  argument.</para>
+
+	  <para>Make note of any error messages, as these can help
+	    determine if the disk is good or bad.</para>
+
+	<sect4>
+	  <title>Formatting Floppy Disks</title>
+
+	  <para>Use the
+	    <filename>/dev/fd<replaceable>N</replaceable></filename>
+	    devices to format the floppy.  Insert a new 3.5inch floppy
+	    disk in your drive and issue:</para>
+
+	  <screen>&prompt.root; <userinput>/usr/sbin/fdformat -f 1440 /dev/fd0</userinput></screen>
+
+	</sect4>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>The Disk Label</title>
+
+      <para>After low-level formatting the disk, you will need to
+	place a disk label on it.  This disk label will be destroyed
+	later, but it is needed by the system to determine the size of
+	the disk and its geometry later.</para>
+
+      <para>The new disk label will take over the whole disk, and will
+	contain all the proper information about the geometry of the
+	floppy.  The geometry values for the disk label are listed in
+	<filename>/etc/disktab</filename>.</para>
+
+      <para>You can run now &man.bsdlabel.8; like so:</para>
+
+      <screen>&prompt.root; <userinput>/sbin/bsdlabel -B -r -w /dev/fd0 fd1440</userinput></screen>
+
+    </sect2>
+
+    <sect2>
+      <title>The File System</title>
+
+      <para>Now the floppy is ready to be high-level formated. This
+	will place a new file system on it, which will let FreeBSD read
+	and write to the disk.  After creating the new file system, the
+	disk label is destroyed, so if you want to reformat the disk, you
+	will have to recreate the disk label.</para>
+
+      <para>The floppy's file system can be either UFS or FAT.
+	 FAT is generally a better choice for floppies.</para>
+
+      <para>To put a new file system on the floppy, issue:</para>
+
+      <screen>&prompt.root; <userinput>/sbin/newfs_msdos /dev/fd0</userinput></screen>
+
+      <para>The disk is now ready for use.</para>
+    </sect2>
+
+
+    <sect2>
+      <title>Using the Floppy</title>
+
+      <para>To use the floppy, mount it with &man.mount.msdosfs.8;.  One can also use
+	<filename role="package">emulators/mtools</filename> from the ports
+	collection.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="backups-tapebackups">
+    <title>Creating and Using Data Tapes</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 ~150&nbsp;kB/s, peaking at ~500&nbsp;kB/s.
+	Data capacity starts at 1.3&nbsp;GB and ends at 2.0&nbsp;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&nbsp;GB.</para>
+
+      <para>The DDS-3 standard now supports tape capacities up to 12&nbsp;GB (or
+	24&nbsp;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&nbsp;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 ~250&nbsp;kB/s to ~500&nbsp;kB/s.  Data sizes start
+	at 300&nbsp;MB and go up to 7&nbsp;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+&nbsp;GB.</para>
+
+      <para>The Exabyte <quote>Mammoth</quote> model supports 12&nbsp;GB on one tape
+	(24&nbsp;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 <quote>serious</quote>
+	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; 152 x
+	102 x 17 mm).</para>
+
+      <para>Data throughput ranges from ~150&nbsp;kB/s to ~500&nbsp;kB/s.  Data capacity
+	ranges from 40&nbsp;MB to 15&nbsp;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-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 <quote>hook</quote> 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.5&nbsp;MB/s, three times the throughput of
+	4mm, 8mm, or QIC tape drives.  Data capacities range from 10&nbsp;GB to 20&nbsp;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&nbsp;GB to 9&nbsp;TB of
+	storage.</para>
+
+      <para>With compression, DLT Type IV format supports up to 70&nbsp;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&nbsp;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 <application>SAMS:Alexandria</application> 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>
+
+      <itemizedlist>
+	<listitem>
+	  <para><command>mt fsf 1</command> causes the tape drive to write an
+	  Identifier Block to the tape.</para>
+	</listitem>
+
+	<listitem>
+	  <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 <errorname>DUMP: End of tape
+	    detected</errorname> and the console will show: <errorname>HARDWARE
+	    FAILURE info:280 asc:80,96</errorname>.</para>
+
+	  <para>rewind the tape using: <command>mt rewind</command>.</para>
+
+	  <para>Subsequent tape operations are successful.</para>
+	</listitem>
+      </itemizedlist>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="backups-floppybackups">
+    <title>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
+	&man.tar.1; 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 &man.tar.1; will prompt you to
+	insert the next volume (because &man.tar.1; 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, &man.tar.1; will not allow the
+	<option>-z</option> option to be used for multi-volume archives.
+	You could, of course, &man.gzip.1; all the files,
+	&man.tar.1; them to the floppies, then
+	&man.gunzip.1; 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>The utility &man.tar.1; 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 &man.tar.1; will warn you that it cannot
+	restore it, even if you have not asked it to!</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="backup-strategies">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Lowell</firstname>
+	  <surname>Gilbert</surname>
+	  <contrib>Original work by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 3 Dec 2005 -->
+    </sect1info>
+
+    <title>Backup Strategies</title>
+
+    <para>The first requirement in devising a backup plan is to make sure that
+      all of the following problems are covered:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Disk failure</para>
+      </listitem>
+      <listitem>
+	<para>Accidental file deletion</para>
+      </listitem>
+      <listitem>
+	<para>Random file corruption</para>
+      </listitem>
+      <listitem>
+	<para>Complete machine destruction (e.g. fire), including destruction
+	  of any on-site backups.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>It is perfectly possible that some systems will be best served by
+      having each of these problems covered by a completely different
+      technique.  Except for strictly personal systems with very low-value
+      data, it is unlikely that one technique would cover all of them.</para>
+
+    <para>Some of the techniques in the toolbox are:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Archives of the whole system, backed up onto permanent media
+	  offsite.  This actually provides protection against all of the
+	  possible problems listed above, but is slow and inconvenient to
+	  restore from.  You can keep copies of the backups onsite and/or
+	  online, but there will still be inconveniences in restoring files,
+	  especially for non-privileged users.</para>
+      </listitem>
+
+      <listitem>
+	<para>Filesystem snapshots.  This is really only helpful in the
+	  accidental file deletion scenario, but it can be
+	  <emphasis>very</emphasis> helpful in that case, and is quick and
+	  easy to deal with.</para>
+      </listitem>
+
+      <listitem>
+	<para>Copies of whole filesystems and/or disks (e.g. periodic rsync of
+	  the whole machine).  This is generally most useful in networks with
+	  unique requirements.  For general protection against disk failure,
+	  it is usually inferior to <acronym>RAID</acronym>.  For restoring
+	  accidentally deleted files, it can be comparable to
+	  <acronym>UFS</acronym> snapshots, but that depends on your
+	  preferences.</para>
+      </listitem>
+
+      <listitem>
+	<para><acronym>RAID</acronym>.  Minimizes or avoids downtime when a
+	  disk fails.  At the expense of having to deal with disk failures
+	  more often (because you have more disks), albeit at a much lower
+	  urgency.</para>
+      </listitem>
+
+      <listitem>
+	<para>Checking fingerprints of files.  The &man.mtree.8; utility is
+	  very useful for this.  Although it is not a backup technique, it
+	  helps guarantee that you will notice when you need to resort to your
+	  backups.  This is particularly important for offline backups, and
+	  should be checked periodically.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>It is quite easy to come up with even more techniques, many of them
+      variations on the ones listed above.  Specialized requirements will
+      usually lead to specialized techniques (for example, backing up a live
+      database usually requires a method particular to the database software
+      as an intermediate step).  The important thing is to know what dangers
+      you want to protect against, and how you will handle each.</para>
+  </sect1>
+
+  <sect1 id="backup-basics">
+    <title>Backup Basics</title>
+
+    <para>The three major backup 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 file systems. <command>dump</command> backs up an entire
+	file system on a device.  It is unable to backup only part of a
+	file system or a directory tree that spans more than one
+	file system.  <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 file systems or
+        symbolic links into those file systems.</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 &man.rcmd.3; and
+        &man.ruserok.3; to access the remote tape drive.  Therefore,
+	the user performing the backup must be listed in the
+	<filename>.rhosts</filename> file on the remote computer.  The
+        arguments to <command>rdump</command> and <command>rrestore</command> must be suitable
+        to use on the remote computer.  When
+        <command>rdump</command>ing from a FreeBSD computer to an
+        Exabyte tape drive connected to a Sun called
+        <hostid>komodo</hostid>, use:</para>
+
+      <screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&amp;1</userinput></screen>
+
+      <para>Beware: there are security implications to
+        allowing <filename>.rhosts</filename> authentication.  Evaluate your
+        situation carefully.</para>
+
+      <para>It is also possible to use <command>dump</command> and
+        <command>restore</command> in a more secure fashion over
+        <command>ssh</command>.</para>
+
+      <example>
+	<title>Using <command>dump</command> over <application>ssh</application></title>
+
+	<screen>&prompt.root; <userinput>/sbin/dump -0uan -f - /usr | gzip -2 | ssh -c blowfish \
+          targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz</userinput></screen>
+
+      </example>
+
+      <para>Or using <command>dump</command>'s built-in method,
+        setting the environment variable <envar>RSH</envar>:</para>
+
+      <example>
+	<title>Using <command>dump</command> over <application>ssh</application> with <envar>RSH</envar> set</title>
+
+	<screen>&prompt.root; <userinput>RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0 /usr</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 file system; it 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
+	it does not require the unusual command
+	pipeline that <command>cpio</command> uses.</para>
+
+      <indexterm><primary><command>tar</command></primary></indexterm>
+
+      <para>On FreeBSD 5.3 and later, both GNU <command>tar</command>
+        and the default <command>bsdtar</command> are available.  The
+        GNU version can be invoked with <command>gtar</command>.  It
+        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:</para>
+
+      <screen>&prompt.root; <userinput>/usr/bin/gtar cf komodo:/dev/nsa8 . 2>&amp;1</userinput></screen>
+
+      <para>The same could be accomplished with
+	<command>bsdtar</command> by using 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> an 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 &gt;&gt; backup.list</userinput>
+<userinput>done</userinput>
+&prompt.root; <userinput>cpio -v -o --format=newc &lt; backup.list | ssh <replaceable>user</replaceable>@<replaceable>host</replaceable> "cat &gt; <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/nsa0</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 <application>Amanda</application> server will backup to
+        a single tape drive any number of computers that have <application>Amanda</application>
+        clients and a network connection to the <application>Amanda</application> 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.  <application>Amanda</application>
+        solves this problem.  <application>Amanda</application> can use a <quote>holding disk</quote> to
+        backup several file systems at the same time.  <application>Amanda</application> creates
+        <quote>archive sets</quote>: a group of tapes used over a period of time to
+        create full backups of all the file systems listed in <application>Amanda</application>'s
+        configuration file.  The <quote>archive set</quote> also contains nightly
+        incremental (or differential) backups of all the file systems.
+        Restoring a damaged file system 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 <application>Amanda</application> generates.  <application>Amanda</application> will use any of the
+	above backup programs to write the data to tape.  <application>Amanda</application> 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;
+	file systems is <command>dump</command>.  Elizabeth created file systems 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
+	file systems.  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://berdmann.dyndns.org/zwicky/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>bsdlabel</command></primary>
+  </indexterm>
+
+	<para>First, print the bsdlabel from each of your disks
+	  (e.g. <command>bsdlabel da0 | lpr</command>), your file system 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>bsdlabel</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/sa0</command>, you
+	  might accidentally type <command>tar cvf /dev/sa0</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
+#
+bsdlabel -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 file system 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, the parts should be replaced
+	  before attempting to use the computer.</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 class="directory">/mnt2/rescue</filename>
+	  (<filename class="directory">/mnt2/stand</filename> for
+	  &os; versions older than 5.2).</para>
+
+	<para>Recover each file system separately.</para>
+
+	<indexterm>
+    <primary><command>mount</command></primary>
+  </indexterm>
+	<indexterm><primary>root partition</primary></indexterm>
+	<indexterm>
+    <primary><command>bsdlabel</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
+	  bsdlabel was damaged, use <command>bsdlabel</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 file systems.  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 file system (e.g. <command>restore vrf
+	    /dev/sa0</command>).  Unmount the file system (e.g. <command>umount
+	    /mnt</command>). Repeat for each file system 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="disks-virtual">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Fonvieille</surname>
+	  <contrib>Reorganized and enhanced by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Network, Memory, and File-Backed File Systems</title>
+    <indexterm><primary>virtual disks</primary></indexterm>
+    <indexterm>
+      <primary>disks</primary>
+      <secondary>virtual</secondary>
+    </indexterm>
+
+    <para>Aside from the disks you physically insert into your computer:
+      floppies, CDs, hard drives, and so forth; other forms of disks
+      are understood by FreeBSD - the <firstterm>virtual
+      disks</firstterm>.</para>
+
+    <indexterm><primary>NFS</primary></indexterm>
+    <indexterm><primary>Coda</primary></indexterm>
+    <indexterm>
+      <primary>disks</primary>
+      <secondary>memory</secondary>
+    </indexterm>
+    <para>These include network file systems such as the <link
+	linkend="network-nfs">Network File System</link> and Coda, memory-based
+      file systems and
+      file-backed file systems.</para>
+
+    <para>According to the FreeBSD version you run, you will have to use
+      different tools for creation and use of file-backed and
+      memory-based file systems.</para>
+
+    <note>
+      <para>Use &man.devfs.5; to allocate device nodes transparently for the
+	user.</para>
+    </note>
+
+    <sect2 id="disks-mdconfig">
+      <title>File-Backed File System</title>
+      <indexterm>
+        <primary>disks</primary>
+        <secondary>file-backed</secondary>
+      </indexterm>
+
+      <para>The utility &man.mdconfig.8; is used to configure and enable
+	memory disks, &man.md.4;, under FreeBSD.  To use
+	&man.mdconfig.8;, you have to load &man.md.4; module or to add
+	the support in your kernel configuration file:</para>
+
+      <programlisting>device md</programlisting>
+
+      <para>The &man.mdconfig.8; command supports three kinds of
+	memory backed virtual disks: memory disks allocated with
+	&man.malloc.9;, memory disks using a file or swap space as
+	backing.  One possible use is the mounting of floppy
+	or CD images kept in files.</para>
+
+      <para>To mount an existing file system image:</para>
+
+      <example>
+	<title>Using <command>mdconfig</command> to Mount an Existing File System
+	  Image</title>
+
+	<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>diskimage</replaceable> -u <replaceable>0</replaceable></userinput>
+&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput></screen>
+      </example>
+
+      <para>To create a new file system image with &man.mdconfig.8;:</para>
+
+      <example>
+	<title>Creating a New File-Backed Disk with <command>mdconfig</command></title>
+
+	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput>
+5120+0 records in
+5120+0 records out
+&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>newimage</replaceable> -u <replaceable>0</replaceable></userinput>
+&prompt.root; <userinput>bsdlabel -w md<replaceable>0</replaceable> auto</userinput>
+&prompt.root; <userinput>newfs md<replaceable>0</replaceable>a</userinput>
+/dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048
+        using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes.
+super-block backups (for fsck -b #) at:
+ 160, 2720, 5280, 7840
+&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable>a <replaceable>/mnt</replaceable></userinput>
+&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
+Filesystem 1K-blocks Used Avail Capacity  Mounted on
+/dev/md0a       4710    4  4330     0%    /mnt</screen>
+      </example>
+
+      <para>If you do not specify the unit number with the
+	<option>-u</option> option, &man.mdconfig.8; will use the
+	&man.md.4; automatic allocation to select an unused device.
+	The name of the allocated unit will be output on stdout like
+	<devicename>md4</devicename>.  For more details about
+	&man.mdconfig.8;, please refer to the manual page.</para>
+
+      <para>The utility &man.mdconfig.8; is very useful, however it
+	asks many command lines to create a file-backed file system.
+	FreeBSD also comes with a tool called &man.mdmfs.8;,
+	this program configures a &man.md.4; disk using
+	&man.mdconfig.8;, puts a UFS file system on it using
+	&man.newfs.8;, and mounts it using &man.mount.8;.  For example,
+	if you want to create and mount the same file system image as
+	above, simply type the following:</para>
+
+      <example>
+	<title>Configure and Mount a File-Backed Disk with <command>mdmfs</command></title>
+	<screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput>
+5120+0 records in
+5120+0 records out
+&prompt.root; <userinput>mdmfs -F <replaceable>newimage</replaceable> -s <replaceable>5</replaceable>m md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput>
+&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
+Filesystem 1K-blocks Used Avail Capacity  Mounted on
+/dev/md0        4718    4  4338     0%    /mnt</screen>
+      </example>
+
+      <para>If you use the option <option>md</option> without unit
+	number, &man.mdmfs.8; will use &man.md.4; auto-unit feature to
+	automatically select an unused device.  For more details
+	about &man.mdmfs.8;, please refer to the manual page.</para>
+
+    </sect2>
+
+    <sect2 id="disks-md-freebsd5">
+      <title>Memory-Based File System</title>
+      <indexterm>
+        <primary>disks</primary>
+        <secondary>memory file system</secondary>
+      </indexterm>
+
+      <para>For a
+	memory-based file system the <quote>swap backing</quote>
+	should normally be used.  Using swap backing does not mean
+	that the memory disk will be swapped out to disk by default,
+	but merely that the memory disk will be allocated from a
+	memory pool which can be swapped out to disk if needed.  It is
+	also possible to create memory-based disk which are
+	&man.malloc.9; backed, but using malloc backed memory disks,
+	especially large ones, can result in a system panic if the
+	kernel runs out of memory.</para>
+
+      <example>
+	<title>Creating a New Memory-Based Disk with
+	  <command>mdconfig</command></title>
+
+	<screen>&prompt.root; <userinput>mdconfig -a -t swap -s <replaceable>5</replaceable>m -u <replaceable>1</replaceable></userinput>
+&prompt.root; <userinput>newfs -U md<replaceable>1</replaceable></userinput>
+/dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048
+        using 4 cylinder groups of 1.27MB, 81 blks, 192 inodes.
+        with soft updates
+super-block backups (for fsck -b #) at:
+ 160, 2752, 5344, 7936
+&prompt.root; <userinput>mount /dev/md<replaceable>1</replaceable> <replaceable>/mnt</replaceable></userinput>
+&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
+Filesystem 1K-blocks Used Avail Capacity  Mounted on
+/dev/md1        4718    4  4338     0%    /mnt</screen>
+      </example>
+
+      <example>
+	<title>Creating a New Memory-Based Disk with
+	  <command>mdmfs</command></title>
+	<screen>&prompt.root; <userinput>mdmfs -s <replaceable>5</replaceable>m md<replaceable>2</replaceable> <replaceable>/mnt</replaceable></userinput>
+&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput>
+Filesystem 1K-blocks Used Avail Capacity  Mounted on
+/dev/md2        4846    2  4458     0%    /mnt</screen>
+      </example>
+    </sect2>
+
+    <sect2>
+      <title>Detaching a Memory Disk from the System</title>
+      <indexterm>
+        <primary>disks</primary>
+        <secondary>detaching a memory disk</secondary>
+      </indexterm>
+
+      <para>When a memory-based or file-based file system
+	is not used, you should release all resources to the system.
+	The first thing to do is to unmount the file system, then use
+	&man.mdconfig.8; to detach the disk from the system and release
+	the resources.</para>
+
+      <para>For example to detach and free all resources used by
+	<filename>/dev/md4</filename>:</para>
+
+      <screen>&prompt.root; <userinput>mdconfig -d -u <replaceable>4</replaceable></userinput></screen>
+
+      <para>It is possible to list information about configured
+	&man.md.4; devices in using the command <command>mdconfig
+	-l</command>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="snapshots">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 15 JUL 2002 -->
+    </sect1info>
+
+    <title>File System Snapshots</title>
+
+    <indexterm>
+      <primary>file systems</primary>
+      <secondary>snapshots</secondary>
+    </indexterm>
+
+      <para>FreeBSD offers a feature in conjunction with
+	<link linkend="soft-updates">Soft Updates</link>: File system snapshots.</para>
+
+      <para>Snapshots allow a user to create images of specified file
+	systems, and treat them as a file.
+	Snapshot files must be created in the file system that the
+	action is performed on, and a user may create no more than 20
+	snapshots per file system.  Active snapshots are recorded
+	in the superblock so they are persistent across unmount and
+	remount operations along with system reboots.  When a snapshot
+	is no longer required, it can be removed with the standard &man.rm.1;
+	command.  Snapshots may be removed in any order,
+	however all the used space may not be acquired because another snapshot will
+	possibly claim some of the released blocks.</para>
+
+      <para>The un-alterable <option>snapshot</option> file flag is set
+      by &man.mksnap.ffs.8; after initial creation of a snapshot file.
+	The &man.unlink.1; command makes an exception for snapshot files
+	since it allows them to be removed.</para>
+
+      <para>Snapshots are created with the &man.mount.8; command.  To place
+	a snapshot of <filename>/var</filename> in the file
+	<filename>/var/snapshot/snap</filename> use the following
+	command:</para>
+
+<screen>&prompt.root; <userinput>mount -u -o snapshot /var/snapshot/snap /var</userinput></screen>
+
+      <para>Alternatively, you can use &man.mksnap.ffs.8; to create
+	a snapshot:</para>
+<screen>&prompt.root; <userinput>mksnap_ffs /var /var/snapshot/snap</userinput></screen>
+
+      <para>One can find snapshot files on a file system (e.g. <filename>/var</filename>)
+        by using the &man.find.1; command:</para>
+<screen>&prompt.root; <userinput>find /var -flags snapshot</userinput></screen>
+
+      <para>Once a snapshot has been created, it has several
+	uses:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Some administrators will use a snapshot file for backup purposes,
+	    because the snapshot can be transfered to CDs or tape.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The file system integrity checker, &man.fsck.8;, may be run on the snapshot.
+	    Assuming that the file system was clean when it was mounted, you
+	    should always get a clean (and unchanging) result.
+	    This is essentially what the
+	    background &man.fsck.8; process does.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Run the &man.dump.8; utility on the snapshot.
+	    A dump will be returned that is consistent with the
+	    file system and the timestamp of the snapshot.  &man.dump.8;
+	    can also take a snapshot, create a dump image and then
+	    remove the snapshot in one command using the
+	    <option>-L</option> flag.</para>
+	</listitem>
+
+	<listitem>
+	  <para>&man.mount.8; the snapshot as a frozen image of the file system.
+	    To &man.mount.8; the snapshot
+	    <filename>/var/snapshot/snap</filename> run:</para>
+
+<screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /var/snapshot/snap -u 4</userinput>
+&prompt.root; <userinput>mount -r /dev/md4 /mnt</userinput></screen>
+
+	</listitem>
+      </itemizedlist>
+
+      <para>You can now walk the hierarchy of your frozen <filename>/var</filename>
+	file system mounted at <filename>/mnt</filename>.  Everything will
+	initially be in the same state it was during the snapshot creation time.
+	The only exception is that any earlier snapshots will appear
+	as zero length files.  When the use of a snapshot has delimited,
+	it can be unmounted with:</para>
+
+<screen>&prompt.root; <userinput>umount /mnt</userinput>
+&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen>
+
+      <para>For more information about <option>softupdates</option> and
+	file system snapshots, including technical papers, you can visit
+	Marshall Kirk McKusick's website at
+	<ulink url="http://www.mckusick.com/"></ulink>.</para>
+  </sect1>
+
+  <sect1 id="quotas">
+    <title>File System Quotas</title>
+    <indexterm>
+      <primary>accounting</primary>
+      <secondary>disk space</secondary>
+    </indexterm>
+    <indexterm><primary>disk quotas</primary></indexterm>
+
+    <para>Quotas are an optional feature of the operating system that
+      allow you to limit the amount of disk space and/or the number of
+      files a user or members of a group may allocate on a per-file
+      system basis. This is used most often on timesharing systems where
+      it is desirable to limit the amount of resources any one user or
+      group of users may allocate.  This will prevent one user or group
+      of users from consuming all of the available disk space.</para>
+
+    <sect2>
+      <title>Configuring Your System to Enable Disk Quotas</title>
+
+      <para>Before attempting to use disk quotas, it is necessary to make
+	sure that quotas are configured in your kernel.  This is done by
+	adding the following line to your kernel configuration
+	file:</para>
+
+      <programlisting>options QUOTA</programlisting>
+
+      <para>The stock <filename>GENERIC</filename> kernel does not have
+	this enabled by default, so you will have to configure, build and
+	install a custom kernel in order to use disk quotas.  Please refer
+	to <xref linkend="kernelconfig"> for more information on kernel
+	configuration.</para>
+
+      <para>Next you will need to enable disk quotas in
+	<filename>/etc/rc.conf</filename>.  This is done by adding the
+	line:</para>
+
+      <programlisting>enable_quotas="YES"</programlisting>
+      <indexterm>
+        <primary>disk quotas</primary>
+        <secondary>checking</secondary>
+      </indexterm>
+      <para>For finer control over your quota startup, there is an
+	additional configuration variable available. Normally on bootup,
+	the quota integrity of each file system is checked by the
+	&man.quotacheck.8; program.  The
+	&man.quotacheck.8; facility insures that the data in
+	the quota database properly reflects the data on the file system.
+	This is a very time consuming process that will significantly
+	affect the time your system takes to boot. If you would like to
+	skip this step, a variable in <filename>/etc/rc.conf</filename>
+	is made available for the purpose:</para>
+
+      <programlisting>check_quotas="NO"</programlisting>
+
+      <para>Finally you will need to edit <filename>/etc/fstab</filename>
+	to enable disk quotas on a per-file system basis.  This is where
+	you can either enable user or group quotas or both for all of your
+	file systems.</para>
+
+      <para>To enable per-user quotas on a file system, add the
+	<option>userquota</option> option to the options field in the
+	<filename>/etc/fstab</filename> entry for the file system you want
+	to enable quotas on.  For example:</para>
+
+      <programlisting>/dev/da1s2g   /home    ufs rw,userquota 1 2</programlisting>
+
+      <para>Similarly, to enable group quotas, use the
+	<option>groupquota</option> option instead of
+	<option>userquota</option>.  To enable both user and
+	group quotas, change the entry as follows:</para>
+
+      <programlisting>/dev/da1s2g    /home    ufs rw,userquota,groupquota 1 2</programlisting>
+
+      <para>By default, the quota files are stored in the root directory of
+	the file system with the names <filename>quota.user</filename> and
+	<filename>quota.group</filename> for user and group quotas
+	respectively.  See &man.fstab.5; for more
+	information.  Even though the &man.fstab.5; manual page says that
+	you can specify
+	an alternate location for the quota files, this is not recommended
+	because the various quota utilities do not seem to handle this
+	properly.</para>
+
+      <para>At this point you should reboot your system with your new
+	kernel.  <filename>/etc/rc</filename> will automatically run the
+	appropriate commands to  create the initial quota files for all of
+	the quotas you enabled in <filename>/etc/fstab</filename>, so
+	there is no need to manually create any zero length quota
+	files.</para>
+
+      <para>In the normal course of operations you should not be required
+	to run the &man.quotacheck.8;,
+	&man.quotaon.8;, or &man.quotaoff.8;
+	commands manually.  However, you may want to read their manual pages
+	just to be familiar with their operation.</para>
+    </sect2>
+
+    <sect2>
+      <title>Setting Quota Limits</title>
+      <indexterm>
+        <primary>disk quotas</primary>
+        <secondary>limits</secondary>
+      </indexterm>
+
+      <para>Once you have configured your system to enable quotas, verify
+	that they really are enabled.  An easy way to do this is to
+	run:</para>
+
+      <screen>&prompt.root; <userinput>quota -v</userinput></screen>
+
+      <para>You should see a one line summary of disk usage and current
+	quota limits for each file system that quotas are enabled
+	on.</para>
+
+      <para>You are now ready to start assigning quota limits with the
+	&man.edquota.8; command.</para>
+
+      <para>You have several options on how to enforce limits on the
+	amount of disk space a user or group may allocate, and how many
+	files they may create.  You may limit allocations based on disk
+	space (block quotas) or number of files (inode quotas) or a
+	combination of both.  Each of these limits are further broken down
+	into two categories: hard and soft limits.</para>
+
+      <indexterm><primary>hard limit</primary></indexterm>
+      <para>A hard limit may not be exceeded.  Once a user reaches his
+	hard limit he may not make any further allocations on the file
+	system in question.  For example, if the user has a hard limit of
+	500 kbytes on a file system and is currently using 490 kbytes, the
+	user can only allocate an additional 10 kbytes.  Attempting to
+	allocate an additional 11 kbytes will fail.</para>
+
+      <indexterm><primary>soft limit</primary></indexterm>
+      <para>Soft limits, on the other hand, can be exceeded for a limited
+	amount of time.  This period of time is known as the grace period,
+	which is one week by default.  If a user stays over his or her
+	soft limit longer than the grace period, the soft limit will
+	turn into a hard limit and no further allocations will be allowed.
+	When the user drops back below the soft limit, the grace period
+	will be reset.</para>
+
+      <para>The following is an example of what you might see when you run
+	the &man.edquota.8; command.  When the
+	&man.edquota.8; command is invoked, you are placed into
+	the editor specified by the <envar>EDITOR</envar> environment
+	variable, or in the <application>vi</application> editor if the
+	<envar>EDITOR</envar> variable is not set, to allow you to edit
+	the quota limits.</para>
+
+      <screen>&prompt.root; <userinput>edquota -u test</userinput></screen>
+
+      <programlisting>Quotas for user test:
+/usr: kbytes in use: 65, limits (soft = 50, hard = 75)
+        inodes in use: 7, limits (soft = 50, hard = 60)
+/usr/var: kbytes in use: 0, limits (soft = 50, hard = 75)
+        inodes in use: 0, limits (soft = 50, hard = 60)</programlisting>
+
+      <para>You will normally see two lines for each file system that has
+	quotas enabled.  One line for the block limits, and one line for
+	inode limits.  Simply change the value you want updated to modify
+	the quota limit.  For example, to raise this user's block limit
+	from a soft limit of 50 and a hard limit of 75 to a soft limit of
+	500 and a hard limit of 600, change:</para>
+
+      <programlisting>/usr: kbytes in use: 65, limits (soft = 50, hard = 75)</programlisting>
+
+      <para>to:</para>
+
+      <programlisting>/usr: kbytes in use: 65, limits (soft = 500, hard = 600)</programlisting>
+
+      <para>The new quota limits will be in place when you exit the
+	editor.</para>
+
+      <para>Sometimes it is desirable to set quota limits on a range of
+	UIDs.  This can be done by use of the <option>-p</option> option
+	on the &man.edquota.8; command.  First, assign the
+	desired quota limit to a user, and then run
+	<command>edquota -p protouser startuid-enduid</command>.  For
+	example, if user <username>test</username> has the desired quota
+	limits, the following command can be used to duplicate those quota
+	limits for UIDs 10,000 through 19,999:</para>
+
+      <screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen>
+
+      <para>For more information see &man.edquota.8; manual page.</para>
+    </sect2>
+
+    <sect2>
+      <title>Checking Quota Limits and Disk Usage</title>
+      <indexterm>
+        <primary>disk quotas</primary>
+        <secondary>checking</secondary>
+      </indexterm>
+
+      <para>You can use either the &man.quota.1; or the
+	&man.repquota.8; commands to check quota limits and
+	disk usage.  The &man.quota.1; command can be used to
+	check individual user or group quotas and disk usage.  A user
+	may only examine his own quota, and the quota of a group he
+	is a member of. Only the super-user may view all user and group
+	quotas.  The
+	&man.repquota.8; command can be used to get a summary
+	of all quotas and disk usage for file systems with quotas
+	enabled.</para>
+
+      <para>The following is some sample output from the
+	<command>quota -v</command> command for a user that has quota
+	limits on two file systems.</para>
+
+      <programlisting>Disk quotas for user test (uid 1002):
+     Filesystem  usage    quota   limit   grace   files   quota   limit   grace
+           /usr      65*     50      75   5days       7      50      60
+       /usr/var       0      50      75               0      50      60</programlisting>
+
+      <indexterm><primary>grace period</primary></indexterm>
+      <para>On the <filename>/usr</filename> file system in the above
+	example, this user is currently 15 kbytes over the soft limit of
+	50 kbytes and has 5 days of the grace period left.  Note the
+	asterisk <literal>*</literal> which indicates that the user is
+	currently over his quota limit.</para>
+
+      <para>Normally file systems that the user is not using any disk
+	space on will not show up in the output from the
+	&man.quota.1; command, even if he has a quota limit
+	assigned for that file system.  The <option>-v</option> option
+	will display those file systems, such as the
+	<filename>/usr/var</filename> file system in the above
+	example.</para>
+    </sect2>
+
+    <sect2>
+      <title>Quotas over NFS</title>
+      <indexterm><primary>NFS</primary></indexterm>
+
+      <para>Quotas are enforced by the quota subsystem on the NFS server.
+	The &man.rpc.rquotad.8; daemon makes quota information available
+	to the &man.quota.1; command on NFS clients, allowing users on
+	those machines to see their quota statistics.</para>
+
+      <para>Enable <command>rpc.rquotad</command> in
+	<filename>/etc/inetd.conf</filename> like so:</para>
+
+      <programlisting>rquotad/1      dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad</programlisting>
+
+      <para>Now restart <command>inetd</command>:</para>
+
+      <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
+    </sect2>
+  </sect1>
+
+
+  <sect1 id="disks-encrypting">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Lucky</firstname>
+	  <surname>Green</surname>
+	  <contrib>Contributed by </contrib>
+	  <affiliation>
+	    <address><email>shamrock@cypherpunks.to</email></address>
+	  </affiliation>
+	</author>
+      </authorgroup>
+      <!-- 11 MARCH 2003 -->
+    </sect1info>
+
+    <title>Encrypting Disk Partitions</title>
+    <indexterm>
+      <primary>disks</primary>
+      <secondary>encrypting</secondary></indexterm>
+
+    <para>FreeBSD offers excellent online protections against
+      unauthorized data access.  File permissions and Mandatory
+      Access Control (MAC) (see <xref linkend="mac">) help prevent
+      unauthorized third-parties from accessing data while the operating
+      system is active and the computer is powered up. However,
+      the permissions enforced by the operating system are irrelevant if an
+      attacker has physical access to a computer and can simply move
+      the computer's hard drive to another system to copy and analyze
+      the sensitive data.</para>
+
+    <para>Regardless of how an attacker may have come into possession of
+      a hard drive or powered-down computer, both <application>GEOM
+      Based Disk Encryption (gbde)</application> and
+      <command>geli</command> cryptographic subsystems in &os; are able
+      to protect the data on the computer's file systems against even
+      highly-motivated attackers with significant resources. Unlike
+      cumbersome encryption methods that encrypt only individual files,
+      <command>gbde</command> and <command>geli</command> transparently
+      encrypt entire file systems. No cleartext ever touches the hard
+      drive's platter.</para>
+
+    <sect2>
+      <title>Disk Encryption with <application>gbde</application></title>
+
+      <procedure>
+	<step>
+	  <title>Become <username>root</username></title>
+
+	  <para>Configuring <application>gbde</application> requires
+	    super-user privileges.</para>
+
+	  <screen>&prompt.user; <userinput>su -</userinput>
+Password:</screen>
+	</step>
+
+	<step>
+	  <title>Add &man.gbde.4; Support to the Kernel Configuration File</title>
+
+	  <para>Add the following line to the kernel configuration
+	    file:</para>
+
+	  <para><literal>options GEOM_BDE</literal></para>
+
+	  <para>Rebuild the kernel as described in <xref
+	    linkend="kernelconfig">.</para>
+
+	  <para>Reboot into the new kernel.</para>
+	</step>
+      </procedure>
+
+    <sect3>
+      <title>Preparing the Encrypted Hard Drive</title>
+
+      <para>The following example assumes that you are adding a new hard
+	drive to your system that will hold a single encrypted partition.
+	This partition will be mounted as <filename>/private</filename>.
+	<application>gbde</application> can also be used to encrypt
+	<filename>/home</filename> and <filename>/var/mail</filename>, but
+	this requires more complex instructions which exceed the scope of
+	this introduction.</para>
+
+      <procedure>
+	<step>
+	  <title>Add the New Hard Drive</title>
+
+	  <para>Install the new drive to the system as explained in <xref
+	    linkend="disks-adding">. For the purposes of this example,
+	    a new hard drive partition has been added as
+	    <filename>/dev/ad4s1c</filename>. The
+	    <filename>/dev/ad0s1<replaceable>*</replaceable></filename>
+	    devices represent existing standard FreeBSD partitions on
+	    the example system.</para>
+
+	  <screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
+/dev/ad0        /dev/ad0s1b     /dev/ad0s1e     /dev/ad4s1
+/dev/ad0s1      /dev/ad0s1c     /dev/ad0s1f     /dev/ad4s1c
+/dev/ad0s1a     /dev/ad0s1d     /dev/ad4</screen>
+	</step>
+
+	<step>
+	  <title>Create a Directory to Hold gbde Lock Files</title>
+
+	  <screen>&prompt.root; <userinput>mkdir /etc/gbde</userinput></screen>
+
+	  <para>The <application>gbde</application> lock file contains
+	    information that <application>gbde</application> requires to
+	    access encrypted partitions. Without access to the lock file,
+	    <application>gbde</application> will not be able to decrypt
+	    the data contained in the encrypted partition without
+	    significant manual intervention which is not supported by the
+	    software. Each encrypted partition uses a separate lock
+	    file.</para>
+	</step>
+
+	<step>
+	  <title>Initialize the gbde Partition</title>
+
+	  <para>A <application>gbde</application> partition must be
+	    initialized before it can be used. This initialization needs to
+	    be performed only once:</para>
+
+	  <screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c</userinput></screen>
+
+	  <para>&man.gbde.8; will open your editor, permitting you to set
+	    various configuration options in a template. For use with UFS1
+	    or UFS2, set the sector_size to 2048:</para>
+
+	  <programlisting>$<!-- This is not the space you are looking
+for-->FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/20 11:16:13 phk Exp $
+#
+# Sector size is the smallest unit of data which can be read or written.
+# Making it too small decreases performance and decreases available space.
+# Making it too large may prevent filesystems from working.  512 is the
+# minimum and always safe.  For UFS, use the fragment size
+#
+sector_size     =       2048
+[...]
+</programlisting>
+
+	  <para>&man.gbde.8; will ask you twice to type the passphrase that
+	    should be used to secure the data. The passphrase must be the
+	    same both times. <application>gbde</application>'s ability to
+	    protect your data depends entirely on the quality of the
+	    passphrase that you choose.
+	  <footnote>
+          <para>For tips on how to select a secure passphrase that is easy
+	    to remember, see the <ulink
+	    url="http://world.std.com/~reinhold/diceware.html">Diceware
+	    Passphrase</ulink> website.</para></footnote></para>
+
+	  <para>The <command>gbde init</command> command creates a lock
+	    file for your <application>gbde</application> partition that in
+	    this example is stored as
+	    <filename>/etc/gbde/ad4s1c</filename>.</para>
+
+	  <caution>
+	    <para><application>gbde</application> lock files
+	      <emphasis>must</emphasis> be backed up together with the
+	      contents of any encrypted partitions. While deleting a lock
+	      file alone cannot prevent a determined attacker from
+	      decrypting a <application>gbde</application> partition,
+	      without the lock file, the legitimate owner will be unable
+	      to access the data on the encrypted partition without a
+	      significant amount of work that is totally unsupported by
+	      &man.gbde.8; and its designer.</para>
+	  </caution>
+	</step>
+
+	<step>
+	  <title>Attach the Encrypted Partition to the Kernel</title>
+
+	  <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</userinput></screen>
+
+	  <para> You will be asked to provide the passphrase that you
+	    selected during the initialization of the encrypted partition.
+	    The new encrypted device will show up in
+	    <filename>/dev</filename> as
+	    <filename>/dev/device_name.bde</filename>:</para>
+
+	  <screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
+/dev/ad0        /dev/ad0s1b     /dev/ad0s1e     /dev/ad4s1
+/dev/ad0s1      /dev/ad0s1c     /dev/ad0s1f     /dev/ad4s1c
+/dev/ad0s1a     /dev/ad0s1d     /dev/ad4        /dev/ad4s1c.bde</screen>
+	</step>
+
+	<step>
+	  <title>Create a File System on the Encrypted Device</title>
+
+	  <para>Once the encrypted device has been attached to the kernel,
+	    you can create a file system on the device. To create a file
+	    system on the encrypted device, use &man.newfs.8;. Since it is
+	    much faster to initialize a new UFS2 file system than it is to
+	    initialize the old UFS1 file system, using &man.newfs.8; with
+	    the <option>-O2</option> option is recommended.</para>
+
+	  <screen>&prompt.root; <userinput>newfs -U -O2 /dev/ad4s1c.bde</userinput></screen>
+
+	  <note>
+	    <para>The &man.newfs.8; command must be performed on an
+	      attached <application>gbde</application> partition which
+	      is identified by a
+	      <filename><replaceable>*</replaceable>.bde</filename>
+	      extension to the device name.</para>
+	  </note>
+	</step>
+
+	<step>
+	  <title>Mount the Encrypted Partition</title>
+
+	  <para>Create a mount point for the encrypted file system.</para>
+
+	  <screen>&prompt.root; <userinput>mkdir /private</userinput></screen>
+
+	  <para>Mount the encrypted file system.</para>
+
+	  <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
+	</step>
+
+	<step>
+	  <title>Verify That the Encrypted File System is Available</title>
+
+	  <para>The encrypted file system should now be visible to
+	    &man.df.1; and be available for use.</para>
+
+	  <screen>&prompt.user; <userinput>df -H</userinput>
+Filesystem        Size   Used  Avail Capacity  Mounted on
+/dev/ad0s1a      1037M    72M   883M     8%    /
+/devfs            1.0K   1.0K     0B   100%    /dev
+/dev/ad0s1f       8.1G    55K   7.5G     0%    /home
+/dev/ad0s1e      1037M   1.1M   953M     0%    /tmp
+/dev/ad0s1d       6.1G   1.9G   3.7G    35%    /usr
+/dev/ad4s1c.bde   150G   4.1K   138G     0%    /private</screen>
+	</step>
+      </procedure>
+    </sect3>
+
+    <sect3>
+      <title>Mounting Existing Encrypted File Systems</title>
+
+      <para>After each boot, any encrypted file systems must be
+	re-attached to the kernel, checked for errors, and mounted, before
+	the file systems can be used. The required commands must be
+	executed as user <username>root</username>.</para>
+
+      <procedure>
+	<step>
+	  <title>Attach the gbde Partition to the Kernel</title>
+
+	  <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c</userinput></screen>
+
+	  <para>You will be asked to provide the passphrase that you
+	    selected during initialization of the encrypted
+	    <application>gbde</application> partition.</para>
+	</step>
+
+	<step>
+	  <title>Check the File System for Errors</title>
+
+	  <para>Since encrypted file systems cannot yet be listed in
+	    <filename>/etc/fstab</filename> for automatic mounting, the
+	    file systems must be checked for errors by running &man.fsck.8;
+	    manually before mounting.</para>
+
+	  <screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput></screen>
+	</step>
+
+	<step>
+	  <title>Mount the Encrypted File System</title>
+
+	  <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
+
+	  <para>The encrypted file system is now available for use.</para>
+	</step>
+      </procedure>
+
+      <sect4>
+	<title>Automatically Mounting Encrypted Partitions</title>
+
+	<para>It is possible to create a script to automatically attach,
+	  check, and mount an encrypted partition, but for security reasons
+	  the script should not contain the &man.gbde.8; password. Instead,
+	  it is recommended that such scripts be run manually while
+	  providing the password via the console or &man.ssh.1;.</para>
+
+	<para>As of &os; 5.2-RELEASE, there is a new <filename>rc.d</filename> script
+	  provided.  Arguments for this script can be passed via
+	  &man.rc.conf.5;, for example:</para>
+
+	<screen>gbde_autoattach_all="YES"
+gbde_devices="ad4s1c"</screen>
+
+	<para>This will require that the <application>gbde</application>
+	  passphrase be entered at boot time.  After typing the correct
+	  passphrase, the <application>gbde</application> encrypted
+	  partition will be mounted automatically.  This can be very
+	  useful when using <application>gbde</application> on
+	  notebooks.</para>
+      </sect4>
+    </sect3>
+
+      <sect3>
+	<title>Cryptographic Protections Employed by gbde</title>
+
+	<para>&man.gbde.8; encrypts the sector payload using 128-bit AES in
+	  CBC mode.  Each sector on the disk is encrypted with a different
+	  AES key. For more information on <application>gbde</application>'s
+	  cryptographic design, including how the sector keys are derived
+	  from the user-supplied passphrase, see &man.gbde.4;.</para>
+      </sect3>
+
+      <sect3>
+	<title>Compatibility Issues</title>
+
+	<para>&man.sysinstall.8; is incompatible with
+	  <application>gbde</application>-encrypted devices. All
+	  <devicename><replaceable>*</replaceable>.bde</devicename> devices must be detached from the
+	  kernel before starting &man.sysinstall.8; or it will crash during
+	  its initial probing for devices. To detach the encrypted device
+	  used in our example, use the following command:</para>
+	<screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput></screen>
+
+      <para>Also note that, as &man.vinum.4; does not use the
+	&man.geom.4; subsystem, you cannot use
+	<application>gbde</application> with
+	<application>vinum</application> volumes.</para>
+      </sect3>
+
+    </sect2>
+
+    <sect2>
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Daniel</firstname>
+	    <surname>Gerzo</surname>
+	    <contrib>Contributed by </contrib>
+	  </author>
+	</authorgroup>
+	<!-- Date of writing: 28 November 2005 -->
+      </sect2info>
+
+      <title>Disk Encryption with <command>geli</command></title>
+
+      <para>A new cryptographic GEOM class is available as of &os; 6.0 -
+	<command>geli</command>.  It is currently being developed by
+	&a.pjd;.  <command>Geli</command> is different to
+	<command>gbde</command>; it offers different features and uses
+	a different scheme for doing cryptographic work.</para>
+
+      <para>The most important features of &man.geli.8; are:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Utilizes the &man.crypto.9; framework &mdash; when
+	    cryptographic hardware is available, <command>geli</command>
+	    will use it automatically.</para>
+	</listitem>
+	<listitem>
+	  <para>Supports multiple cryptographic algorithms (currently
+	     AES, Blowfish, and 3DES).</para>
+	</listitem>
+	<listitem>
+	  <para>Allows the root partition to be encrypted.  The
+	    passphrase used to access the encrypted root partition will
+	    be requested during the system boot.</para>
+	</listitem>
+	<listitem>
+	  <para>Allows the use of two independent keys (e.g. a
+	    <quote>key</quote> and a <quote>company key</quote>).</para>
+	</listitem>
+	<listitem>
+	  <para><command>geli</command> is fast - performs simple
+	    sector-to-sector encryption.</para>
+	</listitem>
+	<listitem>
+	  <para>Allows backup and restore of Master Keys.  When a user
+	    has to destroy his keys, it will be possible to get access
+	    to the data again by restoring keys from the backup.</para>
+	</listitem>
+	<listitem>
+	  <para>Allows to attach a disk with a random, one-time key
+	    &mdash; useful for swap partitions and temporary file
+	    systems.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>More <command>geli</command> features can be found in the
+	&man.geli.8; manual page.</para>
+
+      <para>The next steps will describe how to enable support for
+	<command>geli</command> in the &os; kernel and will explain how
+	to create a new <command>geli</command> encryption provider.  At
+	the end it will be demonstrated how to create an encrypted swap
+	partition using features provided by <command>geli</command>.</para>
+
+      <para>In order to use <command>geli</command>, you must be running
+	&os; 6.0-RELEASE or later.  Super-user privileges will be
+	required since modifications to the kernel are necessary.</para>
+
+      <procedure>
+	<step>
+	  <title>Adding <command>geli</command> Support to the Kernel
+	    Configuration File</title>
+
+	  <para>Add the following lines to the kernel configuration
+	    file:</para>
+
+	  <screen>options GEOM_ELI
+device crypto</screen>
+
+	  <para>Rebuild the kernel as described in <xref
+	    linkend="kernelconfig">.</para>
+
+	  <para>Alternatively, the <command>geli</command> module can
+	    be loaded at boot time.  Add the following line to the
+	    <filename>/boot/loader.conf</filename>:</para>
+
+	  <para><literal>geom_eli_load="YES"</literal></para>
+
+	  <para>&man.geli.8; should now be supported by the kernel.</para>
+	</step>
+
+	<step>
+	  <title>Generating the Master Key</title>
+
+	  <para>The following example will describe how to generate a
+	    key file, which will be used as part of the Master Key for
+	    the encrypted provider mounted under
+	    <filename role="directory">/private</filename>.  The key
+	    file will provide some random data used to encrypt the
+	    Master Key.  The Master Key will be protected by a
+	    passphrase as well.  Provider's sector size will be 4kB big.
+	    Furthermore, the discussion will describe how to attach the
+	    <command>geli</command> provider, create a file system on
+	    it, how to mount it, how to work with it, and finally how to
+	    detach it.</para>
+
+	  <para>It is recommended to use a bigger sector size (like 4kB) for
+	    better performance.</para>
+
+	  <para>The Master Key will be protected with a passphrase and
+	    the data source for key file will be
+	    <filename>/dev/random</filename>.  The sector size of
+	    <filename>/dev/da2.eli</filename>, which we call provider,
+	    will be 4kB.</para> 
+
+	  <screen>&prompt.root; <userinput>dd if=/dev/random of=/root/da2.key bs=64 count=1</userinput>
+&prompt.root; <userinput>geli init -s 4096 -K /root/da2.key /dev/da2</userinput>
+Enter new passphrase:
+Reenter new passphrase:</screen>
+
+	  <para>It is not mandatory that both a passphrase and a key
+	    file are used; either method of securing the Master Key can
+	    be used in isolation.</para>
+
+	  <para>If key file is given as <quote>-</quote>, standard
+	    input will be used.  This example shows how more than one
+	    key file can be used.</para>
+
+	  <screen>&prompt.root; <userinput>cat keyfile1 keyfile2 keyfile3 | geli init -K - /dev/da2</userinput></screen>
+	</step>
+
+	<step>
+	  <title>Attaching the Provider with the generated Key</title>
+
+	  <screen>&prompt.root; <userinput>geli attach -k /root/da2.key /dev/da2</userinput>
+Enter passphrase:</screen>
+
+	  <para>The new plaintext device will be named
+	    <filename>/dev/<replaceable>da2</replaceable>.eli</filename>.</para>
+
+	  <screen>&prompt.root; <userinput>ls /dev/da2*</userinput>
+/dev/da2  /dev/da2.eli</screen>
+	</step>
+
+	<step>
+	  <title>Creating the new File System</title>
+
+	  <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/da2.eli bs=1m</userinput>
+&prompt.root; <userinput>newfs /dev/da2.eli</userinput>
+&prompt.root; <userinput>mount /dev/da2.eli /private</userinput></screen>
+
+	<para>The encrypted file system should be visible to &man.df.1;
+	  and be available for use now.</para>
+
+	  <screen>&prompt.root; <userinput>df -H</userinput>
+Filesystem     Size   Used  Avail Capacity  Mounted on
+/dev/ad0s1a    248M    89M   139M    38%    /
+/devfs         1.0K   1.0K     0B   100%    /dev
+/dev/ad0s1f    7.7G   2.3G   4.9G    32%    /usr
+/dev/ad0s1d    989M   1.5M   909M     0%    /tmp
+/dev/ad0s1e    3.9G   1.3G   2.3G    35%    /var
+/dev/da2.eli   150G   4.1K   138G     0%    /private</screen>
+
+	</step>
+
+	<step>
+	  <title>Unmounting and Detaching the Provider</title>
+
+	  <para>Once the work on the encrypted partition is done, and
+	    the <filename role="directory">/private</filename> partition
+	    is no longer needed, it is prudent to consider unmounting
+	    and detaching the <command>geli</command> encrypted
+	    partition from the kernel.</para>
+
+	  <screen>&prompt.root; <userinput>umount /private</userinput>
+&prompt.root; <userinput>geli detach da2.eli</userinput></screen>
+	</step>
+      </procedure>
+
+      <para>More information about the use of &man.geli.8; can be
+        found in the manual page.</para>
+
+      <sect3>
+	<title>Using the <filename>geli</filename> <filename>rc.d</filename> Script</title>
+
+	<para><command>geli</command> comes with a <filename>rc.d</filename> script which
+	  can be used to simplify the usage of <command>geli</command>.
+	  An example of configuring <command>geli</command> through
+	  &man.rc.conf.5; follows:</para>
+
+	<screen>geli_devices="da2"
+geli_da2_flags="-p -k /root/da2.key"</screen>
+
+	<para>This will configure <filename>/dev/da2</filename> as a
+	  <command>geli</command> provider of which the Master Key file
+	  is located in <filename>/root/da2.key</filename>, and
+	  <command>geli</command> will not use a passphrase when
+	  attaching the provider (note that this can only be used if -P
+	  was given during the <command>geli</command> init phase).  The
+	  system will detach the <command>geli</command> provider from
+	  the kernel before the system shuts down.</para>
+
+	<para>More information about configuring <filename>rc.d</filename> is provided in the
+	  <link linkend="configtuning-rcd">rc.d</link> section of the
+	  Handbook.</para>
+      </sect3>
+    </sect2>	
+  </sect1>
+
+
+  <sect1 id="swap-encrypting">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Christian</firstname>
+	  <surname>Br&uuml;ffer</surname>
+	  <contrib>Written by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Encrypting Swap Space</title>
+    <indexterm>
+      <primary>swap</primary>
+      <secondary>encrypting</secondary>
+    </indexterm>
+
+    <para>Swap encryption in &os; is easy to configure and has been
+      available since &os; 5.3-RELEASE.  Depending on which version
+      of &os; is being used, different options are available
+      and configuration can vary slightly.  From &os; 6.0-RELEASE onwards,
+      the &man.gbde.8; or &man.geli.8; encryption systems can be used
+      for swap encryption.  With earlier versions, only &man.gbde.8; is
+      available.  Both systems use the <filename>encswap</filename>
+      <link linkend="configtuning-rcd">rc.d</link> script.</para>
+
+    <para>The previous section, <link linkend="disks-encrypting">Encrypting
+      Disk Partitions</link>, includes a short discussion on the different
+      encryption systems.</para>
+
+    <sect2>
+      <title>Why should Swap be Encrypted?</title>
+
+      <para>Like the encryption of disk partitions, encryption of swap space
+	is done to protect sensitive information.  Imagine an application
+	that e.g. deals with passwords.  As long as these passwords stay in
+	physical memory, all is well.  However, if the operating system starts
+	swapping out memory pages to free space for other applications, the
+	passwords may be written to the disk platters unencrypted and easy to
+	retrieve for an adversary.  Encrypting swap space can be a solution for
+	this scenario.</para>
+    </sect2>
+
+    <sect2>
+      <title>Preparation</title>
+
+      <note>
+	<para>For the remainder of this section, <devicename>ad0s1b</devicename>
+	  will be the swap partition.</para>
+      </note>
+
+      <para>Up to this point the swap has been unencrypted.  It is possible that
+	there are already passwords or other sensitive data on the disk platters
+	in cleartext.  To rectify this, the data on the swap partition should be
+	overwritten with random garbage:</para>
+
+      <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Swap Encryption with &man.gbde.8;</title>
+
+      <para>If &os; 6.0-RELEASE or newer is being used, the
+	<literal>.bde</literal> suffix should be added to the device in the
+	respective <filename>/etc/fstab</filename> swap line:</para>
+
+      <screen>
+# Device                Mountpoint      FStype  Options         Dump    Pass#
+/dev/ad0s1b.bde         none            swap    sw              0       0
+      </screen>
+
+      <para>For systems prior to &os; 6.0-RELEASE, the following line
+	in <filename>/etc/rc.conf</filename> is also needed:</para>
+
+      <programlisting>gbde_swap_enable="YES"</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Swap Encryption with &man.geli.8;</title>
+
+      <para>Alternatively, the procedure for using &man.geli.8; for swap
+	encryption is similar to that of using &man.gbde.8;.  The
+	<literal>.eli</literal> suffix should be added to the device in the
+	respective <filename>/etc/fstab</filename> swap line:</para>
+
+      <screen>
+# Device                Mountpoint      FStype  Options         Dump    Pass#
+/dev/ad0s1b.eli         none            swap    sw              0       0
+      </screen>
+
+      <para>&man.geli.8; uses the <acronym>AES</acronym> algorithm with
+	a key length of 256 bit by default.</para>
+
+      <para>Optionally, these defaults can be altered using the
+	<literal>geli_swap_flags</literal> option in
+	<filename>/etc/rc.conf</filename>.  The following line tells the
+	<filename>encswap</filename> rc.d script to create &man.geli.8; swap
+	partitions using the Blowfish algorithm with a key length of 128 bit,
+	a sectorsize of 4 kilobytes and the <quote>detach on last close</quote>
+	option set:</para>
+
+      <programlisting>geli_swap_flags="-a blowfish -l 128 -s 4096 -d"</programlisting>
+
+      <para>Please refer to the description of the <command>onetime</command> command
+	in the &man.geli.8; manual page for a list of possible options.</para>
+    </sect2>
+
+    <sect2>
+      <title>Verifying that it Works</title>
+
+      <para>Once the system has been rebooted, proper operation of the
+	encrypted swap can be verified using the
+	<command>swapinfo</command> command.</para>
+
+      <para>If &man.gbde.8; is being used:</para>
+
+      <screen>&prompt.user; <userinput>swapinfo</userinput>
+Device          1K-blocks     Used    Avail Capacity
+/dev/ad0s1b.bde    542720        0   542720     0%
+      </screen>
+
+      <para>If &man.geli.8; is being used:</para>
+
+      <screen>&prompt.user; <userinput>swapinfo</userinput>
+Device          1K-blocks     Used    Avail Capacity
+/dev/ad0s1b.eli    542720        0   542720     0%
+      </screen>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/eresources/Makefile b/pl_PL.ISO8859-2/books/handbook/eresources/Makefile
new file mode 100644
index 0000000000..cb030a0162
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/eresources/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	eresources/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/eresources/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/eresources/chapter.sgml
new file mode 100644
index 0000000000..4dceab8cdc
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/eresources/chapter.sgml
@@ -0,0 +1,1781 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<appendix id="eresources">
+  <title>Resources on the Internet</title>
+
+  <para>The rapid pace of FreeBSD progress makes print media impractical as a
+    means of following the latest developments.  Electronic resources are the
+    best, if not often the only, way stay informed of the latest advances.
+    Since FreeBSD is a volunteer effort, the user community itself also
+    generally serves as a <quote>technical support department</quote> of sorts,
+    with electronic mail and  USENET news being the most effective way of
+    reaching that community.</para>
+
+  <para>The most important points of contact with the FreeBSD user community
+    are outlined below.  If you are aware of other resources not mentioned
+    here, please send them to the &a.doc; so that they may also be
+    included.</para>
+
+  <sect1 id="eresources-mail">
+    <title>Mailing Lists</title>
+
+    <para>Though many of the FreeBSD development members read USENET, we
+      cannot always guarantee that we will get to your questions in a timely
+      fashion (or at all) if you post them only to one of the
+      <literal>comp.unix.bsd.freebsd.*</literal> groups.  By addressing your
+      questions to the appropriate mailing list you will reach both us and a
+      concentrated FreeBSD audience, invariably assuring a better (or at least
+      faster) response.</para>
+
+    <para>The charters for the various lists are given at the bottom of this
+      document.  <emphasis>Please read the charter before joining or sending
+	mail to any list</emphasis>.  Most of our list subscribers now receive
+      many hundreds of FreeBSD related messages every day, and by setting down
+      charters and rules for proper use we are striving to keep the
+      signal-to-noise ratio of the lists high. To do less would see the
+      mailing lists ultimately fail as an effective communications medium for
+      the project.</para>
+
+    <para>When in doubt about what list to post a question to, see <ulink
+      url="&url.articles.freebsd-questions;">How to get best results from
+        the FreeBSD-questions mailing list</ulink>.</para>
+
+    <para>Before posting to any list, please learn about how to best use
+      the mailing lists, such as how to help avoid frequently-repeated
+      discussions, by reading the <ulink url="&url.articles.mailing-list-faq;">
+        Mailing List Frequently Asked Questions</ulink> (FAQ) document.</para>
+
+    <para>Archives are kept for all of the mailing lists and can be searched
+      using the <ulink url="&url.base;/search/index.html">FreeBSD World
+	Wide Web server</ulink>.  The keyword searchable archive offers an
+      excellent way of finding answers to frequently asked questions and
+      should be consulted before posting a question.</para>
+
+    <sect2 id="eresources-summary">
+      <title>List Summary</title>
+
+      <para><emphasis>General lists:</emphasis> The following are general
+	lists which anyone is free (and encouraged) to join:</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>List</entry>
+	      <entry>Purpose</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>&a.cvsall.name;</entry>
+	      <entry>Changes made to the FreeBSD source tree</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.advocacy.name;</entry>
+	      <entry>FreeBSD Evangelism</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.announce.name;</entry>
+	      <entry>Important events and project milestones</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.arch.name;</entry>
+	      <entry>Architecture and design discussions</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.bugbusters.name;</entry>
+	      <entry>Discussions pertaining to the maintenance of the FreeBSD
+		problem report database and related tools</entry>
+	    </row>
+
+    	    <row>
+	      <entry>&a.bugs.name;</entry>
+	      <entry>Bug reports</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.chat.name;</entry>
+	      <entry>Non-technical items related to the FreeBSD
+		community</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.current.name;</entry>
+	      <entry>Discussion concerning the use of
+		&os.current;</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.isp.name;</entry>
+	      <entry>Issues for Internet Service Providers using
+		FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.jobs.name;</entry>
+	      <entry>FreeBSD employment and consulting
+		opportunities</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.policy.name;</entry>
+	      <entry>FreeBSD Core team policy decisions.  Low volume, and
+		read-only</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.questions.name;</entry>
+	      <entry>User questions and technical support</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.security-notifications.name;</entry>
+	      <entry>Security notifications</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.stable.name;</entry>
+	      <entry>Discussion concerning the use of
+		&os.stable;</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.test.name;</entry>
+	      <entry>Where to send your test messages instead of one of
+		the actual lists</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para><emphasis>Technical lists:</emphasis> The following lists are for
+	technical discussion.  You should read the charter for each list
+	carefully before joining or sending mail to one as there are firm
+	guidelines for their use and content.</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>List</entry>
+	      <entry>Purpose</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>&a.acpi.name;</entry>
+	      <entry>ACPI and power management development</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.afs.name;</entry>
+	      <entry>Porting AFS to FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.aic7xxx.name;</entry>
+	      <entry>Developing drivers for the &adaptec; AIC 7xxx</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.alpha.name;</entry>
+	      <entry>Porting FreeBSD to the Alpha</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.amd64.name;</entry>
+	      <entry>Porting FreeBSD to AMD64 systems</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.apache.name;</entry>
+	      <entry>Discussion about <application>Apache</application> related ports</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.arm.name;</entry>
+	      <entry>Porting FreeBSD to &arm; processors</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.atm.name;</entry>
+	      <entry>Using ATM networking with FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.audit.name;</entry>
+	      <entry>Source code audit project</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.binup.name;</entry>
+	      <entry>Design and development of the binary update system</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.bluetooth.name;</entry>
+	      <entry>Using &bluetooth; technology in FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.cluster.name;</entry>
+	      <entry>Using FreeBSD in a clustered environment</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.cvsweb.name;</entry>
+	      <entry>CVSweb maintenance</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.database.name;</entry>
+	      <entry>Discussing database use and development under
+		FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.doc.name;</entry>
+	      <entry>Creating FreeBSD related documents</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.drivers.name;</entry>
+	      <entry>Writing device drivers for &os;</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.eclipse.name;</entry>
+	      <entry>FreeBSD users of Eclipse IDE, tools, rich client
+	       applications and ports.</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.embedded.name;</entry>
+	      <entry>Using FreeBSD in embedded applications</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.emulation.name;</entry>
+	      <entry>Emulation of other systems such as
+		Linux/&ms-dos;/&windows;</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.firewire.name;</entry>
+	      <entry>FreeBSD &firewire; (iLink, IEEE 1394) technical
+		discussion</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.fs.name;</entry>
+	      <entry>File systems</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.geom.name;</entry>
+	      <entry>GEOM-specific discussions and implementations</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.gnome.name;</entry>
+	      <entry>Porting <application>GNOME</application> and <application>GNOME</application> applications</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.hackers.name;</entry>
+	      <entry>General technical discussion</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.hardware.name;</entry>
+	      <entry>General discussion of hardware for running
+		FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.i18n.name;</entry>
+	      <entry>FreeBSD Internationalization</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.ia32.name;</entry>
+	      <entry>FreeBSD on the IA-32 (&intel; x86) platform</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.ia64.name;</entry>
+	      <entry>Porting FreeBSD to &intel;'s upcoming IA64 systems</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.ipfw.name;</entry>
+	      <entry>Technical discussion concerning the redesign of the IP
+		firewall code</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.isdn.name;</entry>
+	      <entry>ISDN developers</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.java.name;</entry>
+	      <entry>&java; developers and people porting &jdk;s to
+		FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.kde.name;</entry>
+	      <entry>Porting <application>KDE</application> and <application>KDE</application> applications</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.lfs.name;</entry>
+	      <entry>Porting LFS to FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.libh.name;</entry>
+	      <entry>The second generation installation and package
+	         system</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.mips.name;</entry>
+	      <entry>Porting FreeBSD to &mips;</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.mobile.name;</entry>
+	      <entry>Discussions about mobile computing</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.mozilla.name;</entry>
+	      <entry>Porting <application>Mozilla</application> to FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.multimedia.name;</entry>
+	      <entry>Multimedia applications</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.newbus.name;</entry>
+	      <entry>Technical discussions about bus architecture</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.net.name;</entry>
+	      <entry>Networking discussion and TCP/IP source code</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.openoffice.name;</entry>
+	      <entry>Porting <application>OpenOffice.org</application> and
+		<application>&staroffice;</application> to FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.performance.name;</entry>
+	      <entry>Performance tuning questions for high
+		performance/load installations</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.perl.name;</entry>
+	      <entry>Maintenance of a number of
+		Perl-related ports</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.pf.name;</entry>
+	      <entry>Discussion and questions about the packet filter
+		firewall system</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.platforms.name;</entry>
+	      <entry>Concerning ports to non &intel; architecture
+		platforms</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.ports.name;</entry>
+	      <entry>Discussion of the Ports Collection</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.ports-bugs.name;</entry>
+	      <entry>Discussion of the ports bugs/PRs</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.ppc.name;</entry>
+	      <entry>Porting FreeBSD to the &powerpc;</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.proliant.name;</entry>
+	      <entry>Technical discussion of FreeBSD on HP ProLiant server platforms</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.python.name;</entry>
+	      <entry>FreeBSD-specific Python issues</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.qa.name;</entry>
+	      <entry>Discussion of Quality Assurance, usually pending a release</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.rc.name;</entry>
+	      <entry>Discussion related to the <filename>rc.d</filename> system and its development</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.realtime.name;</entry>
+	      <entry>Development of realtime extensions to FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.scsi.name;</entry>
+	      <entry>The SCSI subsystem</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.security.name;</entry>
+	      <entry>Security issues affecting FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.small.name;</entry>
+	      <entry>Using FreeBSD in embedded applications
+		(obsolete; use &a.embedded.name; instead)</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.smp.name;</entry>
+	      <entry>Design discussions for [A]Symmetric
+		MultiProcessing</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.sparc.name;</entry>
+	      <entry>Porting FreeBSD to &sparc; based systems</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.standards.name;</entry>
+	      <entry>FreeBSD's conformance to the C99 and the &posix;
+		standards</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.threads.name;</entry>
+	      <entry>Threading in FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.testing.name;</entry>
+	      <entry>FreeBSD Performance and Stability Tests</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.tokenring.name;</entry>
+	      <entry>Support Token Ring in FreeBSD</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.usb.name;</entry>
+	      <entry>Discussing &os; support for USB</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.vuxml.name;</entry>
+	      <entry>Discussion on VuXML infrastructure</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.x11.name;</entry>
+	      <entry>Maintenance and support of X11 on FreeBSD</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para><emphasis>Limited lists:</emphasis> The following lists are for
+	more specialized (and demanding) audiences and are probably not of
+        interest to the general public.  It is also a good idea to establish a
+        presence in the technical lists before joining one of these limited
+        lists so that you will understand the communications etiquette involved.</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>List</entry>
+	      <entry>Purpose</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>&a.hubs.name;</entry>
+	      <entry>People running mirror sites (infrastructural
+		support)</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.usergroups.name;</entry>
+	      <entry>User group coordination</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.vendors.name;</entry>
+	      <entry>Vendors pre-release coordination</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.www.name;</entry>
+	      <entry>Maintainers of <ulink url="&url.base;/index.html">www.FreeBSD.org</ulink></entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para><emphasis>Digest lists:</emphasis> All of the above lists
+	are available in a digest format.  Once subscribed to a list,
+	you can change your digest options in your account options
+	section.</para>
+
+      <para><emphasis>CVS lists:</emphasis> The following lists are for people
+	interested in seeing the log messages for changes to various areas of
+	the source tree.  They are <emphasis>Read-Only</emphasis> lists and
+	should not have mail sent to them.</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>List</entry>
+	      <entry>Source area</entry>
+	      <entry>Area Description (source for)</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>&a.cvsall.name;</entry>
+	      <entry><filename>/usr/(CVSROOT|doc|ports|projects|src)</filename></entry>
+	      <entry>All changes to any place in the tree (superset of other CVS commit lists)</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.cvs-doc.name;</entry>
+	      <entry><filename>/usr/(doc|www)</filename></entry>
+	      <entry>All changes to the doc and www trees</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.cvs-ports.name;</entry>
+	      <entry><filename>/usr/ports</filename></entry>
+	      <entry>All changes to the ports tree</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.cvs-projects.name;</entry>
+	      <entry><filename>/usr/projects</filename></entry>
+	      <entry>All changes to the projects tree</entry>
+	    </row>
+
+	    <row>
+	      <entry>&a.cvs-src.name;</entry>
+	      <entry><filename>/usr/src</filename></entry>
+	      <entry>All changes to the src tree</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+    </sect2>
+
+    <sect2 id="eresources-subscribe">
+      <title>How to Subscribe</title>
+
+      <para>To subscribe to a list, click on the list name above or
+        go to &a.mailman.lists.link;
+        and click on the list that you are interested in.  The list
+        page should contain all of the necessary subscription
+        instructions.</para>
+
+      <para>To actually post to a given list you simply send mail to
+	<email><replaceable>listname</replaceable>@FreeBSD.org</email>.  It will then
+	be redistributed to mailing list members world-wide.</para>
+
+      <para>To unsubscribe yourself from a list, click on the URL
+	found at the bottom of every email received from the list.  It
+	is also possible to send an email to
+	<email><replaceable>listname</replaceable>-unsubscribe@FreeBSD.org</email> to unsubscribe
+	yourself.</para>
+
+      <para>Again, we would like to request that you keep discussion in the
+	technical mailing lists on a technical track. If you are only
+	interested in important announcements then it is suggested that
+	you join the &a.announce;, which is intended only for infrequent
+	traffic.</para>
+    </sect2>
+
+    <sect2 id="eresources-charters">
+      <title>List Charters</title>
+
+      <para><emphasis>All</emphasis> FreeBSD mailing lists have certain basic
+	rules which must be adhered to by anyone using them. Failure to comply
+	with these guidelines will result in two (2) written warnings from the
+	FreeBSD Postmaster <email>postmaster@FreeBSD.org</email>, after which,
+	on a third offense, the poster will removed from all FreeBSD mailing
+	lists and filtered from further posting to them. We regret that such
+	rules and measures are necessary at all, but today's Internet is a
+	pretty harsh environment, it would seem, and many fail to appreciate
+	just how fragile some of its mechanisms are.</para>
+
+      <para>Rules of the road:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>The topic of any posting should adhere to the basic charter of
+	    the list it is posted to, e.g. if the list is about technical
+	    issues then your posting should contain technical discussion.
+	    Ongoing irrelevant chatter or flaming only detracts from the value
+	    of the mailing list for everyone on it and will not be tolerated.
+	    For free-form discussion on no particular topic, the &a.chat;
+	    is freely available and should be used instead.</para>
+	</listitem>
+
+	<listitem>
+	  <para>No posting should be made to more than 2 mailing lists, and
+	    only to 2 when a clear and obvious need to post to both lists
+	    exists.  For most lists, there is already a great deal of
+	    subscriber overlap and except for the most esoteric mixes (say
+	    <quote>-stable &amp; -scsi</quote>), there really is no reason to post to more
+	    than one list at a time.  If a message is sent to you in such a
+	    way that multiple mailing lists appear on the
+	    <literal>Cc</literal> line then the <literal>Cc</literal>
+	    line should also be trimmed before sending it out again.
+	    <emphasis>You are still responsible for your
+	      own cross-postings, no matter who the originator might have
+	      been.</emphasis></para>
+	</listitem>
+
+	<listitem>
+	  <para>Personal attacks and profanity (in the context of an argument)
+	    are not allowed, and that includes users and developers alike.
+	    Gross breaches of netiquette, like excerpting or reposting private
+	    mail when permission to do so was not and would not be
+	    forthcoming, are frowned upon but not specifically enforced.
+	    <emphasis>However</emphasis>, there are also very few cases where
+	    such content would fit within the charter of a list and it would
+	    therefore probably rate a warning (or ban) on that basis
+	    alone.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Advertising of non-FreeBSD related products or services is
+	    strictly prohibited and will result in an immediate ban if it is
+	    clear that the offender is advertising by spam.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para><emphasis>Individual list charters:</emphasis></para>
+
+      <variablelist>
+
+	<varlistentry>
+	  <term>&a.acpi.name;</term>
+
+	  <listitem>
+	    <para><emphasis>ACPI and power management
+	       development</emphasis></para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.afs.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Andrew File System</emphasis></para>
+
+	    <para>This list is for discussion on porting and using AFS from
+	      CMU/Transarc</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.announce.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Important events / milestones</emphasis></para>
+
+	    <para>This is the mailing list for people interested only in
+	      occasional announcements of significant FreeBSD events. This
+	      includes announcements about snapshots and other releases.  It
+	      contains announcements of new FreeBSD capabilities.  It may
+	      contain calls for volunteers etc. This is a low volume, strictly
+	      moderated mailing list.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.arch.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Architecture and design
+		discussions</emphasis></para>
+
+            <para>This list is for discussion of the FreeBSD
+	      architecture.  Messages will mostly be kept strictly
+	      technical in nature.  Examples of suitable topics
+	      are:</para>
+
+	    <itemizedlist>
+	      <listitem>
+		<para>How to re-vamp the build system to have several
+		  customized builds running at the same time.</para>
+	      </listitem>
+
+	      <listitem>
+		<para>What needs to be fixed with VFS to make Heidemann layers
+		  work.</para>
+		</listitem>
+
+	      <listitem>
+		<para>How do we change the device driver interface to be able
+		  to use the same drivers cleanly on many buses and
+		  architectures.</para>
+	      </listitem>
+
+	      <listitem>
+		<para>How to write a network driver.</para>
+	      </listitem>
+	    </itemizedlist>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.audit.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Source code audit project</emphasis></para>
+
+	    <para>This is the mailing list for the FreeBSD source code
+	      audit project.  Although this was originally intended for
+	      security-related changes, its charter has been expanded to
+	      review any code changes.</para>
+
+	    <para>This list is very heavy on patches, and is probably of no
+	      interest to the average FreeBSD user.  Security discussions
+	      not related to a particular code change are held on
+	      freebsd-security.  Conversely, all developers are encouraged
+	      to send their patches here for review, especially if they
+	      touch a part of the system where a bug may adversely affect
+	      the integrity of the system.</para>
+
+<!-- I can't actually find a charter for this, but there's this email: http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=223347+225804+/usr/local/www/db/text/2000/cvs-all/20001210.cvs-all -->
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.binup.name;</term>
+
+	  <listitem>
+	    <para><emphasis>FreeBSD Binary Update Project</emphasis></para>
+
+	    <para>This list exists to provide discussion for the binary
+	      update system, or <application>binup</application>.
+	      Design issues, implementation details,
+	      patches, bug reports, status reports, feature requests, commit
+	      logs, and all other things related to
+	      <application>binup</application> are fair game.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.bluetooth.name;</term>
+
+	  <listitem>
+	    <para><emphasis>&bluetooth; in FreeBSD</emphasis></para>
+
+	    <para>This is the forum where FreeBSD's &bluetooth; users
+              congregate.  Design issues, implementation details,
+              patches, bug reports, status reports, feature requests,
+              and all matters related to &bluetooth; are fair
+              game.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.bugbusters.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Coordination of the Problem Report handling effort</emphasis></para>
+
+	    <para>The purpose of this list is to serve as a coordination and
+	      discussion forum for the Bugmeister, his Bugbusters, and any other
+	      parties who have a genuine interest in the PR database.  This list
+	      is not for discussions about specific bugs, patches or PRs.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.bugs.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Bug reports</emphasis></para>
+
+	    <para>This is the mailing list for reporting bugs in FreeBSD.
+	      Whenever possible, bugs should be submitted using the
+		&man.send-pr.1;
+	      command or the <ulink
+		url="&url.base;/send-pr.html">WEB
+		interface</ulink> to it.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.chat.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Non technical items related to the FreeBSD
+		community</emphasis></para>
+
+	    <para>This list contains the overflow from the other lists about
+	      non-technical, social information.  It includes discussion about
+	      whether Jordan looks like a toon ferret or not, whether or not
+	      to type in capitals, who is drinking too much coffee, where the
+	      best beer is brewed, who is brewing beer in their basement, and
+	      so on.  Occasional announcements of important events (such as
+	      upcoming parties, weddings, births, new jobs, etc) can be made
+	      to the technical lists, but the follow ups should be directed to
+	      this -chat list.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.core.name;</term>
+
+	  <listitem>
+	    <para><emphasis>FreeBSD core team</emphasis></para>
+
+	    <para>This is an internal mailing list for use by the core
+	      members.  Messages can be sent to it when a serious
+	      FreeBSD-related matter requires arbitration or high-level
+	      scrutiny.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.current.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussions about the use of
+		&os.current;</emphasis></para>
+
+	    <para>This is the mailing list for users of &os.current;.  It
+	      includes warnings about new features coming out in -CURRENT that
+	      will affect the users, and instructions on steps that must be
+	      taken to remain -CURRENT.  Anyone running <quote>CURRENT</quote>
+	      must subscribe to this list.  This is a technical mailing list
+	      for which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.cvsweb.name;</term>
+
+	  <listitem>
+	    <para><emphasis>FreeBSD CVSweb Project</emphasis></para>
+
+	    <para>Technical discussions about use, development and maintenance
+	      of FreeBSD-CVSweb.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.doc.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Documentation project</emphasis></para>
+
+	    <para>This mailing list is for the discussion of issues and
+	      projects related to the creation of documentation for FreeBSD.
+	      The members of this mailing list are collectively referred to as
+	      <quote>The FreeBSD Documentation Project</quote>.  It is an open
+	      list; feel free to join and contribute!</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.drivers.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Writing device drivers for &os;</emphasis></para>
+
+	    <para>This is a forum for technical discussions related to
+		device drivers on &os;.  It is primarily a place
+		for device driver writers to ask questions about
+		how to write device drivers using the APIs in the
+		&os; kernel.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.eclipse.name;</term>
+
+	  <listitem>
+	    <para><emphasis>&os; users of Eclipse IDE, tools, rich
+	      client applications and ports.</emphasis></para>
+
+	    <para>The intention of this list is to provide mutual
+	      support for everything to do with choosing, installing,
+	      using, developing and maintaining the Eclipse IDE,
+	      tools, rich client applications on the &os; platform and
+	      assisting with the porting of Eclipse IDE and plugins to
+	      the &os; environment.</para>
+
+	    <para>The intention is also to facilitate exchange of
+	      information between the Eclipse community and the &os;
+	      community to the mutual benefit of both.</para>
+
+	    <para>Although this list is focused primarily on the needs
+	      of Eclipse users it will also provide a forum for those
+	      who would like to develop &os; specific applications
+	      using the Eclipse framework.
+	    </para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.embedded.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Using FreeBSD in embedded
+	      applications</emphasis></para>
+
+	    <para>This list discusses topics related to using FreeBSD in
+	      embedded systems.  This is a technical mailing list for which
+	      strictly technical content is expected.  For the purpose of
+	      this list we define embedded systems as those computing
+	      devices which are not desktops and which usually serve a
+	      single purpose as opposed to being general computing
+	      environments.  Examples include, but are not limited to,
+	      all kinds of phone handsets, network equipment such as
+	      routers, switches and PBXs, remote measuring equipment,
+	      PDAs, Point Of Sale systems, and so on.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.emulation.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Emulation of other systems such as
+		Linux/&ms-dos;/&windows;</emphasis></para>
+
+	    <para>This is a forum for technical discussions related to
+	      running programs written for other operating systems on &os;.
+	    </para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.firewire.name;</term>
+
+	  <listitem>
+	    <para><emphasis>&firewire; (iLink, IEEE 1394)</emphasis></para>
+
+	    <para>This is a mailing list for discussion of the design
+	      and implementation of a &firewire; (aka IEEE 1394 aka
+	      iLink) subsystem for FreeBSD.  Relevant topics
+	      specifically include the standards, bus devices and
+	      their protocols, adapter boards/cards/chips sets, and
+	      the architecture and implementation of code for their
+	      proper support.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.fs.name;</term>
+
+	  <listitem>
+	    <para><emphasis>File systems</emphasis></para>
+
+	    <para>Discussions concerning FreeBSD file systems.  This is a
+	      technical mailing list for which strictly technical content is
+	      expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.geom.name;</term>
+
+	  <listitem>
+	    <para><emphasis>GEOM</emphasis></para>
+
+	    <para>Discussions specific to GEOM and related implementations.
+	      This is a technical mailing list for which strictly technical
+	      content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.gnome.name;</term>
+
+	  <listitem>
+	    <para><emphasis>GNOME</emphasis></para>
+
+	    <para>Discussions concerning The <application>GNOME</application> Desktop Environment for
+              FreeBSD systems.  This is a technical mailing list for
+	      which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.ipfw.name;</term>
+
+	  <listitem>
+	    <para><emphasis>IP Firewall</emphasis></para>
+
+	    <para>This is the forum for technical discussions concerning the
+	      redesign of the IP firewall code in FreeBSD.  This is a
+	      technical mailing list for which strictly technical content is
+	      expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.ia64.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Porting FreeBSD to IA64</emphasis></para>
+
+	    <para>This is a technical mailing list for individuals
+            actively working on porting FreeBSD to the IA-64 platform
+            from &intel;, to bring up problems or discuss alternative
+            solutions.  Individuals interested in following the
+            technical discussion are also welcome.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.isdn.name;</term>
+
+	  <listitem>
+	    <para><emphasis>ISDN Communications</emphasis></para>
+
+	    <para>This is the mailing list for people discussing the
+	      development of ISDN support for FreeBSD.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.java.name;</term>
+
+	  <listitem>
+	    <para><emphasis>&java; Development</emphasis></para>
+
+	    <para>This is the mailing list for people discussing the
+	      development of significant &java; applications for FreeBSD and the
+	      porting and maintenance of &jdk;s.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry id="eresources-charters-jobs">
+	  <term>&a.jobs.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Jobs offered and sought</emphasis></para>
+
+	    <para>This is a forum for posting employment notices and
+	      resumes specifically related to &os;, e.g. if you are
+	      seeking &os;-related employment or have a job involving
+	      &os; to advertise then this is the right place.  This is
+	      <emphasis>not</emphasis> a mailing list for general
+	      employment issues since adequate forums for that
+	      already exist elsewhere.</para>
+
+	    <para>Note that this list, like other <hostid role="domainname">FreeBSD.org</hostid> mailing
+	      lists, is distributed worldwide.  Thus, you need to be
+	      clear about location and the extent to which
+	      telecommuting or assistance with relocation is
+	      available.</para>
+
+	    <para>Email should use open formats only &mdash;
+	      preferably plain text, but basic Portable Document
+	      Format (<acronym>PDF</acronym>), HTML, and a few others
+	      are acceptable to many readers.  Closed formats such as
+	      &microsoft; Word (<filename>.doc</filename>) will be
+	      rejected by the mailing list server.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.kde.name;</term>
+
+	  <listitem>
+	    <para><emphasis>KDE</emphasis></para>
+
+	    <para>Discussions concerning <application>KDE</application> on
+              FreeBSD systems.  This is a technical mailing list for
+	      which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.hackers.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Technical discussions</emphasis></para>
+
+	    <para>This is a forum for technical discussions related to
+	      FreeBSD.  This is the primary technical mailing list.  It is for
+	      individuals actively working on FreeBSD, to bring up problems or
+	      discuss alternative solutions.  Individuals interested in
+	      following the technical discussion are also welcome.  This is a
+	      technical mailing list for which strictly technical content is
+	      expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.hardware.name;</term>
+
+	  <listitem>
+	    <para><emphasis>General discussion of FreeBSD
+		hardware</emphasis></para>
+
+	    <para>General discussion about the types of hardware that FreeBSD
+	      runs on, various problems and suggestions concerning what to buy
+	      or avoid.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.hubs.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Mirror sites</emphasis></para>
+
+	    <para>Announcements and discussion for people who run FreeBSD
+	      mirror sites.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.isp.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Issues for Internet Service
+		Providers</emphasis></para>
+
+	    <para>This mailing list is for discussing topics relevant to
+	      Internet Service Providers (ISPs) using FreeBSD.  This is a
+	      technical mailing list for which strictly technical content is
+	      expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.openoffice.name;</term>
+
+	  <listitem>
+	    <para><emphasis>OpenOffice.org</emphasis></para>
+
+	    <para>Discussions concerning the porting and maintenance
+	      of <application>OpenOffice.org</application> and
+	      <application>&staroffice;</application>.</para>
+	   </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.performance.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussions about tuning or speeding up FreeBSD</emphasis></para>
+
+	    <para>This mailing list exists to provide a place for
+	      hackers, administrators, and/or concerned parties to
+	      discuss performance related topics pertaining to
+	      FreeBSD.  Acceptable topics includes talking about
+	      FreeBSD installations that are either under high load,
+	      are experiencing performance problems, or are pushing
+	      the limits of FreeBSD.  Concerned parties that are
+	      willing to work toward improving the performance of
+	      FreeBSD are highly encouraged to subscribe to this list.
+	      This is a highly technical list ideally suited for
+	      experienced FreeBSD users, hackers, or administrators
+	      interested in keeping FreeBSD fast, robust, and
+	      scalable.  This list is not a question-and-answer list
+	      that replaces reading through documentation, but it is a
+	      place to make contributions or inquire about unanswered
+	      performance related topics.</para>
+
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.pf.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussion and questions about the packet filter
+		firewall system</emphasis></para>
+
+	    <para>Discussion concerning the packet filter (pf) firewall
+	      system in terms of FreeBSD. Technical discussion and user
+	      questions are both welcome. This list is also a place to
+	      discuss the ALTQ QoS framework.</para>
+
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.platforms.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Porting to Non &intel; platforms</emphasis></para>
+
+	    <para>Cross-platform FreeBSD issues, general discussion and
+	      proposals for non &intel; FreeBSD ports.  This is a technical
+	      mailing list for which strictly technical content is
+	      expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.policy.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Core team policy decisions</emphasis></para>
+
+	    <para>This is a low volume, read-only mailing list for FreeBSD
+	      Core Team Policy decisions.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.ports.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussion of
+		<quote>ports</quote></emphasis></para>
+
+	    <para>Discussions concerning FreeBSD's <quote>ports
+	      collection</quote> (<filename>/usr/ports</filename>), ports infrastructure, and
+	      general ports coordination efforts.  This is a technical mailing list
+	      for which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.ports-bugs.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussion of
+		<quote>ports</quote> bugs</emphasis></para>
+
+	    <para>Discussions concerning problem reports for FreeBSD's <quote>ports
+	      collection</quote> (<filename>/usr/ports</filename>), proposed
+	      ports, or modifications to ports.  This is a technical mailing list
+	      for which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.proliant.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Technical discussion of FreeBSD on HP
+		ProLiant server platforms</emphasis></para>
+
+	    <para>This mailing list is to be used for the technical
+	      discussion of the usage of FreeBSD on HP ProLiant servers,
+	      including the discussion of ProLiant-specific drivers,
+	      management software, configuration tools, and BIOS
+	      updates.  As such, this is the primary place to discuss
+	      the hpasmd, hpasmcli, and hpacucli modules.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.python.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Python on FreeBSD</emphasis></para>
+
+	    <para>This is a list for discussions related to improving Python-support
+	      on FreeBSD.  This is a technical mailing list.  It is for individuals
+	      working on porting Python, its 3rd party modules and <application>Zope</application> stuff to
+	      FreeBSD.  Individuals interested in following the technical discussion
+	      are also welcome.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.questions.name;</term>
+
+	  <listitem>
+	    <para><emphasis>User questions</emphasis></para>
+
+	    <para>This is the mailing list for questions about FreeBSD.  You
+	      should not send <quote>how to</quote> questions to the technical
+	      lists unless you consider the question to be pretty
+	      technical.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.scsi.name;</term>
+
+	  <listitem>
+	    <para><emphasis>SCSI subsystem</emphasis></para>
+
+	    <para>This is the mailing list for people working on the SCSI
+	      subsystem for FreeBSD.  This is a technical mailing list for
+	      which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.security.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Security issues</emphasis></para>
+
+	    <para>FreeBSD computer security issues (DES, Kerberos, known
+	      security holes and fixes, etc).  This is a technical mailing
+	      list for which strictly technical discussion is expected. Note
+	      that this is not a question-and-answer list, but that
+	      contributions (BOTH question AND answer) to the FAQ are
+	      welcome.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.security-notifications.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Security Notifications</emphasis></para>
+
+	    <para>Notifications of FreeBSD security problems and
+	      fixes. This is not a discussion list.  The discussion
+	      list is FreeBSD-security.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.small.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Using FreeBSD in embedded
+	      applications</emphasis></para>
+
+	    <para>This list discusses topics related to unusually small and
+	      embedded FreeBSD installations.  This is a technical mailing
+	      list for which strictly technical content is expected.</para>
+
+	    <note>
+	      <para>This list has been obsoleted by &a.embedded.name;.</para>
+	    </note>
+
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.stable.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussions about the use of
+		&os.stable;</emphasis></para>
+
+	    <para>This is the mailing list for users of &os.stable;.  It
+	      includes warnings about new features coming out in -STABLE that
+	      will affect the users, and instructions on steps that must be
+	      taken to remain -STABLE.  Anyone running <quote>STABLE</quote>
+	      should subscribe to this list.  This is a technical mailing list
+	      for which strictly technical content is expected.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.standards.name;</term>
+
+	  <listitem>
+	    <para><emphasis>C99 &amp; POSIX Conformance</emphasis></para>
+
+	    <para>This is a forum for technical discussions related to
+	      FreeBSD Conformance to the C99 and the POSIX standards.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.usb.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Discussing &os; support for
+	      USB</emphasis></para>
+
+	    <para>This is a mailing list for technical discussions
+	      related to &os; support for USB.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.usergroups.name;</term>
+
+	  <listitem>
+	    <para><emphasis>User Group Coordination List</emphasis></para>
+
+	    <para>This is the mailing list for the coordinators from each of
+	      the  local area Users Groups to discuss matters with each other
+	      and a  designated individual from the Core Team.  This mail list
+	      should be limited to meeting synopsis and coordination of
+	      projects that span User Groups.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>&a.vendors.name;</term>
+
+	  <listitem>
+	    <para><emphasis>Vendors</emphasis></para>
+
+	    <para>Coordination discussions between The FreeBSD Project and
+	      Vendors of software and hardware for FreeBSD.</para>
+	  </listitem>
+	</varlistentry>
+
+      </variablelist>
+    </sect2>
+    <sect2 id="eresources-mailfiltering">
+      <title>Filtering on the Mailing Lists</title>
+
+      <para>The &os; mailing lists are filtered in multiple ways to
+        avoid the distribution of spam, viruses, and other unwanted emails.
+        The filtering actions described in this section do not include all
+        those used to protect the mailing lists.</para>
+
+      <para>Only certain types of attachments are allowed on the
+	mailing lists.  All attachments with a MIME content type not
+	found in the list below will be stripped before an email is
+	distributed on the mailing lists.</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>application/octet-stream</para>
+	</listitem>
+
+	<listitem>
+	  <para>application/pdf</para>
+	</listitem>
+
+	<listitem>
+	  <para>application/pgp-signature</para>
+	</listitem>
+
+	<listitem>
+	  <para>application/x-pkcs7-signature</para>
+	</listitem>
+
+	<listitem>
+	  <para>message/rfc822</para>
+	</listitem>
+
+	<listitem>
+	  <para>multipart/alternative</para>
+	</listitem>
+
+	<listitem>
+	  <para>multipart/related</para>
+	</listitem>
+
+	<listitem>
+	  <para>multipart/signed</para>
+	</listitem>
+
+	<listitem>
+	  <para>text/html</para>
+	</listitem>
+
+	<listitem>
+	  <para>text/plain</para>
+	</listitem>
+
+	<listitem>
+	  <para>text/x-diff</para>
+	</listitem>
+
+	<listitem>
+	  <para>text/x-patch</para>
+	</listitem>
+      </itemizedlist>
+
+      <note>
+	<para>Some of the mailing lists might allow attachments of
+	  other MIME content types, but the above list should be
+	  applicable for most of the mailing lists.</para>
+      </note>
+
+      <para>If an email contains both an HTML and a plain text version,
+	the HTML version will be removed.  If an email contains only an
+	HTML version, it will be converted to plain text.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="eresources-news">
+    <title>Usenet Newsgroups</title>
+
+    <para>In addition to two FreeBSD specific newsgroups, there are many
+      others in which FreeBSD is discussed or are otherwise relevant to
+      FreeBSD users.  <ulink
+	url="http://minnie.tuhs.org/BSD-info/bsdnews_search.html">Keyword
+	searchable archives</ulink> are available for some of these newsgroups
+      from courtesy of Warren Toomey <email>wkt@cs.adfa.edu.au</email>.</para>
+
+    <sect2>
+      <title>BSD Specific Newsgroups</title>
+
+      <itemizedlist>
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:de.comp.os.unix.bsd">de.comp.os.unix.bsd</ulink> (German)</para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	    url="news:fr.comp.os.bsd">fr.comp.os.bsd</ulink> (French)</para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	    url="news:it.comp.os.freebsd">it.comp.os.freebsd</ulink> (Italian)</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Other &unix; Newsgroups of Interest</title>
+
+      <itemizedlist>
+	<listitem>
+	  <para><ulink url="news:comp.unix">comp.unix</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.questions">comp.unix.questions</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.admin">comp.unix.admin</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.programmer">comp.unix.programmer</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.shell">comp.unix.shell</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.security.unix">comp.security.unix</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.sources.unix">comp.sources.unix</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.misc">comp.unix.misc</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.bugs.4bsd">comp.bugs.4bsd</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.bugs.4bsd.ucb-fixes">comp.bugs.4bsd.ucb-fixes</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.unix.bsd">comp.unix.bsd</ulink></para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>X Window System</title>
+
+      <itemizedlist>
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x">comp.windows.x</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="eresources-web">
+    <title>World Wide Web Servers</title>
+
+    &chap.eresources.www.inc;
+  </sect1>
+
+  <sect1 id="eresources-email">
+    <title>Email Addresses</title>
+
+    <para>The following user groups provide FreeBSD related email addresses
+      for their members.  The listed administrator reserves the right to
+      revoke the address if it is abused in any way.</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="4">
+        <thead>
+	  <row>
+	    <entry>Domain</entry>
+	    <entry>Facilities</entry>
+	    <entry>User Group</entry>
+	    <entry>Administrator</entry>
+          </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry>ukug.uk.FreeBSD.org</entry>
+	    <entry>Forwarding only</entry>
+	    <entry><email>freebsd-users@uk.FreeBSD.org</email></entry>
+	    <entry>Lee Johnston
+	      <email>lee@uk.FreeBSD.org</email></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+  </sect1>
+
+  <sect1 id="eresources-shell">
+    <title>Shell Accounts</title>
+
+    <para>The following user groups provide shell accounts for people who are
+      actively supporting the FreeBSD project.  The listed administrator
+      reserves the right to cancel the account if it is abused in any
+      way.</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="4">
+	<thead>
+	  <row>
+	    <entry>Host</entry>
+	    <entry>Access</entry>
+	    <entry>Facilities</entry>
+	    <entry>Administrator</entry>
+          </row>
+	</thead>
+
+	<tbody>
+	  <row>
+	    <entry>dogma.freebsd-uk.eu.org</entry>
+	    <entry>Telnet/FTP/SSH</entry>
+	    <entry>Email, Web space, Anonymous FTP</entry>
+            <entry>Lee Johnston
+		<email>lee@uk.FreeBSD.org</email></entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+  </sect1>
+</appendix>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../appendix.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "appendix")
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/firewalls/Makefile b/pl_PL.ISO8859-2/books/handbook/firewalls/Makefile
new file mode 100644
index 0000000000..331f5bf8ec
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/firewalls/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	firewalls/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/firewalls/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/firewalls/chapter.sgml
new file mode 100644
index 0000000000..9b9e69fb6d
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/firewalls/chapter.sgml
@@ -0,0 +1,3339 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="firewalls">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Joseph J.</firstname>
+	<surname>Barbish</surname>
+	<contrib>Contributed by </contrib>
+      </author>
+    </authorgroup>
+    <authorgroup>
+      <author>
+	<firstname>Brad</firstname>
+	<surname>Davis</surname>
+	<contrib>Converted to SGML and updated by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Firewalls</title>
+
+  <indexterm><primary>firewall</primary></indexterm>
+
+  <indexterm>
+    <primary>security</primary>
+
+    <secondary>firewalls</secondary>
+  </indexterm>
+
+  <sect1 id="firewalls-intro">
+    <title>Introduction</title>
+
+    <para>Firewalls make it possible to filter
+      incoming and outgoing traffic that flows through your system.
+      A firewall can use one or more sets of <quote>rules</quote> to
+      inspect the network packets as they come in or go out of your
+      network connections and either allows the traffic through or
+      blocks it.  The rules of a firewall can inspect one or more
+      characteristics of the packets, including but not limited to the
+      protocol type, the source or destination host address, and the
+      source or destination port.</para>
+
+    <para>Firewalls can greatly enhance the security of a host or a
+      network.  They can be used to do one or more of
+      the following things:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>To protect and insulate the applications, services and
+	  machines of your internal network from unwanted traffic
+	  coming in from the public Internet.</para>
+      </listitem>
+
+      <listitem>
+	<para>To limit or disable access from hosts of the internal
+	  network to services of the public Internet.</para>
+      </listitem>
+
+      <listitem>
+	<para>To support network address translation
+	  (<acronym>NAT</acronym>), which allows your internal network
+	  to use private <acronym>IP</acronym> addresses and share a
+	  single connection to the public Internet (either with a
+	  single <acronym>IP</acronym> address or by a shared pool of
+	  automatically assigned public addresses).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>How to properly define packet filtering rules.</para>
+      </listitem>
+
+      <listitem>
+	<para>The differences between the firewalls
+	  built into &os;.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use and configure the OpenBSD
+	  <application>PF</application> firewall.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use and configure
+	  <application>IPFILTER</application>.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use and configure
+	  <application>IPFW</application>.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand basic &os; and Internet concepts.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="firewalls-concepts">
+    <title>Firewall Concepts</title>
+
+    <indexterm>
+      <primary>firewall</primary>
+
+      <secondary>rulesets</secondary>
+    </indexterm>
+
+    <para>There are two basic ways to create firewall rulesets:
+      <quote>inclusive</quote> or <quote>exclusive</quote>.  An
+      exclusive firewall allows all traffic through except for the
+      traffic matching the ruleset.  An inclusive firewall does the
+      reverse.  It only allows traffic matching the rules through and
+      blocks everything else.</para>
+
+    <para>Inclusive firewalls are generally safer than exclusive
+      firewalls because they significantly reduce the risk of allowing
+      unwanted traffic to pass through the firewall.</para>
+
+    <para>Security can be tightened further using a <quote>stateful
+	firewall</quote>.  With a stateful firewall the firewall keeps
+      track of which connections are opened through the firewall and
+      will only allow traffic through which either matches an existing
+      connection or opens a new one.  The disadvantage of a stateful
+      firewall is that it can be vulnerable to Denial of Service
+      (<acronym>DoS</acronym>) attacks if a lot of new connections are
+      opened very fast.  With most firewalls it is possible to use a
+      combination of stateful and non-stateful behavior to make an
+      optimal firewall for the site.</para>
+  </sect1>
+
+  <sect1 id="firewalls-apps">
+    <title>Firewall Packages</title>
+
+    <para>&os; has three different firewall packages built
+      into the base system.  They are: <emphasis>IPFILTER</emphasis>
+      (also known as <acronym>IPF</acronym>),
+      <emphasis>IPFIREWALL</emphasis> (also known as <acronym>IPFW</acronym>),
+      and <emphasis>OpenBSD's PacketFilter</emphasis> (also known as
+      <acronym>PF</acronym>).  &os; also has two built in packages for
+      traffic shaping (basically controlling bandwidth usage):
+      &man.altq.4; and &man.dummynet.4;.  Dummynet has traditionally been
+      closely tied with <acronym>IPFW</acronym>, and
+      <acronym>ALTQ</acronym> with
+      <acronym>IPF</acronym>/<acronym>PF</acronym>.  IPF,
+      IPFW, and PF all use rules to control the access of packets to and
+      from your system, although they go about it different ways and
+      have different rule syntaxes.</para>
+
+    <para>The reason that &os; has multiple built in firewall packages
+      is that different people have different requirements and
+      preferences.  No single firewall package is the best.</para>
+
+    <para>The author prefers IPFILTER because its stateful rules are
+      much less complicated to use in a <acronym>NAT</acronym>
+      environment and it has a built in ftp proxy that simplifies the
+      rules to allow secure outbound FTP usage.</para>
+
+    <para>Since all firewalls are based on inspecting the values of
+      selected packet control fields, the creator of the firewall
+      rulesets must have an understanding of how
+      <acronym>TCP</acronym>/IP works, what the different values in
+      the packet control fields are and how these values are used in a
+      normal session conversation.  For a good explanation go to:
+      <ulink
+	url="http://www.ipprimer.com/overview.cfm"></ulink>.</para>
+  </sect1>
+
+  <sect1 id="firewalls-pf">
+    <title>The OpenBSD Packet Filter (PF) and
+      <acronym>ALTQ</acronym></title>
+
+    <indexterm>
+      <primary>firewall</primary>
+
+      <secondary>PF</secondary>
+    </indexterm>
+
+    <para>As of July 2003 the OpenBSD firewall software application
+      known as <acronym>PF</acronym> was ported to &os; and was made
+      available in the &os; Ports Collection; the first release that
+      contained <acronym>PF</acronym> as an integrated part of the
+      base system was &os;&nbsp;5.3 in November 2004.
+      <acronym>PF</acronym> is a complete, fully featured firewall
+      that has optional support for <acronym>ALTQ</acronym> (Alternate
+      Queuing).  <acronym>ALTQ</acronym> provides Quality of Service
+      (<acronym>QoS</acronym>) bandwidth shaping that allows
+      guaranteeing bandwidth to different services based on filtering
+      rules.  The OpenBSD Project does an outstanding job of
+      maintaining the PF User's Guide that it will not be made part of
+      this handbook firewall section as that would just be duplicated
+      effort.</para>
+
+    <para>More info can be found at the PF for &os; web site: <ulink
+	url="http://pf4freebsd.love2party.net/"></ulink>.</para>
+
+    <sect2>
+      <title>Enabling PF</title>
+
+      <para>PF is included in the basic &os; install for versions newer
+	than 5.3 as a separate run time loadable module.  The system
+	will dynamically load the PF kernel loadable module when the
+	rc.conf statement <literal>pf_enable="YES"</literal> is used.
+	The loadable module was created with &man.pflog.4; logging
+	enabled.</para>
+
+      <note>
+	<para>The module assumes the presence of <literal>options
+	    INET</literal> and <literal>device bpf</literal>.  Unless
+	  <literal>NOINET6</literal> for &os; prior to 6.0-RELEASE and
+	  <literal>NO_INET6</literal> for later releases (for example in
+	  &man.make.conf.5;) was defined during the build, it also
+	  requires<literal>options INET6</literal>.</para>
+      </note>
+
+      <para>Once the kernel module is loaded or the kernel is statically
+	built with PF support, it is possible to enable or disable
+	<application>pf</application> with the <command>pfctl</command>
+	command.</para>
+
+      <para>This example demonstrates how to enable
+	<application>pf</application>:</para>
+
+      <screen>&prompt.root; <userinput>pfctl -e</userinput></screen>
+
+      <para>The <command>pfctl</command> command provides a way to work
+	with the <application>pf</application> firewall. It is a good
+	idea to check the &man.pfctl.8; manual page to find out more
+	information about using it.</para>
+    </sect2>
+
+    <sect2>
+      <title>Kernel options</title>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>device pf</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>device pflog</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>device pfsync</secondary>
+      </indexterm>
+
+      <para>It is not a mandatory requirement that you enable PF by
+	compiling the following options into the &os; kernel.  It is
+	only presented here as background information.  Compiling PF
+	into the kernel causes the loadable module to never be
+	used.</para>
+
+      <para>Sample kernel config PF option statements are in the
+	<filename>/usr/src/sys/conf/NOTES</filename> kernel source and
+	are reproduced here:</para>
+
+      <programlisting>device pf
+device pflog
+device pfsync</programlisting>
+
+      <para><literal>device pf</literal> enables support for the
+	<quote>Packet Filter</quote> firewall.</para>
+
+      <para><literal>device pflog</literal> enables the optional
+	&man.pflog.4; pseudo network device which can be used to log
+	traffic to a &man.bpf.4; descriptor.  The &man.pflogd.8; daemon
+	can be used to store the logging information to disk.</para>
+
+      <para><literal>device pfsync</literal> enables the optional
+	&man.pfsync.4; pseudo network device that is used to monitor
+	<quote>state changes</quote>.  As this is not part of the
+	loadable module one has to build a custom kernel to use
+	it.</para>
+
+      <para>These settings will take effect only after you have built
+	and installed a kernel with them set.</para>
+    </sect2>
+
+    <sect2>
+      <title>Available rc.conf Options</title>
+
+      <para>You need the following statements in
+	<filename>/etc/rc.conf</filename> to activate PF at boot
+	time:</para>
+
+      <programlisting>pf_enable="YES"                 # Enable PF (load module if required)
+pf_rules="/etc/pf.conf"         # rules definition file for pf
+pf_flags=""                     # additional flags for pfctl startup
+pflog_enable="YES"              # start pflogd(8)
+pflog_logfile="/var/log/pflog"  # where pflogd should store the logfile
+pflog_flags=""                  # additional flags for pflogd startup</programlisting>
+
+      <para>If you have a LAN behind this firewall and have to forward
+	packets for the computers in the LAN or want to do NAT, you
+	have to enable the following option as well:</para>
+
+      <programlisting>gateway_enable="YES"            # Enable as LAN gateway</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Enabling <acronym>ALTQ</acronym></title>
+
+      <para><acronym>ALTQ</acronym> is only available by compiling the
+	options into the &os; Kernel.  <acronym>ALTQ</acronym> is not
+	supported by all of the available network card drivers.	 Please
+	see the &man.altq.4; manual page for a list of drivers that are
+	supported in your release of &os;.  The following options will
+	enable <acronym>ALTQ</acronym> and add additional
+	functionality.</para>
+
+      <programlisting>options         ALTQ
+options         ALTQ_CBQ        # Class Bases Queuing (CBQ)
+options         ALTQ_RED        # Random Early Detection (RED)
+options         ALTQ_RIO        # RED In/Out
+options         ALTQ_HFSC       # Hierarchical Packet Scheduler (HFSC)
+options         ALTQ_PRIQ       # Priority Queuing (PRIQ)
+options         ALTQ_NOPCC      # Required for SMP build</programlisting>
+
+      <para><literal>options ALTQ</literal> enables the
+	<acronym>ALTQ</acronym> framework.</para>
+
+      <para><literal>options ALTQ_CBQ</literal> enables Class Based
+	Queuing (<acronym>CBQ</acronym>).  <acronym>CBQ</acronym>
+	allows you to divide a connection's bandwidth into different
+	classes or queues to prioritize traffic based on filter
+	rules.</para>
+
+      <para><literal>options ALTQ_RED</literal> enables Random Early
+	Detection (<acronym>RED</acronym>).  <acronym>RED</acronym> is
+	used to avoid network congestion.  <acronym>RED</acronym> does
+	this by measuring the length of the queue and comparing it to
+	the minimum and maximum thresholds for the queue.  If the
+	queue is over the maximum all new packets will be dropped.
+	True to its name, <acronym>RED</acronym> drops packets from
+	different connections randomly.</para>
+
+      <para><literal>options ALTQ_RIO</literal> enables Random Early
+	Detection In and Out.</para>
+
+      <para><literal>options ALTQ_HFSC</literal> enables the
+	Hierarchical Fair Service Curve Packet Scheduler.  For more
+	information about <acronym>HFSC</acronym> see: <ulink
+	  url="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html"></ulink>.</para>
+
+      <para><literal>options ALTQ_PRIQ</literal> enables Priority
+	Queuing (<acronym>PRIQ</acronym>).  <acronym>PRIQ</acronym>
+	will always pass traffic that is in a higher queue
+	first.</para>
+
+      <para><literal>options ALTQ_NOPCC</literal> enables
+	<acronym>SMP</acronym> support for <acronym>ALTQ</acronym>.
+	This option is required on <acronym>SMP</acronym>
+	systems.</para>
+    </sect2>
+
+    <sect2>
+      <title>Creating Filtering Rules</title>
+
+      <para>The Packet Filter reads its configuration rules from the
+	&man.pf.conf.5; file and it modifies, drops or passes packets
+	according to the rules or definitions specified there.  The &os;
+	installation comes with a default
+	<filename>/etc/pf.conf</filename> which contains useful examples
+	and explanations.</para>
+
+      <para>Although &os; has its own <filename>/etc/pf.conf</filename>
+	the syntax is the same as one used in OpenBSD.  A great
+	resource for configuring the <application>pf</application>
+	firewall has been written by OpenBSD team and is available at
+	<ulink url="http://www.openbsd.org/faq/pf/"></ulink>.</para>
+
+      <warning>
+	<para>When browsing the pf user's guide, please keep in mind that
+     different versions of &os; contain different versions of pf.  The
+     <application>pf</application> firewall in &os; 5.X is at the level
+     of OpenBSD version 3.5 and in &os; 6.X is at the level of OpenBSD
+     version 3.7.</para>
+      </warning>
+
+      <para>The &a.pf; is a good place to ask questions about
+	configuring and running the <application>pf</application>
+	firewall.  Do not forget to check the mailing list archives
+	before asking questions.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="firewalls-ipf">
+    <title>The IPFILTER (IPF) Firewall</title>
+
+    <indexterm>
+      <primary>firewall</primary>
+
+      <secondary>IPFILTER</secondary>
+    </indexterm>
+
+    <note>
+      <para>This section is work in progress.  The contents might
+	not be accurate at all times.</para>
+    </note>
+
+    <para>The author of IPFILTER is Darren Reed.  IPFILTER is not
+      operating system dependent: it is an open source application and
+      has been ported to &os;, NetBSD, OpenBSD, &sunos;, HP/UX, and
+      &solaris; operating systems.  IPFILTER is actively being
+      supported and maintained, with updated versions being released
+      regularly.</para>
+
+    <para>IPFILTER is based on a kernel-side firewall and
+      <acronym>NAT</acronym> mechanism that can be controlled and
+      monitored by userland interface programs.  The firewall rules can
+      be set or deleted with the &man.ipf.8; utility.  The
+      <acronym>NAT</acronym> rules can be set or deleted with the
+      &man.ipnat.1; utility.  The &man.ipfstat.8; utility can print
+      run-time statistics for the kernel parts of IPFILTER.  The
+      &man.ipmon.8; program can log IPFILTER actions to the system log
+      files.</para>
+
+    <para>IPF was originally written using a rule processing logic of
+      <quote>the last matching rule wins</quote> and used only
+      stateless type of rules.  Over time IPF has been enhanced to
+      include a <quote>quick</quote> option and a stateful <quote>keep
+	state</quote> option which drastically modernized the rules
+      processing logic.  IPF's official documentation covers the legacy
+      rule coding parameters and the legacy rule file processing
+      logic.  The modernized functions are only included as additional
+      options, completely understating their benefits in producing a
+      far superior secure firewall.</para>
+
+    <para>The instructions contained in this section are based on
+      using rules that contain the <quote>quick</quote> option and the
+      stateful <quote>keep state</quote> option.  This is the basic
+      framework for coding an inclusive firewall rule set.</para>
+
+    <!-- XXX: something like this already in
+	 <xref linkend="firewalls-concepts">
+	 AND: the para below is repeated 3 times in this chapter-->
+
+    <para>An inclusive firewall only allows packets matching the rules
+      to pass through.  This way you can control what services can
+      originate behind the firewall destined for the public Internet
+      and also control the services which can originate from the
+      public Internet accessing your private network.  Everything else
+      is blocked and logged by default design.  Inclusive firewalls are
+      much, much more secure than exclusive firewall rule sets and is
+      the only rule set type covered herein.</para>
+
+    <para>For detailed explanation of the legacy rules processing
+      method see: <ulink
+	url="http://www.obfuscation.org/ipf/ipf-howto.html#TOC_1"></ulink>
+      and <ulink
+	url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>.</para>
+
+    <para>The IPF FAQ is at <ulink
+	url="http://www.phildev.net/ipf/index.html"></ulink>.</para>
+
+    <para>A searchable archive of the open-source IPFilter mailing list is
+      available at <ulink
+        url="http://marc.theaimsgroup.com/?l=ipfilter"></ulink>.</para>
+
+    <sect2>
+      <title>Enabling IPF</title>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>enabling</secondary>
+      </indexterm>
+
+      <para>IPF is included in the basic &os; install as a separate run
+	time loadable module.  The system will dynamically load the IPF
+	kernel loadable module when the rc.conf statement
+	<literal>ipfilter_enable="YES"</literal> is used.  The loadable
+	module was created with logging enabled and the
+	<literal>default pass all</literal> options.  You do not need
+	to compile IPF into the &os; kernel just to change the default
+	to <literal>block all</literal>, you can do that by just coding
+	a block all rule at the end of your rule set.</para>
+    </sect2>
+
+    <sect2>
+      <title>Kernel options</title>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFILTER</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFILTER_LOG</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFILTER_DEFAULT_BLOCK</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>kernel options</secondary>
+      </indexterm>
+
+      <para>It is not a mandatory requirement that you enable IPF by
+	compiling the following options into the &os; kernel.  It is
+	only presented here as background information.  Compiling IPF
+	into the kernel causes the loadable module to never be
+	used.</para>
+
+      <para>Sample kernel config IPF option statements are in the
+	<filename>/usr/src/sys/conf/NOTES</filename> kernel source
+	and are reproduced here:</para>
+
+      <programlisting>options IPFILTER
+options IPFILTER_LOG
+options IPFILTER_DEFAULT_BLOCK</programlisting>
+
+      <para><literal>options IPFILTER</literal> enables support for the
+	<quote>IPFILTER</quote> firewall.</para>
+
+      <para><literal>options IPFILTER_LOG</literal> enables the option
+	to have IPF log traffic by writing to the
+	<devicename>ipl</devicename> packet logging pseudo&mdash;device
+	for every rule that has the <literal>log</literal>
+	keyword.</para>
+
+      <para><literal>options IPFILTER_DEFAULT_BLOCK</literal> changes
+	the default behavior so any packet not matching a firewall
+	<literal>pass</literal> rule gets blocked.</para>
+
+      <para>These settings will take effect only after you have built
+	and installed a kernel with them set.</para>
+    </sect2>
+
+    <sect2>
+      <title>Available rc.conf Options</title>
+
+      <para>You need the following statements in
+	<filename>/etc/rc.conf</filename> to activate IPF at boot
+	time:</para>
+
+      <programlisting>ipfilter_enable="YES"             # Start ipf firewall
+ipfilter_rules="/etc/ipf.rules"   # loads rules definition text file
+ipmon_enable="YES"                # Start IP monitor log
+ipmon_flags="-Ds"                 # D = start as daemon
+                                  # s = log to syslog
+                                  # v = log tcp window, ack, seq
+                                  # n = map IP &amp; port to names</programlisting>
+
+      <para>If you have a LAN behind this firewall that uses the
+	reserved private IP address ranges, then you need to add the
+	following to enable <acronym>NAT</acronym>
+	functionality:</para>
+
+      <programlisting>gateway_enable="YES"              # Enable as LAN gateway
+ipnat_enable="YES"                # Start ipnat function
+ipnat_rules="/etc/ipnat.rules"    # rules definition file for ipnat</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>IPF</title>
+
+      <indexterm><primary><command>ipf</command></primary></indexterm>
+
+      <para>The ipf command is used to load your rules file.  Normally
+	you create a file containing your custom rules and use this
+	command to replace in mass the currently running firewall
+	internal rules:</para>
+
+      <screen>&prompt.root; <userinput>ipf -Fa -f /etc/ipf.rules</userinput></screen>
+
+      <para><option>-Fa</option> means flush all internal rules
+	tables.</para>
+
+      <para><option>-f</option> means this is the file to read for the
+	rules to load.</para>
+
+      <para>This gives you the ability to make changes to your custom
+	rules file, run the above IPF command, and thus update the
+	running firewall with a fresh copy of all the rules without
+	having to reboot the system.  This method is very convenient
+	for testing new rules as the procedure can be executed as many
+	times as needed.</para>
+
+      <para>See the &man.ipf.8; manual page for details on the other
+	flags available with this command.</para>
+
+      <para>The &man.ipf.8; command expects the rules file to be a
+	standard text file.  It will not accept a rules file written as
+	a script with symbolic substitution.</para>
+
+      <para>There is a way to build IPF rules that utilizes the power
+	of script symbolic substitution.  For more information, see
+	<xref linkend="firewalls-ipf-rules-script">.</para>
+    </sect2>
+
+    <sect2>
+      <title>IPFSTAT</title>
+
+      <indexterm><primary><command>ipfstat</command></primary></indexterm>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>statistics</secondary>
+      </indexterm>
+
+      <para>The default behavior of &man.ipfstat.8; is to retrieve and
+	display the totals of the accumulated statistics gathered as a
+	result of applying the user coded rules against packets going
+	in and out of the firewall since it was last started, or since
+	the last time the accumulators were reset to zero by the
+	<command>ipf -Z</command> command.</para>
+
+      <para>See the &man.ipfstat.8; manual page for details.</para>
+
+      <para>The default &man.ipfstat.8; command output will look
+	something like this:</para>
+
+      <screen>input packets: blocked 99286 passed 1255609 nomatch 14686 counted 0
+ output packets: blocked 4200 passed 1284345 nomatch 14687 counted 0
+ input packets logged: blocked 99286 passed 0
+ output packets logged: blocked 0 passed 0
+ packets logged: input 0 output 0
+ log failures: input 3898 output 0
+ fragment state(in): kept 0 lost 0
+ fragment state(out): kept 0 lost 0
+ packet state(in): kept 169364 lost 0
+ packet state(out): kept 431395 lost 0
+ ICMP replies: 0 <acronym>TCP</acronym> RSTs sent: 0
+ Result cache hits(in): 1215208 (out): 1098963
+ IN Pullups succeeded: 2 failed: 0
+ OUT Pullups succeeded: 0 failed: 0
+ Fastroute successes: 0 failures: 0
+ <acronym>TCP</acronym> cksum fails(in): 0 (out): 0
+ Packet log flags set: (0)</screen>
+
+      <para>When supplied with either <option>-i</option> for inbound
+	or <option>-o</option> for outbound, it will retrieve and
+	display the appropriate list of filter rules currently
+	installed and in use by the kernel.</para>
+
+      <para><command>ipfstat -in</command> displays the inbound
+	internal rules table with rule number.</para>
+
+      <para><command>ipfstat -on</command> displays the outbound
+	internal rules table with the rule number.</para>
+
+      <para>The output will look something like this:</para>
+
+      <screen>@1 pass out on xl0 from any to any
+@2 block out on dc0 from any to any
+@3 pass out quick on dc0 proto tcp/udp from any to any keep state</screen>
+
+      <para><command>ipfstat -ih</command> displays the inbound
+	internal rules table, prefixing each rule with a count of how
+	many times the rule was matched.</para>
+
+      <para><command>ipfstat -oh</command> displays the outbound
+	internal rules table, prefixing each rule with a count of how
+	many times the rule was matched.</para>
+
+      <para>The output will look something like this:</para>
+
+      <screen>2451423 pass out on xl0 from any to any
+354727 block out on dc0 from any to any
+430918 pass out quick on dc0 proto tcp/udp from any to any keep state</screen>
+
+      <para>One of the most important functions of the
+	<command>ipfstat</command> command is the <option>-t</option>
+	flag which displays the state table in a way similar to the way
+	&man.top.1; shows the &os; running process table.  When your
+	firewall is under attack this function gives you the ability to
+	identify, drill down to, and see the attacking packets.  The
+	optional sub-flags give the ability to select the destination
+	or source IP, port, or protocol that you want to monitor in
+	real time.  See the &man.ipfstat.8; manual page for
+	details.</para>
+    </sect2>
+
+    <sect2>
+      <title>IPMON</title>
+
+      <indexterm><primary><command>ipmon</command></primary></indexterm>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>logging</secondary>
+      </indexterm>
+
+      <para>In order for <command>ipmon</command> to work properly, the
+	kernel option IPFILTER_LOG must be turned on.  This command has
+	two different modes that it can be used in.  Native mode is the
+	default mode when you type the command on the command line
+	without the <option>-D</option> flag.</para>
+
+      <para>Daemon mode is for when you want to have a continuous
+	system log file available so that you can review logging of
+	past events.  This is how &os; and IPFILTER are configured to
+	work together. &os; has a built in facility to automatically
+	rotate system logs.  That is why outputting the log information
+	to syslogd is better than the default of outputting to a
+	regular file.  In the default <filename>rc.conf</filename> file
+	you see the ipmon_flags statement uses the <option>-Ds</option>
+	flags:</para>
+
+      <programlisting>ipmon_flags="-Ds" # D = start as daemon
+                  # s = log to syslog
+                  # v = log tcp window, ack, seq
+                  # n = map IP &amp; port to names</programlisting>
+
+      <para>The benefits of logging are obvious.  It provides the
+	ability to review, after the fact, information such as which
+	packets had been dropped, what addresses they came from and
+	where they were going.  These all give you a significant edge
+	in tracking down attackers.</para>
+
+      <para>Even with the logging facility enabled, IPF will not
+	generate any rule logging on its own.  The firewall
+	administrator decides what rules in the rule set he wants to
+	log and adds the log keyword to those rules.  Normally only
+	deny rules are logged.</para>
+
+      <para>It is very customary to include a default deny everything
+	rule with the log keyword included as your last rule in the
+	rule set.  This way you get to see all the packets that did not
+	match any of the rules in the rule set.</para>
+    </sect2>
+
+    <sect2>
+      <title>IPMON Logging</title>
+
+      <para><application>Syslogd</application> uses its own special
+	method for segregation of log data.  It uses special groupings
+	called <quote>facility</quote> and <quote>level</quote>.  IPMON
+	in <option>-Ds</option> mode uses <literal>security</literal>
+	as the <quote>facility</quote>
+	name.  All IPMON logged data goes to <literal>security</literal>
+	The following levels can be
+	used to further segregate the logged data if desired:</para>
+
+      <screen>LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block.
+LOG_NOTICE - packets logged which are also passed
+LOG_WARNING - packets logged which are also blocked
+LOG_ERR - packets which have been logged and which can be considered short</screen>
+
+      <!-- XXX: "can be considered short" == "with incomplete header" -->
+
+      <para>To setup IPFILTER to log all data to
+	<filename>/var/log/ipfilter.log</filename>, you will need to
+	create the file.  The following command will do that:</para>
+
+       <screen>&prompt.root; <userinput>touch /var/log/ipfilter.log</userinput></screen>
+
+      <para>The syslog function is controlled by definition statements
+	in the <filename>/etc/syslog.conf</filename> file.  The
+	<filename>syslog.conf</filename> file offers considerable
+	flexibility in how syslog will deal with system messages issued
+	by software applications like IPF.</para>
+
+      <para>Add the following statement to
+	<filename>/etc/syslog.conf</filename>:</para>
+
+      <programlisting>security.* /var/log/ipfilter.log</programlisting>
+
+      <para>Or add the following statement to
+        <filename>/etc/syslog.conf</filename>.</para>
+
+      <para>The <literal>security.*</literal>
+	means to write all the logged messages to the coded
+	file location.</para>
+
+      <para>To activate the changes to <filename>/etc/syslog.conf
+	</filename> you can reboot or bump the syslog task into
+	re-reading <filename>/etc/syslog.conf</filename> by running
+	<command>/etc/rc.d/syslogd reload</command></para>
+
+      <para>Do not forget to change
+	<filename>/etc/newsyslog.conf</filename> to rotate the new log
+	you just created above.</para>
+    </sect2>
+
+    <sect2>
+      <title>The Format of Logged Messages</title>
+
+      <para>Messages generated by <command>ipmon</command> consist of
+	data fields separated by white space.  Fields common to all
+	messages are:</para>
+
+      <orderedlist>
+	<listitem>
+	  <para>The date of packet receipt.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The time of packet receipt.  This is in the form
+	    HH:MM:SS.F, for hours, minutes, seconds, and fractions of a
+	    second (which can be several digits long).</para>
+	</listitem>
+
+	<listitem>
+	  <para>The name of the interface the packet was processed on,
+	    e.g. <devicename>dc0</devicename>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The group and rule number of the rule, e.g.
+	    <literal>@0:17</literal>.</para>
+	</listitem>
+      </orderedlist>
+
+      <para>These can be viewed with <command>ipfstat
+	-in</command>.</para>
+
+      <orderedlist>
+	<listitem>
+	  <para>The action: p for passed, b for blocked, S for a short
+	    packet, n did not match any rules, L for a log rule.  The
+	    order of precedence in showing flags is: S, p, b, n, L.  A
+	    capital P or B means that the packet has been logged due to
+	    a global logging setting, not a particular rule.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The addresses.  This is actually three fields: the
+	    source address and port (separated by a comma), the -&gt;
+	    symbol, and the destination address and port.
+	    209.53.17.22,80 -&gt; 198.73.220.17,1722.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>PR</literal> followed by the protocol name or
+	    number, e.g. PR tcp.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>len</literal> followed by the header length
+	    and total length of the packet, e.g. len 20 40.</para>
+	</listitem>
+      </orderedlist>
+
+      <para>If the packet is a <acronym>TCP</acronym> packet, there
+	will be an additional field starting with a hyphen followed by
+	letters corresponding to any flags that were set.  See the
+	&man.ipmon.8; manual page for a list of letters and their
+	flags.</para>
+
+      <para>If the packet is an ICMP packet, there will be two fields
+	at the end, the first always being <quote>ICMP</quote>, and the
+	next being the ICMP message and sub-message type, separated by
+	a slash, e.g. ICMP 3/3 for a port unreachable message.</para>
+    </sect2>
+
+    <sect2 id="firewalls-ipf-rules-script">
+      <title>Building the Rule Script with Symbolic
+	Substitution</title>
+
+      <para>Some experienced IPF users create a file containing the
+	rules and code them in a manner compatible with running them as
+	a script with symbolic substitution.  The major benefit of
+	doing this is that you only have to change the value associated
+	with the symbolic name and when the script is run all the rules
+	containing the symbolic name will have the value substituted in
+	the rules.  Being a script, you can use symbolic substitution
+	to code frequently used values and substitute them in multiple
+	rules.  You will see this in the following example.</para>
+
+      <para>The script syntax used here is compatible with the sh, csh,
+	and tcsh shells.</para>
+
+      <para>Symbolic substitution fields are prefixed with a dollar
+	sign: <literal>&dollar;</literal>.</para>
+
+      <para>Symbolic fields do not have the &dollar; prefix.</para>
+
+      <para>The value to populate the symbolic field must be enclosed
+	with double quotes (<literal>"</literal>).</para>
+
+      <para>Start your rule file with something like this:</para>
+
+      <programlisting>############# Start of IPF rules script ########################
+
+oif="dc0"            # name of the outbound interface
+odns="192.0.2.11"    # ISP's DNS server IP address
+myip="192.0.2.7"     # my static IP address from ISP
+ks="keep state"
+fks="flags S keep state"
+
+# You can choose between building /etc/ipf.rules file
+# from this script or running this script "as is".
+#
+# Uncomment only one line and comment out another.
+#
+# 1) This can be used for building /etc/ipf.rules:
+#cat &gt; /etc/ipf.rules &lt;&lt; EOF
+#
+# 2) This can be used to run script "as is":
+/sbin/ipf -Fa -f - &lt;&lt; EOF
+
+# Allow out access to my ISP's Domain name server.
+pass out quick on &dollar;oif proto tcp from any to &dollar;odns port = 53 &dollar;fks
+pass out quick on &dollar;oif proto udp from any to &dollar;odns port = 53 &dollar;ks
+
+# Allow out non-secure standard www function
+pass out quick on &dollar;oif proto tcp from &dollar;myip to any port = 80 &dollar;fks
+
+# Allow out secure www function https over TLS SSL
+pass out quick on &dollar;oif proto tcp from &dollar;myip to any port = 443 &dollar;fks
+EOF
+################## End of IPF rules script ########################</programlisting>
+
+      <para>That is all there is to it.  The rules are not important in
+	this example; how the symbolic substitution fields are
+	populated and used are.  If the above example was in a file
+	named <filename>/etc/ipf.rules.script</filename>, you could
+	reload these rules by entering the following command:</para>
+
+      <screen>&prompt.root; <userinput>sh /etc/ipf.rules.script</userinput></screen>
+
+      <para>There is one problem with using a rules file with embedded
+	symbolics: IPF does not understand symbolic substitution, and
+	cannot read such scripts directly.</para>
+
+      <para>This script can be used in one of two ways:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Uncomment the line that begins with
+	    <literal>cat</literal>, and comment out the line that
+	    begins with <literal>/sbin/ipf</literal>.  Place
+	    <literal>ipfilter_enable="YES"</literal> into
+	    <filename>/etc/rc.conf</filename> as usual, and run script
+	    once after each modification to create or update
+	    <filename>/etc/ipf.rules</filename>.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Disable IPFILTER in system startup scripts by adding
+	    <literal>ipfilter_enable="NO"</literal> (this is default
+	    value) into <filename>/etc/rc.conf</filename> file.</para>
+
+	  <para>Add a script like the following to your
+	    <filename>/usr/local/etc/rc.d/</filename> startup
+	    directory.  The script should have an obvious name like
+	    <filename>ipf.loadrules.sh</filename>.  The
+	    <filename>.sh</filename> extension is mandatory.</para>
+
+	  <programlisting>#!/bin/sh
+sh /etc/ipf.rules.script</programlisting>
+
+	  <para>The permissions on this script file must be read,
+	    write, execute for owner <username>root</username>.</para>
+
+	  <screen>&prompt.root; <userinput>chmod 700 /usr/local/etc/rc.d/ipf.loadrules.sh</userinput></screen>
+	</listitem>
+      </itemizedlist>
+
+      <para>Now, when your system boots, your IPF rules will be
+	loaded.</para>
+    </sect2>
+
+    <sect2>
+      <title>IPF Rule Sets</title>
+
+      <!-- XXX: looks incorrect (and duplicated 2 times in this chapter):
+	    1. Packet can be processed two times depend of firewall
+	       firewall configuration, but "return trip back" is
+	       another packet.
+	    2. "Each TCP/IP service ... is predefined by its protocol ..."
+	       - this shold be about packet and it's parameters
+	       (source/destination address and port). -->
+
+      <para>A rule set is a group of ipf rules coded to pass or block
+	packets based on the values contained in the packet.  The
+	bi-directional exchange of packets between hosts comprises a
+	session conversation.  The firewall rule set processes the
+	packet two times, once on its arrival from the public Internet
+	host and again as it leaves for its return trip back to the
+	public Internet host.  Each TCP/IP service (i.e. telnet, www,
+	mail, etc.) is predefined by its protocol, source and
+	destination IP address, or the source and destination port
+	number.  This is the basic selection criteria used to create
+	rules which will pass or block services.</para>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>rule processing order</secondary>
+       </indexterm>
+
+      <para>IPF was originally written using a rules processing logic
+	of <quote>the last matching rule wins</quote> and used only
+	stateless rules.  Over time IPF has been enhanced to include a
+	<quote>quick</quote> option and a stateful <quote>keep
+	  state</quote> option which drastically modernized the rule
+	processing logic.</para>
+
+      <para>The instructions contained in this section are based on
+	using rules that contain the <quote>quick</quote> option and
+	the stateful <quote>keep state</quote> option.  This is the
+	basic framework for coding an inclusive firewall rule
+	set.</para>
+
+    <!-- XXX: something like this already in
+	 <xref linkend="firewalls-concepts">
+	 AND: the para below is repeated 3 times in this chapter-->
+
+      <para>An inclusive firewall only allows services matching the
+	rules through.  This way you can control what services can
+	originate behind the firewall destined for the public Internet
+	and also control the services which can originate from the
+	public Internet accessing your private network.  Everything
+	else is blocked and logged by default design.  Inclusive
+	firewalls are much, much securer than exclusive firewall rule
+	sets and is the only rule set type covered herein.</para>
+
+      <warning>
+	<para>When working with the firewall rules, be <emphasis>very
+	    careful</emphasis>.  Some configurations <emphasis>will
+	    lock you out</emphasis> of the server.  To be on the safe
+	  side, you may wish to consider performing the initial
+	  firewall configuration from the local console rather than
+	  doing it remotely e.g. via
+	  <application>ssh</application>.</para>
+      </warning>
+    </sect2>
+
+    <sect2>
+      <title>Rule Syntax</title>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>rule syntax</secondary>
+      </indexterm>
+
+      <para>The rule syntax presented here has been simplified to only
+	address the modern stateful rule context and <quote>first
+	matching rule wins</quote> logic.  For the complete legacy rule
+	syntax description see the &man.ipf.8; manual page.</para>
+
+      <para>A <literal>#</literal> character is used to mark the start
+	of a comment and may appear at the end of a rule line or on its
+	own line.  Blank lines are ignored.</para>
+
+      <para>Rules contain keywords.  These keywords have to be coded in
+	a specific order from left to right on the line.  Keywords are
+	identified in bold type.  Some keywords have sub-options which
+	may be keywords themselves and also include more sub-options.
+	Each of the headings in the below syntax has a bold section
+	header which expands on the content.</para>
+
+      <!-- This section is probably wrong. See the OpenBSD flag -->
+      <!-- What is the "OpenBSD flag"?  Reference please -->
+
+      <para><replaceable>ACTION IN-OUT OPTIONS SELECTION STATEFUL PROTO
+	  SRC_ADDR,DST_ADDR OBJECT PORT_NUM TCP_FLAG
+	  STATEFUL</replaceable></para>
+
+      <para><replaceable>ACTION</replaceable> = block | pass</para>
+
+      <para><replaceable>IN-OUT</replaceable> = in | out</para>
+
+      <para><replaceable>OPTIONS</replaceable> = log | quick | on
+	  interface-name</para>
+
+      <para><replaceable>SELECTION</replaceable> = proto value |
+	  source/destination IP | port = number | flags
+	  flag-value</para>
+
+      <para><replaceable>PROTO</replaceable> = tcp/udp | udp | tcp |
+	  icmp</para>
+
+      <para><replaceable>SRC_ADD,DST_ADDR</replaceable> = all | from
+	  object to object</para>
+
+      <para><replaceable>OBJECT</replaceable> = IP address | any</para>
+
+      <para><replaceable>PORT_NUM</replaceable> = port number</para>
+
+      <para><replaceable>TCP_FLAG</replaceable> = S</para>
+
+      <para><replaceable>STATEFUL</replaceable> = keep state</para>
+
+      <sect3>
+	<title>ACTION</title>
+
+	<para>The action indicates what to do with the packet if it
+	  matches the rest of the filter rule.  Each rule
+	  <emphasis>must</emphasis> have a action.  The following
+	  actions are recognized:</para>
+
+	<para><literal>block</literal> indicates that the packet should
+	  be dropped if the selection parameters match the
+	  packet.</para>
+
+	<para><literal>pass</literal> indicates that the packet should
+	  exit the firewall if the selection parameters match the
+	  packet.</para>
+      </sect3>
+
+      <sect3>
+	<title>IN-OUT</title>
+
+	<para>A mandatory requirement is that each filter rule
+	  explicitly state which side of the I/O it is to be used on.
+	  The next keyword must be either in or out and one or the
+	  other has to be coded or the rule will not pass syntax
+	  checks.</para>
+
+	<para><literal>in</literal> means this rule is being applied
+	  against an inbound packet which has just been received on the
+	  interface facing the public Internet.</para>
+
+	<para><literal>out</literal> means this rule is being applied
+	  against an outbound packet destined for the interface facing
+	  the public Internet.</para>
+      </sect3>
+
+      <sect3>
+	<title>OPTIONS</title>
+
+	<note>
+	  <para>These options must be used in the order shown
+	  here.</para>
+	</note>
+
+	<para><literal>log</literal> indicates that the packet header
+	  will be written to
+
+	<!-- XXX - xref here -->
+
+	  the <devicename>ipl</devicename> log (as described in the
+	  LOGGING section below) if the selection parameters match the
+	  packet.</para>
+
+	<para><literal>quick</literal> indicates that if the selection
+	  parameters match the packet, this rule will be the last rule
+	  checked, allowing a <quote>short-circuit</quote> path to avoid processing
+	  any following rules for this packet.  This option is a
+	  mandatory requirement for the modernized rules processing
+	  logic.</para>
+
+	<para><literal>on</literal> indicates the interface name to be
+	  incorporated into the selection parameters.  Interface names
+	  are as displayed by &man.ifconfig.8;.  Using this option, the
+	  rule will only match if the packet is going through that
+	  interface in the specified direction (in/out).  This option
+	  is a mandatory requirement for the modernized rules
+	  processing logic.</para>
+
+	<para>When a packet is logged, the headers of the packet are
+	  written to the IPL packet logging pseudo-device.
+	  Immediately following the log keyword, the following
+	  qualifiers may be used (in this order):</para>
+
+	<para><literal>body</literal> indicates that the first 128
+	  bytes of the packet contents will be logged after the
+	  headers.</para>
+
+	<para><literal>first</literal> If the <literal>log</literal>
+	  keyword is being used in conjunction with a <quote>keep
+	    state</quote> option, it is recommended that this option is
+	  also applied so that only the triggering packet is logged and
+	  not every packet which thereafter matches the <quote>keep
+	    state</quote> information.</para>
+      </sect3>
+
+      <sect3>
+	<title>SELECTION</title>
+
+	<para>The keywords described in this section are used to
+	  describe attributes of the packet to be interrogated when
+	  determining whether rules match or not.  There is a
+	  keyword subject, and it has sub-option keywords, one of
+	  which has to be selected.  The following general-purpose
+	  attributes are provided for matching, and must be used in
+	  this order:</para>
+      </sect3>
+
+      <sect3>
+	<title>PROTO</title>
+
+	<para><literal>proto</literal> is the subject keyword and must
+	  be coded along with one of its corresponding keyword
+	  sub-option values.  The value allows a specific protocol to
+	  be matched against.  This option is a mandatory requirement
+	  for the modernized rules processing logic.</para>
+
+	<para><literal>tcp/udp | udp | tcp | icmp</literal> or any
+	  protocol names found in <filename>/etc/protocols</filename>
+	  are recognized and may be used.  The special protocol keyword
+	  <literal>tcp/udp</literal> may be used to match either a
+	  <acronym>TCP</acronym> or a UDP packet, and has been added as
+	  a convenience to save duplication of otherwise identical
+	  rules.</para>
+      </sect3>
+
+      <sect3>
+	<title>SRC_ADDR/DST_ADDR</title>
+
+	<para>The <literal>all</literal> keyword is essentially a
+	  synonym for <quote>from any to any</quote> with no other
+	  match parameters.</para>
+
+	<para><literal>from src to dst</literal>: the from and to
+	  keywords are used to match against IP addresses.  Rules must
+	  specify BOTH source and destination parameters.
+	  <literal>any</literal> is a special keyword that matches any
+	  IP address.  Examples of use: <quote>from any to any</quote>
+	  or <quote>from 0.0.0.0/0 to any</quote> or <quote>from any to
+	    0.0.0.0/0</quote> or <quote>from 0.0.0.0 to any</quote> or
+	  <quote>from any to 0.0.0.0</quote>.</para>
+
+	<!-- XXX: Needs rewording -->
+
+	<para>IP addresses may be specified as a dotted IP address
+	  numeric form/mask-length, or as single dotted IP address
+	  numeric form.</para>
+
+	<para>There is no way to match ranges of IP addresses which
+	  do not express themselves easily as mask-length.  See this
+	  web page for help on writing mask-length: <ulink
+	    url="http://jodies.de/ipcalc"></ulink>.</para>
+      </sect3>
+
+      <sect3>
+	<title>PORT</title>
+
+	<para>If a port match is included, for either or both of source
+	  and destination, then it is only applied to
+	  <acronym>TCP</acronym> and UDP packets.  When composing port
+	  comparisons, either the service name from
+	  <filename>/etc/services</filename> or an integer port number
+	  may be used.  When the port appears as part of the from
+	  object, it matches the source port number; when it appears
+	  as part of the to object, it matches the destination port
+	  number.  The use of the port option with the
+	  <literal>to</literal> object is a mandatory requirement for
+	  the modernized rules processing logic.  Example of use:
+	  <quote>from any to any port = 80</quote></para>
+
+	<!-- XXX: Needs rewriting -->
+
+	<para>Port comparisons may be done in a number of forms, with
+	  a number of comparison operators, or port ranges may be
+	  specified.</para>
+
+	<para>port "=" | "!=" | "&lt;" | "&gt;" | "&lt;=" | "&gt;=" |
+	  "eq" | "ne" | "lt" | "gt" | "le" | "ge".</para>
+
+	<para>To specify port ranges, port "&lt;&gt;" |
+	  "&gt;&lt;"</para>
+
+	<warning>
+	  <para>Following the source and destination matching
+	    parameters, the following two parameters are mandatory
+	    requirements for the modernized rules processing
+	    logic.</para>
+	</warning>
+      </sect3>
+
+      <sect3>
+	<title><acronym>TCP</acronym>_FLAG</title>
+
+	<para>Flags are only effective for <acronym>TCP</acronym>
+	  filtering.  The letters represents one of the possible flags
+	  that can be interrogated in the <acronym>TCP</acronym> packet
+	  header.</para>
+
+	<para>The modernized rules processing logic uses the
+	  <literal>flags S</literal> parameter to identify the tcp
+	  session start request.</para>
+      </sect3>
+
+      <sect3>
+	<title>STATEFUL</title>
+
+	<para><literal>keep state</literal> indicates that on a pass
+	  rule, any packets that match the rules selection parameters
+	  should activate the stateful filtering facility.</para>
+
+	<note>
+	  <para>This option is a mandatory requirement for the
+	    modernized rules processing logic.</para>
+	</note>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Stateful Filtering</title>
+
+      <indexterm>
+	<primary>IPFILTER</primary>
+
+	<secondary>stateful filtering</secondary>
+      </indexterm>
+
+      <!-- XXX: duplicated -->
+
+      <para>Stateful filtering treats traffic as a bi-directional
+	exchange of packets comprising a session conversation.  When
+	activated, keep-state dynamically generates internal rules for
+	each anticipated packet being exchanged during the
+	bi-directional session conversation.  It has the interrogation
+	abilities to determine if the session conversation between the
+	originating sender and the destination are following the valid
+	procedure of bi-directional packet exchange.  Any packets that
+	do not properly fit the session conversation template are
+	automatically rejected as impostors.</para>
+
+      <para>Keep state will also allow ICMP packets related to a
+	<acronym>TCP</acronym> or UDP session through.  So if you get
+	ICMP type 3 code 4 in response to some web surfing allowed out
+	by a keep state rule, they will be automatically allowed in.
+	Any packet that IPF can be certain is part of an active
+	session, even if it is a different protocol, will be let
+	in.</para>
+
+      <para>What happens is:</para>
+
+      <para>Packets destined to go out the interface connected to the
+	public Internet are first checked against the dynamic state
+	table, if the packet matches the next expected packet
+	comprising in a active session conversation, then it exits the
+	firewall and the state of the session conversation flow is
+	updated in the dynamic state table, the remaining packets get
+	checked against the outbound rule set.</para>
+
+      <para>Packets coming in to the interface connected to the public
+	Internet are first checked against the dynamic state table, if
+	the packet matches the next expected packet comprising a
+	active session conversation, then it exits the firewall and
+	the state of the session conversation flow is updated in the
+	dynamic state table, the remaining packets get checked against
+	the inbound rule set.</para>
+
+      <para>When the conversation completes it is removed from the
+	dynamic state table.</para>
+
+      <para>Stateful filtering allows you to focus on blocking/passing
+	new sessions.  If the new session is passed, all its subsequent
+	packets will be allowed through automatically and any impostors
+	automatically rejected.  If a new session is blocked, none of
+	its subsequent packets will be allowed through.  Stateful
+	filtering has technically advanced interrogation abilities
+	capable of defending against the flood of different attack
+	methods currently employed by attackers.</para>
+    </sect2>
+
+    <sect2>
+      <!-- XXX: This section needs a rewrite -->
+
+      <title>Inclusive Rule Set Example</title>
+
+      <para>The following rule set is an example of how to code a very
+	secure inclusive type of firewall.  An inclusive firewall only
+	allows services matching pass rules through and blocks all
+	other by default.  All firewalls have at the minimum two
+	interfaces which have to have rules to allow the firewall to
+	function.</para>
+
+      <para>All &unix; flavored systems including &os; are designed to
+	use interface <devicename>lo0</devicename> and IP address
+	<hostid role="ipaddr">127.0.0.1</hostid> for internal
+	communication within the operating system.  The firewall rules
+	must contain rules to allow free unmolested movement of these
+	special internally used packets.</para>
+
+      <para>The interface which faces the public Internet is the one
+	where you place your rules to authorize and control access out
+	to the public Internet and access requests arriving from the
+	public Internet.  This can be your user PPP
+	<devicename>tun0</devicename> interface or your NIC that is
+	connected to your DSL or cable modem.</para>
+
+      <para>In cases where one or more NICs are cabled to private LANs
+	behind the firewall, those interfaces must have a rule coded to
+	allow free unmolested movement of packets originating from
+	those LAN interfaces.</para>
+
+      <para>The rules should be first organized into three major
+	sections: all the free unmolested interfaces, the public
+	interface outbound, and the public interface inbound.</para>
+
+      <para>The rules in each of the public interface sections should
+	have the most frequently matched rules placed before less
+	commonly matched rules, with the last rule in the section
+	blocking and logging all packets on that interface and
+	direction.</para>
+
+      <para>The Outbound section in the following rule set only
+	contains 'pass' rules which contain selection values that
+	uniquely identify the service that is authorized for public
+	Internet access.  All the rules have the 'quick', 'on',
+	'proto', 'port', and 'keep state' option coded.  The 'proto
+	tcp' rules have the 'flag' option included to identify the
+	session start request as the triggering packet to activate the
+	stateful facility.</para>
+
+      <para>The Inbound section has all the blocking of undesirable
+	packets first, for two different reasons.  The first is that
+	these things being blocked may be part of an otherwise valid
+	packet which may be allowed in by the later authorized service
+	rules.  The second reason is that by having a rule that
+	explicitly blocks selected packets that I receive on an
+	infrequent basis and that I do not want to see in the log, they
+	will not be caught by the last rule in the section which blocks
+	and logs all packets which have fallen through the rules.  The
+	last rule in the section which blocks and logs all packets is
+	how you create the legal evidence needed to prosecute the
+	people who are attacking your system.</para>
+
+      <para>Another thing you should take note of, is there is no
+	response returned for any of the undesirable stuff, their
+	packets just get dropped and vanish.  This way the attacker
+	has no knowledge if his packets have reached your system.  The
+	less the attackers can learn about your system, the more
+	time they must invest before actually doing something bad.
+	The inbound 'nmap OS fingerprint' attempts rule I log
+
+	<!-- XXX: what? -->
+
+	the first occurrence because this is something a attacker
+	would do.</para>
+
+      <para>Any time you see log messages on a rule with 'log first'.
+	You should do an <command>ipfstat -hio</command> command to see
+	the number of times the rule has been matched so you know if
+	you are being flooded, i.e. under attack.</para>
+
+      <para>When you log packets with port numbers you do not
+	recognize, look it up in <filename>/etc/services</filename> or
+	go to <ulink
+	  url="http://www.securitystats.com/tools/portsearch.php"></ulink>
+	and do a port number lookup to find what the purpose of that
+	port number is.</para>
+
+      <para>Check out this link for port numbers used by Trojans <ulink
+	  url="http://www.simovits.com/trojans/trojans.html"></ulink>.</para>
+
+      <para>The following rule set is a complete very secure
+	'inclusive' type of firewall rule set that I have used on my
+	system.  You can not go wrong using this rule set for your own.
+	Just comment out any pass rules for services that you do not
+	want to authorize.</para>
+
+      <para>If you see messages in your log that you want to stop
+	seeing just add a block rule in the inbound section.</para>
+
+      <para>You have to change the <devicename>dc0</devicename>
+	interface name in every rule to the interface name of the Nic
+	card that connects your system to the public Internet.  For
+	user PPP it would be <devicename>tun0</devicename>.</para>
+
+      <para>Add the following statements to
+	<filename>/etc/ipf.rules</filename>:</para>
+
+      <programlisting>#################################################################
+# No restrictions on Inside LAN Interface for private network
+# Not needed unless you have LAN
+#################################################################
+
+#pass out quick on xl0 all
+#pass in quick on xl0 all
+
+#################################################################
+# No restrictions on Loopback Interface
+#################################################################
+pass in quick on lo0 all
+pass out quick on lo0 all
+
+#################################################################
+# Interface facing Public Internet (Outbound Section)
+# Interrogate session start requests originating from behind the
+# firewall on the private network
+# or from this gateway server destine for the public Internet.
+#################################################################
+
+# Allow out access to my ISP's Domain name server.
+# xxx must be the IP address of your ISP's DNS.
+# Dup these lines if your ISP has more than one DNS server
+# Get the IP addresses from /etc/resolv.conf file
+pass out quick on dc0 proto tcp from any to xxx port = 53 flags S keep state
+pass out quick on dc0 proto udp from any to xxx port = 53 keep state
+
+# Allow out access to my ISP's DHCP server for cable or DSL networks.
+# This rule is not needed for 'user ppp' type connection to the
+# public Internet, so you can delete this whole group.
+# Use the following rule and check log for IP address.
+# Then put IP address in commented out rule &amp; delete first rule
+pass out log quick on dc0 proto udp from any to any port = 67 keep state
+#pass out quick on dc0 proto udp from any to z.z.z.z port = 67 keep state
+
+
+# Allow out non-secure standard www function
+pass out quick on dc0 proto tcp from any to any port = 80 flags S keep state
+
+# Allow out secure www function https over TLS SSL
+pass out quick on dc0 proto tcp from any to any port = 443 flags S keep state
+
+# Allow out send &amp; get email function
+pass out quick on dc0 proto tcp from any to any port = 110 flags S keep state
+pass out quick on dc0 proto tcp from any to any port = 25 flags S keep state
+
+# Allow out Time
+pass out quick on dc0 proto tcp from any to any port = 37 flags S keep state
+
+# Allow out nntp news
+pass out quick on dc0 proto tcp from any to any port = 119 flags S keep state
+
+# Allow out gateway &amp; LAN users non-secure FTP ( both passive &amp; active modes)
+# This function uses the IP<acronym>NAT</acronym> built in FTP proxy function coded in
+# the nat rules file to make this single rule function correctly.
+# If you want to use the pkg_add command to install application packages
+# on your gateway system you need this rule.
+pass out quick on dc0 proto tcp from any to any port = 21 flags S keep state
+
+# Allow out secure FTP, Telnet, and SCP
+# This function is using SSH (secure shell)
+pass out quick on dc0 proto tcp from any to any port = 22 flags S keep state
+
+# Allow out non-secure Telnet
+pass out quick on dc0 proto tcp from any to any port = 23 flags S keep state
+
+# Allow out FBSD CVSUP function
+pass out quick on dc0 proto tcp from any to any port = 5999 flags S keep state
+
+# Allow out ping to public Internet
+pass out quick on dc0 proto icmp from any to any icmp-type 8 keep state
+
+# Allow out whois for LAN PC to public Internet
+pass out quick on dc0 proto tcp from any to any port = 43 flags S keep state
+
+# Block and log only the first occurrence of everything
+# else that's trying to get out.
+# This rule enforces the block all by default logic.
+block out log first quick on dc0 all
+
+#################################################################
+# Interface facing Public Internet (Inbound Section)
+# Interrogate packets originating from the public Internet
+# destine for this gateway server or the private network.
+#################################################################
+
+# Block all inbound traffic from non-routable or reserved address spaces
+block in quick on dc0 from 192.168.0.0/16 to any    #RFC 1918 private IP
+block in quick on dc0 from 172.16.0.0/12 to any     #RFC 1918 private IP
+block in quick on dc0 from 10.0.0.0/8 to any        #RFC 1918 private IP
+block in quick on dc0 from 127.0.0.0/8 to any       #loopback
+block in quick on dc0 from 0.0.0.0/8 to any         #loopback
+block in quick on dc0 from 169.254.0.0/16 to any    #DHCP auto-config
+block in quick on dc0 from 192.0.2.0/24 to any      #reserved for docs
+block in quick on dc0 from 204.152.64.0/23 to any   #Sun cluster interconnect
+block in quick on dc0 from 224.0.0.0/3 to any       #Class D &amp; E multicast
+
+##### Block a bunch of different nasty things. ############
+# That I do not want to see in the log
+
+# Block frags
+block in quick on dc0 all with frags
+
+# Block short tcp packets
+block in quick on dc0 proto tcp all with short
+
+# block source routed packets
+block in quick on dc0 all with opt lsrr
+block in quick on dc0 all with opt ssrr
+
+# Block nmap OS fingerprint attempts
+# Log first occurrence of these so I can get their IP address
+block in log first quick on dc0 proto tcp from any to any flags FUP
+
+# Block anything with special options
+block in quick on dc0 all with ipopts
+
+# Block public pings
+block in quick on dc0 proto icmp all icmp-type 8
+
+# Block ident
+block in quick on dc0 proto tcp from any to any port = 113
+
+# Block all Netbios service. 137=name, 138=datagram, 139=session
+# Netbios is MS/Windows sharing services.
+# Block MS/Windows hosts2 name server requests 81
+block in log first quick on dc0 proto tcp/udp from any to any port = 137
+block in log first quick on dc0 proto tcp/udp from any to any port = 138
+block in log first quick on dc0 proto tcp/udp from any to any port = 139
+block in log first quick on dc0 proto tcp/udp from any to any port = 81
+
+# Allow traffic in from ISP's DHCP server. This rule must contain
+# the IP address of your ISP's DHCP server as it's the only
+# authorized source to send this packet type. Only necessary for
+# cable or DSL configurations. This rule is not needed for
+# 'user ppp' type connection to the public Internet.
+# This is the same IP address you captured and
+# used in the outbound section.
+pass in quick on dc0 proto udp from z.z.z.z to any port = 68 keep state
+
+# Allow in standard www function because I have apache server
+pass in quick on dc0 proto tcp from any to any port = 80 flags S keep state
+
+# Allow in non-secure Telnet session from public Internet
+# labeled non-secure because ID/PW passed over public Internet as clear text.
+# Delete this sample group if you do not have telnet server enabled.
+#pass in quick on dc0 proto tcp from any to any port = 23 flags S keep state
+
+# Allow in secure FTP, Telnet, and SCP from public Internet
+# This function is using SSH (secure shell)
+pass in quick on dc0 proto tcp from any to any port = 22 flags S keep state
+
+# Block and log only first occurrence of all remaining traffic
+# coming into the firewall. The logging of only the first
+# occurrence stops a .denial of service. attack targeted
+# at filling up your log file space.
+# This rule enforces the block all by default logic.
+block in log first quick on dc0 all
+################### End of rules file #####################################</programlisting>
+    </sect2>
+
+    <sect2>
+      <title><acronym>NAT</acronym></title>
+
+      <indexterm><primary>NAT</primary></indexterm>
+
+      <indexterm>
+	<primary>IP masquerading</primary>
+
+	<see>NAT</see>
+      </indexterm>
+
+      <indexterm>
+	<primary>network address translation</primary>
+
+	<see>NAT</see>
+      </indexterm>
+
+      <para><acronym>NAT</acronym> stands for Network Address
+	Translation.  To those familiar with &linux;, this concept is
+	called IP Masquerading; <acronym>NAT</acronym> and IP
+	Masquerading are the same thing.  One of the many things the
+	IPF <acronym>NAT</acronym> function enables is the ability to
+	have a private Local Area Network (LAN) behind the firewall
+	sharing a single ISP assigned IP address on the public
+	Internet.</para>
+
+      <para>You may ask why would someone want to do this.  ISPs
+	normally assign a dynamic IP address to their non-commercial
+	users.  Dynamic means that the IP address can be different each
+	time you dial in and log on to your ISP, or for cable and DSL
+	modem users when you power off and then power on your modems
+	you can get assigned a different IP address.  This IP address
+	is how you are known to the public Internet.</para>
+
+      <para>Now lets say you have five PCs at home and each one needs
+	Internet access.  You would have to pay your ISP for an
+	individual Internet account for each PC and have five phone
+	lines.</para>
+
+      <para>With <acronym>NAT</acronym> you only need a single account
+	with your ISP, then cable your other four PCs to a switch and
+	the switch to the NIC in your &os; system which is going to
+	service your LAN as a gateway. <acronym>NAT</acronym> will
+	automatically translate the private LAN IP address for each
+	separate PC on the LAN to the single public IP address as it
+	exits the firewall bound for the public Internet.  It also does
+	the reverse translation for returning packets.</para>
+
+      <para><acronym>NAT</acronym> is most often accomplished without
+	the approval, or knowledge, of your ISP and in most cases is
+	grounds for your ISP terminating your account if found out.
+	Commercial users pay a lot more for their Internet connection
+	and usually get assigned a block of static IP address which
+	never change.  The ISP also expects and consents to their
+	Commercial customers using <acronym>NAT</acronym> for their
+	internal private LANs.</para>
+
+      <para>There is a special range of IP addresses reserved for
+	<acronym>NAT</acronym>ed private LAN IP address.  According to
+	RFC 1918, you can use the following IP ranges for private nets
+	which will never be routed directly to the public
+	Internet:</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <colspec colwidth="1*">
+
+	  <colspec colwidth="1*">
+
+	  <colspec colwidth="1*">
+
+	  <tbody>
+	    <row>
+	      <entry>Start IP <hostid role="ipaddr">10.0.0.0</hostid></entry>
+
+	      <entry>-</entry>
+
+	      <entry>Ending IP <hostid role="ipaddr">10.255.255.255</hostid></entry>
+	    </row>
+
+	    <row>
+	      <entry>Start IP <hostid role="ipaddr">172.16.0.0</hostid></entry>
+
+	      <entry>-</entry>
+
+	      <entry>Ending IP <hostid role="ipaddr">172.31.255.255</hostid></entry>
+	    </row>
+
+	    <row>
+	      <entry>Start IP <hostid role="ipaddr">192.168.0.0</hostid></entry>
+
+	      <entry>-</entry>
+
+	      <entry>Ending IP <hostid role="ipaddr">192.168.255.255</hostid></entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+    </sect2>
+
+    <sect2>
+      <title>IP<acronym>NAT</acronym></title>
+
+      <indexterm>
+	<primary>NAT</primary>
+
+	<secondary>and IPFILTER</secondary>
+      </indexterm>
+
+      <indexterm><primary><command>ipnat</command></primary></indexterm>
+
+      <para><acronym>NAT</acronym> rules are loaded by using the
+	<command>ipnat</command> command.  Typically the
+	<acronym>NAT</acronym> rules are stored in
+	<filename>/etc/ipnat.rules</filename>.  See &man.ipnat.1; for
+	details.</para>
+
+      <para>When changing the <acronym>NAT</acronym> rules after
+	<acronym>NAT</acronym> has been started, make your changes to
+	the file containing the NAT rules, then run ipnat command with
+	the <option>-CF</option> flags to delete the internal in use
+	<acronym>NAT</acronym> rules and flush the contents of the
+	translation table of all active entries.</para>
+
+      <para>To reload the <acronym>NAT</acronym> rules issue a command
+	like this:</para>
+
+      <screen>&prompt.root; <userinput>ipnat -CF -f /etc/ipnat.rules</userinput></screen>
+
+      <para>To display some statistics about your
+	<acronym>NAT</acronym>, use this command:</para>
+
+      <screen>&prompt.root; <userinput>ipnat -s</userinput></screen>
+
+      <para>To list the <acronym>NAT</acronym> table's current
+	mappings, use this command:</para>
+
+      <screen>&prompt.root; <userinput>ipnat -l</userinput></screen>
+
+      <para>To turn verbose mode on, and display information relating
+	to rule processing and active rules/table entries:</para>
+
+      <screen>&prompt.root; <userinput>ipnat -v</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>IP<acronym>NAT</acronym> Rules</title>
+
+      <para><acronym>NAT</acronym> rules are very flexible and can
+	accomplish many different things to fit the needs of commercial
+	and home users.</para>
+
+      <para>The rule syntax presented here has been simplified to what
+	is most commonly used in a non-commercial environment.  For a
+	complete rule syntax description see the &man.ipnat.5; manual
+	page.</para>
+
+      <para>The syntax for a <acronym>NAT</acronym> rule looks
+	something like this:</para>
+
+      <programlisting>map <replaceable>IF</replaceable> <replaceable>LAN_IP_RANGE</replaceable> -&gt; <replaceable>PUBLIC_ADDRESS</replaceable></programlisting>
+
+      <para>The keyword <literal>map</literal> starts the rule.</para>
+
+      <para>Replace <replaceable>IF</replaceable> with the external
+	interface.</para>
+
+      <para>The <replaceable>LAN_IP_RANGE</replaceable> is what your
+	internal clients use for IP Addressing, usually this is
+	something like <hostid
+	  role="ipaddr">192.168.1.0/24</hostid>.</para>
+
+      <para>The <replaceable>PUBLIC_ADDRESS</replaceable> can either
+	be the external IP address or the special keyword
+	<literal>0/32</literal>, which means to use the IP address
+	assigned to <replaceable>IF</replaceable>.</para>
+    </sect2>
+
+    <sect2>
+      <title>How <acronym>NAT</acronym> works</title>
+
+      <para>A packet arrives at the firewall from the LAN with a public
+	destination.  It passes through the outbound filter rules,
+	<acronym>NAT</acronym> gets his turn at the packet and applies
+	its rules top down, first matching rule wins.
+	<acronym>NAT</acronym> tests each of its rules against the
+	packets interface name and source IP address.  When a packets
+	interface name matches a <acronym>NAT</acronym> rule then the
+	[source IP address, i.e. private LAN IP address] of the packet
+	is checked to see if it falls within the IP address range
+	specified to the left of the arrow symbol on the
+	<acronym>NAT</acronym> rule.  On a match the packet has its
+	source IP address rewritten with the public IP address
+	obtained by the <literal>0/32</literal> keyword.
+	<acronym>NAT</acronym> posts a entry in its internal
+	<acronym>NAT</acronym> table so when the packet returns from
+	the public Internet it can be mapped back to its original
+	private IP address and then passed to the filter rules for
+	processing.</para>
+    </sect2>
+
+    <sect2>
+      <title>Enabling IP<acronym>NAT</acronym></title>
+
+      <para>To enable IP<acronym>NAT</acronym> add these statements to
+	<filename>/etc/rc.conf</filename>.</para>
+
+      <para>To enable your machine to route traffic between
+	interfaces:</para>
+
+      <programlisting>gateway_enable="YES"</programlisting>
+
+      <para>To start IP<acronym>NAT</acronym> automatically each
+	time:</para>
+
+      <programlisting>ipnat_enable="YES"</programlisting>
+
+      <para>To specify where to load the IP<acronym>NAT</acronym> rules
+	from:</para>
+
+      <programlisting>ipnat_rules="/etc/ipnat.rules"</programlisting>
+    </sect2>
+
+    <sect2>
+      <title><acronym>NAT</acronym> for a very large LAN</title>
+
+      <para>For networks that have large numbers of PC's on the LAN or
+	networks with more than a single LAN, the process of funneling
+	all those private IP addresses into a single public IP address
+	becomes a resource problem that may cause problems with the
+	same port numbers being used many times across many
+	<acronym>NAT</acronym>ed LAN PC's, causing collisions.  There
+	are two ways to relieve this resource problem.</para>
+
+      <sect3>
+	<title>Assigning Ports to Use</title>
+
+	<!-- What does it mean ? Is there something missing ?-->
+	<!-- XXXBLAH <- Apparently you can't start a sect
+	     with a <programlisting> tag ?-->
+
+	<para>A normal NAT rule would look like:</para>
+
+	<programlisting>map dc0 192.168.1.0/24 -&gt; 0/32</programlisting>
+
+	<para>In the above rule the packet's source port is unchanged
+	  as the packet passes through IP<acronym>NAT</acronym>.  By
+	  adding the portmap keyword you can tell
+	  IP<acronym>NAT</acronym> to only use source ports in a range.
+	  For example the following rule will tell
+	  IP<acronym>NAT</acronym> to modify the source port to be
+	  within that range:</para>
+
+	<programlisting>map dc0 192.168.1.0/24 -&gt; 0/32 portmap tcp/udp 20000:60000</programlisting>
+
+	<para>Additionally we can make things even easier by using the
+	  <literal>auto</literal> keyword to tell
+	  IP<acronym>NAT</acronym> to determine by itself which ports
+	  are available to use:</para>
+
+	<programlisting>map dc0 192.168.1.0/24 -&gt; 0/32 portmap tcp/udp auto</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>Using a pool of public addresses</title>
+
+	<para>In very large LANs there comes a point where there are just too
+	  many LAN addresses to fit into a single public address.  If a block
+	  of public IP addresses is available, you can use these addresses as
+	  a <quote>pool</quote>, and let IP<acronym>NAT</acronym> pick one of
+	  the public IP addresses as packet-addresses are mapped on their way
+	  out.</para>
+
+	<para>For example, instead of mapping all packets through a single
+	  public IP address, as in:</para>
+
+	<programlisting>map dc0 192.168.1.0/24 -&gt; 204.134.75.1</programlisting>
+
+	<para>A range of public IP addresses can be specified either with a
+	  netmask:</para>
+
+	<programlisting>map dc0 192.168.1.0/24 -&gt; 204.134.75.0/255.255.255.0</programlisting>
+
+	<para>or using CIDR notation:</para>
+
+	<programlisting>map dc0 192.168.1.0/24 -&gt; 204.134.75.0/24</programlisting>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Port Redirection</title>
+
+      <para>A very common practice is to have a web server, email
+	server, database server and DNS server each segregated to a
+	different PC on the LAN.  In this case the traffic from these
+	servers still have to be <acronym>NAT</acronym>ed, but there
+	has to be some way to direct the inbound traffic to the
+	correct LAN PCs.  IP<acronym>NAT</acronym> has the redirection
+	facilities of <acronym>NAT</acronym> to solve this problem.
+	Lets say you have your web server on LAN address <hostid
+	  role="ipaddr">10.0.10.25</hostid> and your single public IP
+	address is <hostid role="ipaddr">20.20.20.5</hostid> you would
+	code the rule like this:</para>
+
+	<programlisting>rdr dc0 20.20.20.5/32 port 80 -&gt; 10.0.10.25 port 80</programlisting>
+
+	<para>or:</para>
+
+	<programlisting>rdr dc0 0/32 port 80 -&gt; 10.0.10.25 port 80</programlisting>
+
+	<para>or for a LAN DNS Server on LAN address of <hostid
+	    role="ipaddr">10.0.10.33</hostid> that needs to receive
+	  public DNS requests:</para>
+
+	<programlisting>rdr dc0 20.20.20.5/32 port 53 -&gt; 10.0.10.33 port 53 udp</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>FTP and <acronym>NAT</acronym></title>
+
+      <para>FTP is a dinosaur left over from the time before the
+	Internet as it is known today, when research universities were
+	leased lined together and FTP was used to share files among
+	research Scientists.  This was a time when data security was
+	not a consideration.  Over the years the FTP protocol became
+	buried into the backbone of the emerging Internet and its
+	username and password being sent in clear text was never
+	changed to address new security concerns.  FTP has two flavors,
+	it can run in active mode or passive mode.  The difference is
+	in how the data channel is acquired.  Passive mode is more
+	secure as the data channel is acquired be the ordinal ftp
+	session requester.  For a real good explanation of FTP and the
+	different modes see <ulink
+	  url="http://www.slacksite.com/other/ftp.html"></ulink>.</para>
+
+      <sect3>
+	<title>IP<acronym>NAT</acronym> Rules</title>
+
+	<para>IP<acronym>NAT</acronym> has a special built in FTP proxy
+	  option which can be specified on the <acronym>NAT</acronym>
+	  map rule.  It can monitor all outbound packet traffic for FTP
+	  active or passive start session requests and dynamically
+	  create temporary filter rules containing only the port number
+	  really in use for the data channel.  This eliminates the
+	  security risk FTP normally exposes the firewall to from
+	  having large ranges of high order port numbers open.</para>
+
+	<para>This rule will handle all the traffic for the internal
+	  LAN:</para>
+
+	<programlisting>map dc0 10.0.10.0/29 -&gt; 0/32 proxy port 21 ftp/tcp</programlisting>
+
+	<para>This rule handles the FTP traffic from the
+	  gateway:</para>
+
+	<programlisting>map dc0 0.0.0.0/0 -&gt; 0/32 proxy port 21 ftp/tcp</programlisting>
+
+	<para>This rule handles all non-FTP traffic from the internal
+	  LAN:</para>
+
+	<programlisting>map dc0 10.0.10.0/29 -&gt; 0/32</programlisting>
+
+	<para>The FTP map rule goes before our regular map rule.  All
+	  packets are tested against the first rule from the top.
+	  Matches on interface name, then private LAN source IP
+	  address, and then is it a FTP packet.  If all that matches
+	  then the special FTP proxy creates temp filter rules to let
+	  the FTP session packets pass in and out, in addition to also
+	  <acronym>NAT</acronym>ing the FTP packets.  All LAN packets
+	  that are not FTP do not match the first rule and fall
+	  through to the third rule and are tested, matching on
+	  interface and source IP, then are
+	  <acronym>NAT</acronym>ed.</para>
+      </sect3>
+
+      <sect3>
+	<title>IP<acronym>NAT</acronym> FTP Filter Rules</title>
+
+	<para>Only one filter rule is needed for FTP if the
+	  <acronym>NAT</acronym> FTP proxy is used.</para>
+
+	<para>Without the FTP Proxy you will need the following three
+	  rules:</para>
+
+	<programlisting># Allow out LAN PC client FTP to public Internet
+# Active and passive modes
+pass out quick on rl0 proto tcp from any to any port = 21 flags S keep state
+
+# Allow out passive mode data channel high order port numbers
+pass out quick on rl0 proto tcp from any to any port &gt; 1024 flags S keep state
+
+# Active mode let data channel in from FTP server
+pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>FTP <acronym>NAT</acronym> Proxy Bug</title>
+
+	<para>As of IPFILTER version 3.4.31
+	  the FTP proxy works as documented during the FTP session
+	  until the session is told to close.  When the close happens
+	  packets returning from the remote FTP server are blocked and
+	  logged coming in on port 21.  The <acronym>NAT</acronym>
+	  FTP/proxy appears to remove its temp rules prematurely,
+	  before receiving the response from the remote FTP server
+	  acknowledging the close.  A problem report was posted to the
+	  IPF mailing list.</para>
+
+	<para>The solution is to add a filter rule to get rid of these
+	  unwanted log messages or do nothing and ignore FTP inbound
+	  error messages in your log.  Most people do not use outbound
+	  FTP too often.</para>
+
+	<programlisting>block in quick on rl0 proto tcp from any to any port = 21</programlisting>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="firewalls-ipfw">
+    <title>IPFW</title>
+
+    <indexterm>
+      <primary>firewall</primary>
+
+      <secondary>IPFW</secondary>
+    </indexterm>
+
+    <note>
+      <para>This section is work in progress.  The contents might
+	not be accurate at all times.</para>
+    </note>
+
+    <para>The IPFIREWALL (IPFW) is a &os; sponsored firewall software
+      application authored and maintained by &os; volunteer staff
+      members.  It uses the legacy stateless rules and a legacy rule
+      coding technique to achieve what is referred to as Simple
+      Stateful logic.</para>
+
+    <para>The IPFW sample rule set (found in
+      <filename>/etc/rc.firewall</filename>) in the standard &os;
+      install is rather simple and it is not expected that it used
+      directly without modifications.  The example does not use
+      stateful filtering, which is beneficial in most setups, so it
+      will not be used as base for this section.</para>
+
+    <para>The IPFW stateless rule syntax is empowered with technically
+      sophisticated selection capabilities which far surpasses the
+      knowledge level of the customary firewall installer.  IPFW is
+      targeted at the professional user or the advanced technical
+      computer hobbyist who have advanced packet selection
+      requirements.  A high degree of detailed knowledge into how
+      different protocols use and create their unique packet header
+      information is necessary before the power of the IPFW rules can
+      be unleashed.  Providing that level of explanation is out of the
+      scope of this section of the handbook.</para>
+
+    <para>IPFW is composed of seven components, the primary component
+      is the kernel firewall filter rule processor and its integrated
+      packet accounting facility, the logging facility, the 'divert'
+      rule which triggers the <acronym>NAT</acronym> facility, and the
+      advanced special purpose facilities, the dummynet traffic shaper
+      facilities, the 'fwd rule' forward facility, the bridge
+      facility, and the ipstealth facility.</para>
+
+    <sect2 id="firewalls-ipfw-enable">
+      <title>Enabling IPFW</title>
+
+      <indexterm>
+	<primary>IPFW</primary>
+
+	<secondary>enabling</secondary>
+      </indexterm>
+
+      <para>IPFW is included in the basic &os; install as a separate
+	run time loadable module.  The system will dynamically load the
+	kernel module when the <filename>rc.conf</filename> statement
+	<literal>firewall_enable="YES"</literal> is used.  You do not
+	need to compile IPFW into the &os; kernel unless you want
+	<acronym>NAT</acronym> function enabled.</para>
+
+      <para>After rebooting your system with
+	<literal>firewall_enable="YES"</literal> in
+	<filename>rc.conf</filename> the following white highlighted
+	message is displayed on the screen as part of the boot
+	process:</para>
+
+      <screen>ipfw2 initialized, divert disabled, rule-based forwarding disabled, default to deny, logging disabled</screen>
+
+      <para>The loadable module does have logging ability
+	compiled in.  To enable logging and set the verbose logging
+	limit, there is a knob you can set in
+	<filename>/etc/sysctl.conf</filename> by adding these
+	statements, logging will be enabled on future reboots:</para>
+
+      <programlisting>net.inet.ip.fw.verbose=1
+net.inet.ip.fw.verbose_limit=5</programlisting>
+    </sect2>
+
+    <sect2 id="firewalls-ipfw-kernel">
+      <title>Kernel Options</title>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFIREWALL</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFIREWALL_VERBOSE</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFIREWALL_VERBOSE_LIMIT</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>IPFW</primary>
+
+	<secondary>kernel options</secondary>
+      </indexterm>
+
+      <para>It is not a mandatory requirement that you enable IPFW by
+	compiling the following options into the &os; kernel unless
+	you need <acronym>NAT</acronym> function.  It is presented here
+	as background information.</para>
+
+      <programlisting>options    IPFIREWALL</programlisting>
+
+      <para>This option enables IPFW as part of the kernel</para>
+
+      <programlisting>options    IPFIREWALL_VERBOSE</programlisting>
+
+      <para>Enables logging of packets that pass through IPFW and have
+	the 'log' keyword specified in the rule set.</para>
+
+      <programlisting>options    IPFIREWALL_VERBOSE_LIMIT=5</programlisting>
+
+      <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 which you want to log firewall activity.
+	This will close a possible denial of service attack via syslog
+	flooding.</para>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPFIREWALL_DEFAULT_TO_ACCEPT</secondary>
+      </indexterm>
+
+      <programlisting>options    IPFIREWALL_DEFAULT_TO_ACCEPT</programlisting>
+
+      <para>This option will allow everything to pass through the
+	firewall by default, which is a good idea when you are first
+	setting up your firewall.</para>
+
+      <programlisting>options    IPV6FIREWALL
+options    IPV6FIREWALL_VERBOSE
+options    IPV6FIREWALL_VERBOSE_LIMIT
+options    IPV6FIREWALL_DEFAULT_TO_ACCEPT</programlisting>
+
+      <para>These options are exactly the same as the IPv4 options but
+	they are for IPv6.  If you do not use IPv6 you might want to
+	use IPV6FIREWALL without any rules to block all IPv6</para>
+
+      <indexterm>
+	<primary>kernel options</primary>
+
+	<secondary>IPDIVERT</secondary>
+      </indexterm>
+
+      <programlisting>options    IPDIVERT</programlisting>
+
+      <para>This enables the use of <acronym>NAT</acronym>
+	functionality.</para>
+
+      <note>
+	<para>If you do not include IPFIREWALL_DEFAULT_TO_ACCEPT or set
+	  your rules to allow incoming packets you will block all
+	  packets going to and from this machine.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="firewalls-ipfw-rc">
+      <title><filename>/etc/rc.conf</filename> Options</title>
+
+      <para>If you do not have IPFW compiled into your kernel you will
+	need to load it with the following statement in your
+	<filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>firewall_enable="YES"</programlisting>
+
+      <para>To select one of the default firewall types provided by
+	&os;, select one by reading the
+	<filename>/etc/rc.firewall</filename> file and place it in
+	the following:</para>
+
+      <programlisting>firewall_type="open"</programlisting>
+
+      <para>Or load custom rules by setting the following variable to the
+	file containing them:</para>
+
+      <programlisting>firewall_script="/etc/ipfw.rules"</programlisting>
+
+      <para>Enable logging:</para>
+
+      <programlisting>firewall_logging="YES"</programlisting>
+
+      <warning>
+	<para>The only thing that the
+	  <varname>firewall_logging</varname> variable will do is
+	  setting the <varname>net.inet.ip.fw.verbose</varname> sysctl
+	  variable to the value of <literal>1</literal> (see <xref
+	    linkend="firewalls-ipfw-enable">).  There is no
+	  <filename>rc.conf</filename> variable to set log limitations,
+	  but it can be set via sysctl variable, manually or from the
+	  <filename>/etc/sysctl.conf</filename> file:</para>
+
+	<programlisting>net.inet.ip.fw.verbose_limit=5</programlisting>
+      </warning>
+
+      <para>If your machine is acting as a gateway, i.e. providing
+	Network Address Translation (NAT) via &man.natd.8;, please
+	refer to <xref linkend="network-natd"> for information
+	regarding the required <filename>/etc/rc.conf</filename>
+	options.</para>
+    </sect2>
+
+    <sect2 id="firewalls-ipfw-cmd">
+      <title>The IPFW Command</title>
+
+      <indexterm><primary><command>ipfw</command></primary></indexterm>
+
+      <para>The ipfw command is the normal vehicle for making manual
+	single rule additions or deletions to the firewall active
+	internal rules while it is running.  The problem with using
+	this method is once your system is shutdown or halted all the
+	rules you added or changed or deleted are lost.  Writing all
+	your rules in a file and using that file to load the rules at
+	boot time, or to replace in mass the currently running firewall
+	rules with changes you made to the files content is the
+	recommended method used here.</para>
+
+      <para>The ipfw command is still a very useful to display the
+	running firewall rules to the console screen.  The IPFW
+	accounting facility dynamically creates a counter for each
+	rule that counts each packet that matches the rule.  During the
+	process of testing a rule, listing the rule with its counter
+	is the one of the ways of determining if the rule is
+	functioning.</para>
+
+      <para>To list all the rules in sequence:</para>
+
+      <screen>&prompt.root; <userinput>ipfw list</userinput></screen>
+
+      <para>To list all the rules with a time stamp of when the last
+	time the rule was matched:</para>
+
+      <screen>&prompt.root; <userinput>ipfw -t list</userinput></screen>
+
+      <para>To list the accounting information, packet count for
+	matched rules along with the rules themselves.  The first
+	column is the rule number, followed by the number of outgoing
+	matched packets, followed by the number of incoming matched
+	packets, and then the rule itself.</para>
+
+      <screen>&prompt.root; <userinput>ipfw -a list</userinput></screen>
+
+      <para>List the dynamic rules in addition to the static
+	rules:</para>
+
+      <screen>&prompt.root; <userinput>ipfw -d list</userinput></screen>
+
+      <para>Also show the expired dynamic rules:</para>
+
+      <screen>&prompt.root; <userinput>ipfw -d -e list</userinput></screen>
+
+      <para>Zero the counters:</para>
+
+      <screen>&prompt.root; <userinput>ipfw zero</userinput></screen>
+
+      <para>Zero the counters for just rule
+	<replaceable>NUM</replaceable>:</para>
+
+      <screen>&prompt.root; <userinput>ipfw zero NUM</userinput></screen>
+    </sect2>
+
+    <sect2 id="firewalls-ipfw-rules">
+      <title>IPFW Rule Sets</title>
+
+      <!-- XXX: looks incorrect (and duplicated 2 times in this chapter):
+	    1. Packet can be processed two times depend of firewall
+	       firewall configuration, but "return trip back" is
+	       another packet.
+	    2. "Each TCP/IP service ... is predefined by its protocol ..."
+	       - this shold be about packet and it's parameters
+	       (source/destination address and port). -->
+
+      <para>A rule set is a group of ipfw rules coded to allow or deny
+	packets based on the values contained in the packet.  The
+	bi-directional exchange of packets between hosts comprises a
+	session conversation.  The firewall rule set processes the
+	packet twice: once on its arrival from the public Internet host
+	and again as it leaves for its return trip back to the public
+	Internet host.  Each tcp/ip service (i.e. telnet, www, mail,
+	etc.) is predefined by its protocol, and port number.  This is
+	the basic selection criteria used to create rules which will
+	allow or deny services.</para>
+
+      <indexterm>
+	<primary>IPFW</primary>
+
+	<secondary>rule processing order</secondary>
+      </indexterm>
+
+      <!-- Needs rewording to include note below -->
+
+      <para>When a packet enters the firewall it is compared against
+	the first rule in the rule set and progress one rule at a time
+	moving from top to bottom of the set in ascending rule number
+	sequence order.  When the packet matches a rule selection
+	parameters, the rules action field value is executed and the
+	search of the rule set terminates for that packet.  This is
+	referred to as <quote>the first match wins</quote> search
+	method.  If the packet does not match any of the rules, it gets
+	caught by the mandatory ipfw default rule, number 65535 which
+	denies all packets and discards them without any reply back to
+	the originating destination.</para>
+
+      <note>
+	<para>The search continues after <literal>count</literal>,
+	  <literal>skipto</literal> and <literal>tee</literal>
+	  rules.</para>
+      </note>
+
+      <para>The instructions contained here are based on using rules
+	that contain the stateful 'keep state', 'limit', 'in'/'out',
+	and via options.  This is the basic framework for coding an
+	inclusive type firewall rule set.</para>
+
+    <!-- XXX: something like this already in
+	 <xref linkend="firewalls-concepts">
+	 AND: the para below is repeated 3 times in this chapter. -->
+
+      <para>An inclusive firewall only allows services matching the
+	rules through.  This way you can control what services can
+	originate behind the firewall destine for the public Internet
+	and also control the services which can originate from the
+	public Internet accessing your private network.  Everything
+	else is denied by default design.  Inclusive firewalls are
+	much, much more secure than exclusive firewall rule sets and
+	is the only rule set type covered here in.</para>
+
+      <warning>
+	<para>When working with the firewall rules be careful, you can
+	  end up locking your self out.</para>
+      </warning>
+
+      <sect3 id="firewalls-ipfw-rules-syntax">
+	<title>Rule Syntax</title>
+
+	<indexterm>
+	  <primary>IPFW</primary>
+
+	  <secondary>rule syntax</secondary>
+	</indexterm>
+
+	<para>The rule syntax presented here has been simplified to
+	  what is necessary to create a standard inclusive type
+	  firewall rule set.  For a complete rule syntax description
+	  see the &man.ipfw.8; manual page.</para>
+
+	<para>Rules contain keywords: these keywords have to be coded
+	  in a specific order from left to right on the line.  Keywords
+	  are identified in bold type.  Some keywords have sub-options
+	  which may be keywords them selves and also include more
+	  sub-options.</para>
+
+	<para><literal>#</literal> is used to mark the start of a
+	  comment and may appear at the end of a rule line or on its
+	  own lines.  Blank lines are ignored.</para>
+
+	<para><replaceable>CMD RULE_NUMBER ACTION LOGGING SELECTION
+	    STATEFUL</replaceable></para>
+
+	<sect4>
+	  <title>CMD</title>
+
+	  <para>Each new rule has to be prefixed with
+	    <parameter>add</parameter> to add the
+	    rule to the internal table.</para>
+	</sect4>
+
+	<sect4>
+	  <title>RULE_NUMBER</title>
+
+	  <para>Each rule has to have a rule number to go with
+	    it.</para>
+	</sect4>
+
+	<sect4>
+	  <title>ACTION</title>
+
+	  <para>A rule can be associated with one of the following
+	    actions, which will be executed when the packet matches
+	    the selection criterion of the rule.</para>
+
+	  <para><parameter>allow | accept | pass |
+	      permit</parameter></para>
+
+	  <para>These all mean the same thing which is to allow packets
+	    that match the rule to exit the firewall rule processing.
+	    The search terminates at this rule.</para>
+
+	  <para><parameter>check-state</parameter></para>
+
+	  <para>Checks the packet against the dynamic rules table.  If
+	    a match is found, execute the action associated with the
+	    rule which generated this dynamic rule, otherwise move to
+	    the next rule.  The check-state rule does not have
+	    selection criterion.  If no check-state rule is present in
+	    the rule set, the dynamic rules table is checked at the
+	    first keep-state or limit rule.</para>
+
+	  <para><parameter>deny | drop</parameter></para>
+
+	  <para>Both words mean the same thing which is to discard
+	    packets that match this rule.  The search
+	    terminates.</para>
+	</sect4>
+
+	<sect4>
+	  <title>Logging</title>
+
+	  <para><parameter>log</parameter> or
+	    <parameter>logamount</parameter></para>
+
+	  <para>When a packet matches a rule with the log keyword, a
+	    message will be logged to syslogd with a facility name of
+	    SECURITY.  The logging only occurs if the number of
+	    packets logged so far for that particular rule does not
+	    exceed the logamount parameter.  If no logamount is
+	    specified, the limit is taken from the sysctl variable
+	    net.inet.ip.fw.verbose_limit.  In both cases, a value of
+	    zero removes the logging limit.  Once the limit is
+	    reached, logging can be re-enabled by clearing the
+	    logging counter or the packet counter for that rule, see
+	    the ipfw reset log command.</para>
+
+	  <note>
+	    <para>Logging is done after
+	      all other packet matching conditions have been
+	      successfully verified, and before performing the final
+	      action (accept, deny) on the packet.  It is up to you to
+	      decide which rules you want to enable logging on.</para>
+	    </note>
+	</sect4>
+
+	<sect4>
+	  <title>Selection</title>
+
+	  <para>The keywords described in this section are used to
+	    describe attributes of the packet to be interrogated when
+	    determining whether rules match the packet or not.
+	    The following general-purpose attributes are provided for
+	    matching, and must be used in this order:</para>
+
+	  <para><parameter>udp | tcp | icmp</parameter></para>
+
+	  <para>or any protocol names found in
+	    <filename>/etc/protocols</filename> are recognized and may
+	    be used.  The value specified is protocol to be matched
+	    against.  This is a mandatory requirement.</para>
+
+	  <para><parameter>from src to dst</parameter></para>
+
+	  <para>The from and to keywords are used to match against IP
+	    addresses.  Rules must specify BOTH source and destination
+	    parameters. <literal>any</literal> is a special keyword
+	    that matches any IP address. <literal>me</literal> is a
+	    special keyword that matches any IP address configured on
+	    an interface in your &os; system to represent the PC the
+	    firewall is running on (i.e. this box) as in 'from me to
+	    any' or 'from any to me' or 'from 0.0.0.0/0 to any' or
+	    'from any to 0.0.0.0/0' or 'from 0.0.0.0 to any' or 'from
+	    any to 0.0.0.0' or 'from me to 0.0.0.0'.  IP addresses are
+	    specified as a dotted IP address numeric form/mask-length,
+	    or as single dotted IP address numeric form.  This is a
+	    mandatory requirement.  See this link for help on writing
+	    mask-lengths. <ulink
+	      url="http://jodies.de/ipcalc"></ulink></para>
+
+	  <para><parameter>port number</parameter></para>
+
+	  <para>For protocols which support port numbers (such as
+	    <acronym>TCP</acronym> and UDP).  It is mandatory that you
+	    code the port number of the service you want to match
+	    on.  Service names (from
+	    <filename>/etc/services</filename>) may be used instead of
+	    numeric port values.</para>
+
+	  <para><parameter>in | out</parameter></para>
+
+	  <para>Matches incoming or outgoing packets, respectively.
+	    The in and out are keywords and it is mandatory that you
+	    code one or the other as part of your rule matching
+	    criterion.</para>
+
+	  <para><parameter>via IF</parameter></para>
+
+	  <para>Matches packets going through the interface specified
+	    by exact name.  The <literal>via</literal> keyword causes
+	    the interface to always be checked as part of the match
+	    process.</para>
+
+	  <para><parameter>setup</parameter></para>
+
+	  <para>This is a mandatory keyword that identifies the session
+	    start request for <acronym>TCP</acronym> packets.</para>
+
+	  <para><parameter>keep-state</parameter></para>
+
+	  <para>This is a mandatory> keyword.  Upon a match, the
+	    firewall will create a dynamic rule, whose default behavior
+	    is to match bidirectional traffic between source and
+	    destination IP/port using the same protocol.</para>
+
+	  <para><parameter>limit {src-addr | src-port | dst-addr |
+	      dst-port}</parameter></para>
+
+	  <para>The firewall will only allow
+	    <replaceable>N</replaceable> connections with the same set
+	    of parameters as specified in the rule.  One or more of
+	    source and destination addresses and ports can be
+	    specified.  The 'limit' and 'keep-state' can not be used on
+	    same rule.  Limit provides the same stateful function as
+	    'keep-state' plus its own functions.</para>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<title>Stateful Rule Option</title>
+
+	<indexterm>
+	  <primary>IPFW</primary>
+
+	  <secondary>stateful filtering</secondary>
+	</indexterm>
+
+	<!-- XXX: duplicated -->
+
+	<para>Stateful filtering treats traffic as a bi-directional
+	  exchange of packets comprising a session conversation.  It
+	  has the interrogation abilities to determine if the session
+	  conversation between the originating sender and the
+	  destination are following the valid procedure of
+	  bi-directional packet exchange.  Any packets that do not
+	  properly fit the session conversation template are
+	  automatically rejected as impostors.</para>
+
+	<para>'check-state' is used to identify where in the IPFW rules
+	  set the packet is to be tested against the dynamic rules
+	  facility.  On a match the packet exits the firewall to
+	  continue on its way and a new rule is dynamic created for
+	  the next anticipated packet being exchanged during this
+	  bi-directional session conversation.  On a no match the
+	  packet advances to the next rule in the rule set for
+	  testing.</para>
+
+	<para>The dynamic rules facility is vulnerable to resource
+	  depletion from a SYN-flood attack which would open a huge
+	  number of dynamic rules.  To counter this attack, &os;
+	  added another new option named limit.  This
+	  option is used to limit the number of simultaneous session
+	  conversations by interrogating the rules source or
+	  destinations fields as directed by the limit option and
+	  using the packet's IP address found there, in a search of
+	  the open dynamic rules counting the number of times this
+	  rule and IP address combination occurred, if this count is
+	  greater that the value specified on the limit option, the
+	  packet is discarded.</para>
+      </sect3>
+
+      <sect3>
+	<title>Logging Firewall Messages</title>
+
+	<indexterm>
+	  <primary>IPFW</primary>
+
+	  <secondary>logging</secondary>
+	</indexterm>
+
+	<para>The benefits of logging are obvious: it provides the
+	  ability to review after the fact the rules you activated
+	  logging on which provides information like, what packets had
+	  been dropped, what addresses they came from, where they were
+	  going, giving you a significant edge in tracking down
+	  attackers.</para>
+
+	<para>Even with the logging facility enabled, IPFW will not
+	  generate any rule logging on it's own.  The firewall
+	  administrator decides what rules in the rule set he wants
+	  to log and adds the log verb to those rules.  Normally only
+	  deny rules are logged, like the deny rule for incoming
+	  <acronym>ICMP</acronym> pings.  It is very customary to
+	  duplicate the ipfw default deny everything rule with the
+	  log verb included as your last rule in the rule set.  This
+	  way you get to see all the packets that did not match any
+	  of the rules in the rule set.</para>
+
+	<para>Logging is a two edged sword, if you are not careful, you
+	  can lose yourself in the over abundance of log data and fill
+	  your disk up with growing log files.  DoS attacks that fill
+	  up disk drives is one of the oldest attacks around.  These
+	  log message are not only written to syslogd, but also are
+	  displayed on the root console screen and soon become very
+	  annoying.</para>
+
+	<para>The <literal>IPFIREWALL_VERBOSE_LIMIT=5</literal>
+	  kernel option limits the number of consecutive messages
+	  sent to the system logger syslogd, concerning the packet
+	  matching of a given rule.  When this option is enabled in
+	  the kernel, the number of consecutive messages concerning
+	  a particular rule is capped at the number specified.  There
+	  is nothing to be gained from 200 log messages saying the
+	  same identical thing.  For instance, five consecutive
+	  messages concerning a particular rule would be logged to
+	  syslogd, the remainder identical consecutive messages would
+	  be counted and posted to the syslogd with a phrase like
+	  this:</para>
+
+	<programlisting>last message repeated 45 times</programlisting>
+
+	<para>All logged packets messages are written by default to
+	  <filename>/var/log/security</filename> file, which is defined
+	  in the <filename>/etc/syslog.conf</filename> file.</para>
+      </sect3>
+
+      <sect3 id="firewalls-ipfw-rules-script">
+	<title>Building a Rule Script</title>
+
+	<para>Most experienced IPFW users create a file containing the
+	  rules and code them in a manner compatible with running them
+	  as a script.  The major benefit of doing this is the firewall
+	  rules can be refreshed in mass without the need of rebooting
+	  the system to activate the new rules.  This method is very
+	  convenient in testing new rules as the procedure can be
+	  executed as many times as needed.  Being a script, you can
+	  use symbolic substitution to code frequent used values and
+	  substitution them in multiple rules.  You will see this in
+	  the following example.</para>
+
+	<para>The script syntax used here is compatible with the 'sh',
+	  'csh', 'tcsh' shells.  Symbolic substitution fields are
+	  prefixed with a dollar sign &dollar;.  Symbolic fields do not
+	  have the &dollar; prefix.  The value to populate the Symbolic
+	  field must be enclosed to "double quotes".</para>
+
+	<para>Start your rules file like this:</para>
+
+	<programlisting>############### start of example ipfw rules script #############
+#
+ipfw -q -f flush       # Delete all rules
+# Set defaults
+oif="tun0"             # out interface
+odns="192.0.2.11"      # ISP's DNS server IP address
+cmd="ipfw -q add "     # build rule prefix
+ks="keep-state"        # just too lazy to key this each time
+&dollar;cmd 00500 check-state
+&dollar;cmd 00502 deny all from any to any frag
+&dollar;cmd 00501 deny tcp from any to any established
+&dollar;cmd 00600 allow tcp from any to any 80 out via &dollar;oif setup &dollar;ks
+&dollar;cmd 00610 allow tcp from any to &dollar;odns 53 out via &dollar;oif setup &dollar;ks
+&dollar;cmd 00611 allow udp from any to &dollar;odns 53 out via &dollar;oif &dollar;ks
+################### End of example ipfw rules script ############</programlisting>
+
+	<para>That is all there is to it.  The rules are not important
+	  in this example, how the Symbolic substitution field are
+	  populated and used are.</para>
+
+	<para>If the above example was in
+	  <filename>/etc/ipfw.rules</filename> file, you could reload
+	  these rules by entering on the command line.</para>
+
+	<screen>&prompt.root; <userinput>sh /etc/ipfw.rules</userinput></screen>
+
+	<para>The <filename>/etc/ipfw.rules</filename> file could be
+	  located anywhere you want and the file could be named any
+	  thing you would like.</para>
+
+	<para>The same thing could also be accomplished by running
+	  these commands by hand:</para>
+
+	<screen>&prompt.root; <userinput>ipfw -q -f flush</userinput>
+&prompt.root; <userinput>ipfw -q add check-state</userinput>
+&prompt.root; <userinput>ipfw -q add deny all from any to any frag</userinput>
+&prompt.root; <userinput>ipfw -q add deny tcp from any to any established</userinput>
+&prompt.root; <userinput>ipfw -q add allow tcp from any to any 80 out via tun0 setup keep-state</userinput>
+&prompt.root; <userinput>ipfw -q add allow tcp from any to 192.0.2.11 53 out via tun0 setup keep-state</userinput>
+&prompt.root; <userinput>ipfw -q add 00611 allow udp from any to 192.0.2.11 53 out via tun0 keep-state</userinput></screen>
+      </sect3>
+
+      <sect3>
+	<title>Stateful Ruleset</title>
+
+	<para>The following non-<acronym>NAT</acronym>ed rule set is an
+	  example of how to code a very secure 'inclusive' type of
+	  firewall.  An inclusive firewall only allows services
+	  matching pass rules through and blocks all other by default.
+	  All firewalls have at the minimum two interfaces which have
+	  to have rules to allow the firewall to function.</para>
+
+	<para>All &unix; flavored operating systems, &os; included, are
+	  designed to use interface <devicename>lo0</devicename> and IP
+	  address <hostid role="ipaddr">127.0.0.1</hostid> for internal
+	  communication with in the operating system.  The firewall
+	  rules must contain rules to allow free unmolested movement of
+	  these special internally used packets.</para>
+
+	<para>The interface which faces the public Internet, is the one
+	  which you code your rules to authorize and control access out
+	  to the public Internet and access requests arriving from the
+	  public Internet.  This can be your ppp
+	  <devicename>tun0</devicename> interface or your NIC that is
+	  connected to your DSL or cable modem.</para>
+
+	<para>In cases where one or more than one NIC are connected to
+	  a private LANs behind the firewall, those interfaces must
+	  have rules coded to allow free unmolested movement of
+	  packets originating from those LAN interfaces.</para>
+
+	<para>The rules should be first organized into three major
+	  sections, all the free unmolested interfaces, public
+	  interface outbound, and the public interface inbound.</para>
+
+	<para>The order of the rules in each of the public interface
+	  sections should be in order of the most used rules being
+	  placed before less often used rules with the last rule in
+	  the section being a block log all packets on that interface
+	  and direction.</para>
+
+	<para>The Outbound section in the following rule set only
+	  contains 'allow' rules which contain selection values that
+	  uniquely identify the service that is authorized for public
+	  Internet access.  All the rules have the, proto, port,
+	  in/out, via and keep state option coded.  The 'proto tcp'
+	  rules have the 'setup' option included to identify the start
+	  session request as the trigger packet to be posted to the
+	  keep state stateful table.</para>
+
+	<para>The Inbound section has all the blocking of undesirable
+	  packets first for two different reasons.  First is these
+	  things being blocked may be part of an otherwise valid packet
+	  which may be allowed in by the later authorized service
+	  rules.  Second reason is that by having a rule that
+	  explicitly blocks selected packets that I receive on an
+	  infrequent bases and do not want to see in the log, this
+	  keeps them from being caught by the last rule in the section
+	  which blocks and logs all packets which have fallen through
+	  the rules.  The last rule in the section which blocks and
+	  logs all packets is how you create the legal evidence needed
+	  to prosecute the people who are attacking your system.</para>
+
+	<para>Another thing you should take note of, is there is no
+	  response returned for any of the undesirable stuff, their
+	  packets just get dropped and vanish.  This way the attackers
+	  has no knowledge if his packets have reached your system.
+	  The less the attackers can learn about your system the more
+	  secure it is.  When you log packets with port numbers you do
+	  not recognize, look the numbers up in
+	  <filename>/etc/services/</filename> or go to <ulink
+	    url="http://www.securitystats.com/tools/portsearch.php"></ulink>
+	  and do a port number lookup to find what the purpose of that
+	  port number is.  Check out this link for port numbers used by
+	  Trojans: <ulink
+	    url="http://www.simovits.com/trojans/trojans.html"></ulink>.</para>
+      </sect3>
+
+      <sect3>
+	<title>An Example Inclusive Ruleset</title>
+
+	<para>The following non-<acronym>NAT</acronym>ed rule set is a
+	  complete inclusive type ruleset.  You can not go wrong using
+	  this rule set for you own.  Just comment out any pass rules
+	  for services you do not want.  If you see messages in your
+	  log that you want to stop seeing just add a deny rule in the
+	  inbound section.  You have to change the 'dc0' interface name
+	  in every rule to the interface name of the NIC that connects
+	  your system to the public Internet.  For user ppp it would be
+	  'tun0'.</para>
+
+	<para>You will see a pattern in the usage of these
+	  rules.</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>All statements that are a request to start a session
+	      to the public Internet use keep-state.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>All the authorized services that originate from the
+	      public Internet have the limit option to stop
+	      flooding.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>All rules use in or out to clarify direction.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>All rules use via interface name to specify the
+	      interface the packet is traveling over.</para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>The following rules go into
+	  <filename>/etc/ipfw.rules</filename>.</para>
+
+	<programlisting>################ Start of IPFW rules file ###############################
+# Flush out the list before we begin.
+ipfw -q -f flush
+
+# Set rules command prefix
+cmd="ipfw -q add"
+pif="dc0"     # public interface name of NIC
+              # facing the public Internet
+
+#################################################################
+# No restrictions on Inside LAN Interface for private network
+# Not needed unless you have LAN.
+# Change xl0 to your LAN NIC interface name
+#################################################################
+#&dollar;cmd 00005 allow all from any to any via xl0
+
+#################################################################
+# No restrictions on Loopback Interface
+#################################################################
+&dollar;cmd 00010 allow all from any to any via lo0
+
+#################################################################
+# Allow the packet through if it has previous been added to the
+# the "dynamic" rules table by a allow keep-state statement.
+#################################################################
+&dollar;cmd 00015 check-state
+
+#################################################################
+# Interface facing Public Internet (Outbound Section)
+# Interrogate session start requests originating from behind the
+# firewall on the private network or from this gateway server
+# destine for the public Internet.
+#################################################################
+
+# Allow out access to my ISP's Domain name server.
+# x.x.x.x must be the IP address of your ISP.s DNS
+# Dup these lines if your ISP has more than one DNS server
+# Get the IP addresses from /etc/resolv.conf file
+&dollar;cmd 00110 allow tcp from any to x.x.x.x 53 out via &dollar;pif setup keep-state
+&dollar;cmd 00111 allow udp from any to x.x.x.x 53 out via &dollar;pif keep-state
+
+# Allow out access to my ISP's DHCP server for cable/DSL configurations.
+# This rule is not needed for .user ppp. connection to the public Internet.
+# so you can delete this whole group.
+# Use the following rule and check log for IP address.
+# Then put IP address in commented out rule &amp; delete first rule
+&dollar;cmd 00120 allow log udp from any to any 67 out via &dollar;pif keep-state
+#&dollar;cmd 00120 allow udp from any to x.x.x.x 67 out via &dollar;pif keep-state
+
+# Allow out non-secure standard www function
+&dollar;cmd 00200 allow tcp from any to any 80 out via &dollar;pif setup keep-state
+
+# Allow out secure www function https over TLS SSL
+&dollar;cmd 00220 allow tcp from any to any 443 out via &dollar;pif setup keep-state
+
+# Allow out send &amp; get email function
+&dollar;cmd 00230 allow tcp from any to any 25 out via &dollar;pif setup keep-state
+&dollar;cmd 00231 allow tcp from any to any 110 out via &dollar;pif setup keep-state
+
+# Allow out FBSD (make install &amp; CVSUP) functions
+# Basically give user root "GOD" privileges.
+&dollar;cmd 00240 allow tcp from me to any out via &dollar;pif setup keep-state uid root
+
+# Allow out ping
+&dollar;cmd 00250 allow icmp from any to any out via &dollar;pif keep-state
+
+# Allow out Time
+&dollar;cmd 00260 allow tcp from any to any 37 out via &dollar;pif setup keep-state
+
+# Allow out nntp news (i.e. news groups)
+&dollar;cmd 00270 allow tcp from any to any 119 out via &dollar;pif setup keep-state
+
+# Allow out secure FTP, Telnet, and SCP
+# This function is using SSH (secure shell)
+&dollar;cmd 00280 allow tcp from any to any 22 out via &dollar;pif setup keep-state
+
+# Allow out whois
+&dollar;cmd 00290 allow tcp from any to any 43 out via &dollar;pif setup keep-state
+
+# deny and log everything else that.s trying to get out.
+# This rule enforces the block all by default logic.
+&dollar;cmd 00299 deny log all from any to any out via &dollar;pif
+
+#################################################################
+# Interface facing Public Internet (Inbound Section)
+# Interrogate packets originating from the public Internet
+# destine for this gateway server or the private network.
+#################################################################
+
+# Deny all inbound traffic from non-routable reserved address spaces
+&dollar;cmd 00300 deny all from 192.168.0.0/16 to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 00301 deny all from 172.16.0.0/12 to any in via &dollar;pif     #RFC 1918 private IP
+&dollar;cmd 00302 deny all from 10.0.0.0/8 to any in via &dollar;pif          #RFC 1918 private IP
+&dollar;cmd 00303 deny all from 127.0.0.0/8 to any in via &dollar;pif        #loopback
+&dollar;cmd 00304 deny all from 0.0.0.0/8 to any in via &dollar;pif            #loopback
+&dollar;cmd 00305 deny all from 169.254.0.0/16 to any in via &dollar;pif   #DHCP auto-config
+&dollar;cmd 00306 deny all from 192.0.2.0/24 to any in via &dollar;pif       #reserved for docs
+&dollar;cmd 00307 deny all from 204.152.64.0/23 to any in via &dollar;pif  #Sun cluster interconnect
+&dollar;cmd 00308 deny all from 224.0.0.0/3 to any in via &dollar;pif         #Class D &amp; E multicast
+
+# Deny public pings
+&dollar;cmd 00310 deny icmp from any to any in via &dollar;pif
+
+# Deny ident
+&dollar;cmd 00315 deny tcp from any to any 113 in via &dollar;pif
+
+# Deny all Netbios service. 137=name, 138=datagram, 139=session
+# Netbios is MS/Windows sharing services.
+# Block MS/Windows hosts2 name server requests 81
+&dollar;cmd 00320 deny tcp from any to any 137 in via &dollar;pif
+&dollar;cmd 00321 deny tcp from any to any 138 in via &dollar;pif
+&dollar;cmd 00322 deny tcp from any to any 139 in via &dollar;pif
+&dollar;cmd 00323 deny tcp from any to any 81 in via &dollar;pif
+
+# Deny any late arriving packets
+&dollar;cmd 00330 deny all from any to any frag in via &dollar;pif
+
+# Deny ACK packets that did not match the dynamic rule table
+&dollar;cmd 00332 deny tcp from any to any established in via &dollar;pif
+
+# Allow traffic in from ISP's DHCP server. This rule must contain
+# the IP address of your ISP.s DHCP server as it.s the only
+# authorized source to send this packet type.
+# Only necessary for cable or DSL configurations.
+# This rule is not needed for .user ppp. type connection to
+# the public Internet. This is the same IP address you captured
+# and used in the outbound section.
+#&dollar;cmd 00360 allow udp from any to x.x.x.x 67 in via &dollar;pif keep-state
+
+# Allow in standard www function because I have apache server
+&dollar;cmd 00400 allow tcp from any to me 80 in via &dollar;pif setup limit src-addr 2
+
+# Allow in secure FTP, Telnet, and SCP from public Internet
+&dollar;cmd 00410 allow tcp from any to me 22 in via &dollar;pif setup limit src-addr 2
+
+# Allow in non-secure Telnet session from public Internet
+# labeled non-secure because ID &amp; PW are passed over public
+# Internet as clear text.
+# Delete this sample group if you do not have telnet server enabled.
+&dollar;cmd 00420 allow tcp from any to me 23 in via &dollar;pif setup limit src-addr 2
+
+# Reject &amp; Log all incoming connections from the outside
+&dollar;cmd 00499 deny log all from any to any in via &dollar;pif
+
+# Everything else is denied by default
+# deny and log all packets that fell through to see what they are
+&dollar;cmd 00999 deny log all from any to any
+################ End of IPFW rules file ###############################</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>An Example <acronym>NAT</acronym> and Stateful
+	  Ruleset</title>
+
+	<indexterm>
+	  <primary>NAT</primary>
+
+	  <secondary>and IPFW</secondary>
+	</indexterm>
+
+	<para>There are some additional configuration statements that
+	  need to be enabled to activate the <acronym>NAT</acronym>
+	  function of IPFW.  The kernel source needs 'option divert'
+	  statement added to the other IPFIREWALL statements compiled
+	  into a custom kernel.</para>
+
+	<para>In addition to the normal IPFW options in
+	  <filename>/etc/rc.conf</filename>, the following are
+	  needed.</para>
+
+	<programlisting>natd_enable="YES"                   # Enable <acronym>NAT</acronym>D function
+natd_interface="rl0"                # interface name of public Internet NIC
+natd_flags="-dynamic -m"            # -m = preserve port numbers if possible</programlisting>
+
+	<para>Utilizing stateful rules with divert natd rule (Network
+	  Address Translation) greatly complicates the rule set coding
+	  logic.  The positioning of the check-state, and 'divert natd'
+	  rules in the rule set becomes very critical.  This is no
+	  longer a simple fall-through logic flow.  A new action type
+	  is used, called 'skipto'.  To use the skipto command it is
+	  mandatory that you number each rule so you know exactly
+	  where the skipto rule number is you are really jumping
+	  to.</para>
+
+	<para>The following is an uncommented example of one coding
+	  method, selected here to explain the sequence of the packet
+	  flow through the rule sets.</para>
+
+	<para>The processing flow starts with the first rule from the
+	  top of the rule file and progress one rule at a time deeper
+	  into the file until the end is reach or the packet being
+	  tested to the selection criteria matches and the packet is
+	  released out of the firewall.  It is important to take notice
+	  of the location of rule numbers 100 101, 450, 500, and 510.
+	  These rules control the translation of the outbound and
+	  inbound packets so their entries in the keep-state dynamic
+	  table always register the private LAN IP address.  Next
+	  notice that all the allow and deny rules specified the
+	  direction the packet is going (IE outbound or inbound) and
+	  the interface.  Also notice that all the start outbound
+	  session requests all skipto rule 500 for the network address
+	  translation.</para>
+
+	<para>Lets say a LAN user uses their web browser to get a web
+	  page.  Web pages use port 80 to communicate over.  So the
+	  packet enters the firewall, It does not match 100 because it
+	  is headed out not in.  It passes rule 101 because this is the
+	  first packet so it has not been posted to the keep-state
+	  dynamic table yet.  The packet finally comes to rule 125 a
+	  matches.  It is outbound through the NIC facing the public
+	  Internet.  The packet still has it's source IP address as a
+	  private LAN IP address.  On the match to this rule, two
+	  actions take place.  The keep-state option will post this
+	  rule into the keep-state dynamic rules table and the
+	  specified action is executed.  The action is part of the info
+	  posted to the dynamic table.  In this case it is "skipto rule
+	  500".  Rule 500 <acronym>NAT</acronym>s the packet IP address
+	  and out it goes.  Remember this, this is very important.
+	  This packet makes its way to the destination and returns and
+	  enters the top of the rule set.  This time it does match rule
+	  100 and has it destination IP address mapped back to its
+	  corresponding LAN IP address.  It then is processed by the
+	  check-state rule, it's found in the table as an existing
+	  session conversation and released to the LAN.  It goes to the
+	  LAN PC that sent it and a new packet is sent requesting
+	  another segment of the data from the remote server.  This
+	  time it gets checked by the check-state rule and its outbound
+	  entry is found,  the associated action, 'skipto 500', is
+	  executed.  The packet jumps to rule 500 gets
+	  <acronym>NAT</acronym>ed and released on it's way out.</para>
+
+	<para>On the inbound side, everything coming in that is part
+	  of an existing session conversation is being automatically
+	  handled by the check-state rule and the properly placed
+	  divert natd rules.  All we have to address is denying all the
+	  bad packets and only allowing in the authorized services.
+	  Lets say there is a apache server running on the firewall box
+	  and we want people on the public Internet to be able to
+	  access the local web site.  The new inbound start request
+	  packet matches rule 100 and its IP address is mapped to LAN
+	  IP for the firewall box.  The packet is them matched against
+	  all the nasty things we want to check for and finally matches
+	  against rule 425.  On a match two things occur.  The packet
+	  rule is posted to the keep-state dynamic table but this time
+	  any new session requests originating from that source IP
+	  address is limited to 2.  This defends against DoS attacks of
+	  service running on the specified port number.  The action is
+	  allow so the packet is released to the LAN.  On return the
+	  check-state rule recognizes the packet as belonging to an
+	  existing session conversation sends it to rule 500 for
+	  <acronym>NAT</acronym>ing and released to outbound
+	  interface.</para>
+
+	<para>Example Ruleset #1:</para>
+
+	<programlisting>#!/bin/sh
+cmd="ipfw -q add"
+skip="skipto 500"
+pif=rl0
+ks="keep-state"
+good_tcpo="22,25,37,43,53,80,443,110,119"
+
+ipfw -q -f flush
+
+&dollar;cmd 002 allow all from any to any via xl0  # exclude LAN traffic
+&dollar;cmd 003 allow all from any to any via lo0  # exclude loopback traffic
+
+&dollar;cmd 100 divert natd ip from any to any in via &dollar;pif
+&dollar;cmd 101 check-state
+
+# Authorized outbound packets
+&dollar;cmd 120 &dollar;skip udp from any to xx.168.240.2 53 out via &dollar;pif &dollar;ks
+&dollar;cmd 121 &dollar;skip udp from any to xx.168.240.5 53 out via &dollar;pif &dollar;ks
+&dollar;cmd 125 &dollar;skip tcp from any to any &dollar;good_tcpo out via &dollar;pif setup &dollar;ks
+&dollar;cmd 130 &dollar;skip icmp from any to any out via &dollar;pif &dollar;ks
+&dollar;cmd 135 &dollar;skip udp from any to any 123 out via &dollar;pif &dollar;ks
+
+
+# Deny all inbound traffic from non-routable reserved address spaces
+&dollar;cmd 300 deny all from 192.168.0.0/16  to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 301 deny all from 172.16.0.0/12   to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 302 deny all from 10.0.0.0/8      to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 303 deny all from 127.0.0.0/8     to any in via &dollar;pif  #loopback
+&dollar;cmd 304 deny all from 0.0.0.0/8       to any in via &dollar;pif  #loopback
+&dollar;cmd 305 deny all from 169.254.0.0/16  to any in via &dollar;pif  #DHCP auto-config
+&dollar;cmd 306 deny all from 192.0.2.0/24    to any in via &dollar;pif  #reserved for docs
+&dollar;cmd 307 deny all from 204.152.64.0/23 to any in via &dollar;pif  #Sun cluster
+&dollar;cmd 308 deny all from 224.0.0.0/3     to any in via &dollar;pif  #Class D &amp; E multicast
+
+# Authorized inbound packets
+&dollar;cmd 400 allow udp from xx.70.207.54 to any 68 in &dollar;ks
+&dollar;cmd 420 allow tcp from any to me 80 in via &dollar;pif setup limit src-addr 1
+
+
+&dollar;cmd 450 deny log ip from any to any
+
+# This is skipto location for outbound stateful rules
+&dollar;cmd 500 divert natd ip from any to any out via &dollar;pif
+&dollar;cmd 510 allow ip from any to any
+
+######################## end of rules  ##################</programlisting>
+
+	<para>The following is pretty much the same as above, but uses
+	  a self documenting coding style full of description comments
+	  to help the inexperienced IPFW rule writer to better
+	  understand what the rules are doing.</para>
+
+	<para>Example Ruleset #2:</para>
+
+	<programlisting>#!/bin/sh
+################ Start of IPFW rules file ###############################
+# Flush out the list before we begin.
+ipfw -q -f flush
+
+# Set rules command prefix
+cmd="ipfw -q add"
+skip="skipto 800"
+pif="rl0"     # public interface name of NIC
+              # facing the public Internet
+
+#################################################################
+# No restrictions on Inside LAN Interface for private network
+# Change xl0 to your LAN NIC interface name
+#################################################################
+&dollar;cmd 005 allow all from any to any via xl0
+
+#################################################################
+# No restrictions on Loopback Interface
+#################################################################
+&dollar;cmd 010 allow all from any to any via lo0
+
+#################################################################
+# check if packet is inbound and nat address if it is
+#################################################################
+&dollar;cmd 014 divert natd ip from any to any in via &dollar;pif
+
+#################################################################
+# Allow the packet through if it has previous been added to the
+# the "dynamic" rules table by a allow keep-state statement.
+#################################################################
+&dollar;cmd 015 check-state
+
+#################################################################
+# Interface facing Public Internet (Outbound Section)
+# Interrogate session start requests originating from behind the
+# firewall on the private network or from this gateway server
+# destine for the public Internet.
+#################################################################
+
+# Allow out access to my ISP's Domain name server.
+# x.x.x.x must be the IP address of your ISP's DNS
+# Dup these lines if your ISP has more than one DNS server
+# Get the IP addresses from /etc/resolv.conf file
+&dollar;cmd 020 &dollar;skip tcp from any to x.x.x.x 53 out via &dollar;pif setup keep-state
+
+
+# Allow out access to my ISP's DHCP server for cable/DSL configurations.
+&dollar;cmd 030 &dollar;skip udp from any to x.x.x.x 67 out via &dollar;pif keep-state
+
+# Allow out non-secure standard www function
+&dollar;cmd 040 &dollar;skip tcp from any to any 80 out via &dollar;pif setup keep-state
+
+# Allow out secure www function https over TLS SSL
+&dollar;cmd 050 &dollar;skip tcp from any to any 443 out via &dollar;pif setup keep-state
+
+# Allow out send &amp; get email function
+&dollar;cmd 060 &dollar;skip tcp from any to any 25 out via &dollar;pif setup keep-state
+&dollar;cmd 061 &dollar;skip tcp from any to any 110 out via &dollar;pif setup keep-state
+
+# Allow out FreeBSD (make install &amp; CVSUP) functions
+# Basically give user root "GOD" privileges.
+&dollar;cmd 070 &dollar;skip tcp from me to any out via &dollar;pif setup keep-state uid root
+
+# Allow out ping
+&dollar;cmd 080 &dollar;skip icmp from any to any out via &dollar;pif keep-state
+
+# Allow out Time
+&dollar;cmd 090 &dollar;skip tcp from any to any 37 out via &dollar;pif setup keep-state
+
+# Allow out nntp news (i.e. news groups)
+&dollar;cmd 100 &dollar;skip tcp from any to any 119 out via &dollar;pif setup keep-state
+
+# Allow out secure FTP, Telnet, and SCP
+# This function is using SSH (secure shell)
+&dollar;cmd 110 &dollar;skip tcp from any to any 22 out via &dollar;pif setup keep-state
+
+# Allow out whois
+&dollar;cmd 120 &dollar;skip tcp from any to any 43 out via &dollar;pif setup keep-state
+
+# Allow ntp time server
+&dollar;cmd 130 &dollar;skip udp from any to any 123 out via &dollar;pif keep-state
+
+#################################################################
+# Interface facing Public Internet (Inbound Section)
+# Interrogate packets originating from the public Internet
+# destine for this gateway server or the private network.
+#################################################################
+
+# Deny all inbound traffic from non-routable reserved address spaces
+&dollar;cmd 300 deny all from 192.168.0.0/16  to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 301 deny all from 172.16.0.0/12   to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 302 deny all from 10.0.0.0/8      to any in via &dollar;pif  #RFC 1918 private IP
+&dollar;cmd 303 deny all from 127.0.0.0/8     to any in via &dollar;pif  #loopback
+&dollar;cmd 304 deny all from 0.0.0.0/8       to any in via &dollar;pif  #loopback
+&dollar;cmd 305 deny all from 169.254.0.0/16  to any in via &dollar;pif  #DHCP auto-config
+&dollar;cmd 306 deny all from 192.0.2.0/24    to any in via &dollar;pif  #reserved for docs
+&dollar;cmd 307 deny all from 204.152.64.0/23 to any in via &dollar;pif  #Sun cluster
+&dollar;cmd 308 deny all from 224.0.0.0/3     to any in via &dollar;pif  #Class D &amp; E multicast
+
+# Deny ident
+&dollar;cmd 315 deny tcp from any to any 113 in via &dollar;pif
+
+# Deny all Netbios service. 137=name, 138=datagram, 139=session
+# Netbios is MS/Windows sharing services.
+# Block MS/Windows hosts2 name server requests 81
+&dollar;cmd 320 deny tcp from any to any 137 in via &dollar;pif
+&dollar;cmd 321 deny tcp from any to any 138 in via &dollar;pif
+&dollar;cmd 322 deny tcp from any to any 139 in via &dollar;pif
+&dollar;cmd 323 deny tcp from any to any 81  in via &dollar;pif
+
+# Deny any late arriving packets
+&dollar;cmd 330 deny all from any to any frag in via &dollar;pif
+
+# Deny ACK packets that did not match the dynamic rule table
+&dollar;cmd 332 deny tcp from any to any established in via &dollar;pif
+
+# Allow traffic in from ISP's DHCP server. This rule must contain
+# the IP address of your ISP's DHCP server as it's the only
+# authorized source to send this packet type.
+# Only necessary for cable or DSL configurations.
+# This rule is not needed for 'user ppp' type connection to
+# the public Internet. This is the same IP address you captured
+# and used in the outbound section.
+&dollar;cmd 360 allow udp from x.x.x.x to any 68 in via &dollar;pif keep-state
+
+# Allow in standard www function because I have Apache server
+&dollar;cmd 370 allow tcp from any to me 80 in via &dollar;pif setup limit src-addr 2
+
+# Allow in secure FTP, Telnet, and SCP from public Internet
+&dollar;cmd 380 allow tcp from any to me 22 in via &dollar;pif setup limit src-addr 2
+
+# Allow in non-secure Telnet session from public Internet
+# labeled non-secure because ID &amp; PW are passed over public
+# Internet as clear text.
+# Delete this sample group if you do not have telnet server enabled.
+&dollar;cmd 390 allow tcp from any to me 23 in via &dollar;pif setup limit src-addr 2
+
+# Reject &amp; Log all unauthorized incoming connections from the public Internet
+&dollar;cmd 400 deny log all from any to any in via &dollar;pif
+
+# Reject &amp; Log all unauthorized out going connections to the public Internet
+&dollar;cmd 450 deny log all from any to any out via &dollar;pif
+
+# This is skipto location for outbound stateful rules
+&dollar;cmd 800 divert natd ip from any to any out via &dollar;pif
+&dollar;cmd 801 allow ip from any to any
+
+# Everything else is denied by default
+# deny and log all packets that fell through to see what they are
+&dollar;cmd 999 deny log all from any to any
+################ End of IPFW rules file ###############################</programlisting>
+      </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/pl_PL.ISO8859-2/books/handbook/geom/Makefile b/pl_PL.ISO8859-2/books/handbook/geom/Makefile
new file mode 100644
index 0000000000..59e5759cdc
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/geom/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	geom/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/geom/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/geom/chapter.sgml
new file mode 100644
index 0000000000..ca84a765f3
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/geom/chapter.sgml
@@ -0,0 +1,466 @@
+<!--
+     The FreeBSD Documentation Project
+     $FreeBSD$
+
+-->
+
+<chapter id="GEOM">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Written by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>GEOM: Modular Disk Transformation Framework</title>
+
+  <sect1 id="GEOM-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>GEOM Disk Framework</primary>
+      <see>GEOM</see>
+    </indexterm>
+
+    <para>This chapter covers the use of disks under the GEOM
+      framework in &os;.  This includes the major <acronym
+      role="Redundant Array of Inexpensive Disks">RAID</acronym>
+      control utilities which use the framework for configuration.
+      This chapter will not go into in depth discussion on how GEOM
+      handles or controls I/O, the underlying subsystem, or code.
+      This information is provided through the &man.geom.4; manual
+      page and its various SEE ALSO references.  This chapter is also
+      not a definitive guide to <acronym>RAID</acronym>
+      configurations.  Only GEOM-supported <acronym>RAID</acronym>
+      classifications will be discussed.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>What type of <acronym>RAID</acronym> support is available
+	  through GEOM.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use the base utilities to configure, maintain,
+	  and manipulate the various <acronym>RAID</acronym>
+	  levels.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to mirror, stripe, encrypt, and remotely connect disk
+	  devices through GEOM.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to troubleshoot disks attached to the GEOM
+	  framework.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand how &os; treats disk devices
+	  (<xref linkend="disks">).</para>
+      <listitem>
+	<para>Know how to configure and install a new &os; kernel
+	  (<xref linkend="kernelconfig">).</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="GEOM-intro">
+    <title>GEOM Introduction</title>
+
+    <para>GEOM permits access and control to classes &mdash; Master Boot
+      Records, <acronym>BSD</acronym> labels, etc &mdash; through the
+      use of providers, or the special files in
+      <filename role="directory">/dev</filename>.  Supporting various
+      software <acronym>RAID</acronym> configurations, GEOM will
+      transparently provide access to the operating system and
+      operating system utilities.</para>
+  </sect1>
+
+  <sect1 id="GEOM-striping">
+  <sect1info>
+    <authorgroup>
+      <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Written by </contrib>
+      </author>
+      <author>
+	<firstname>Murray</firstname>
+	<surname>Stokely</surname>
+      </author>
+    </authorgroup>
+  </sect1info>
+
+    <title>RAID0 - Striping</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Striping</primary>
+    </indexterm>
+
+    <para>Striping is a method used to combine several disk drives into
+      a single volume.  In many cases, this is done through the use of
+      hardware controllers.  The GEOM disk subsystem provides
+      software support for <acronym>RAID</acronym>0, also known as
+      disk striping.</para>
+
+    <para>In a <acronym>RAID</acronym>0 system, data are split up in
+      blocks that get written across all the drives in the array.
+      Instead of having to wait on the system to write 256k to one
+      disk, a <acronym>RAID</acronym>0 system can simultaneously write
+      64k to each of four different disks, offering superior I/O
+      performance.  This performance can be enhanced further by using
+      multiple disk controllers.</para>
+
+    <para>Each disk in a <acronym>RAID</acronym>0 stripe must be of
+      the same size, since I/O requests are interleaved to read or
+      write to multiple disks in parallel.</para>
+
+      <mediaobject>
+        <imageobject>
+          <imagedata fileref="geom/striping" align="center">
+        </imageobject>
+
+        <textobject>
+          <phrase>Disk Striping Illustration</phrase>
+        </textobject>
+      </mediaobject>
+
+    <procedure>
+      <title>Creating a stripe of unformatted ATA disks</title>
+
+      <step><para>Load the <filename>geom_stripe</filename>
+        module:</para>
+
+    <screen>&prompt.root; <userinput>kldload geom_stripe.ko</userinput></screen>
+	</step>
+
+      <step><para>Ensure that a suitable mount point exists.  If this
+        volume will become a root partition, then temporarily use
+        another mount point such as <filename
+        role="directory">/mnt</filename>:</para>
+
+        <screen>&prompt.root; <userinput>mkdir /mnt</userinput></screen>
+      </step>
+
+      <step><para>Determine the device names for the disks which will
+        be striped, and create the new stripe device.  For example,
+        the following command could be used to stripe two unused,
+        unpartitioned <acronym>ATA</acronym> disks:
+        <filename>/dev/ad2</filename> and
+        <filename>/dev/ad3</filename>.</para>
+
+        <screen>&prompt.root; <userinput>gstripe label -v st0 /dev/ad2 /dev/ad3</userinput></screen>
+
+<!-- 
+    <para>A message should be returned explaining that meta data has
+      been stored on the devices.
+XXX: What message?  Put it inside the screen output above.
+-->
+      </step>
+
+      <step><para>A partition table must be created on the new volume
+        with the following command:</para>
+
+        <screen>&prompt.root; <userinput>bsdlabel -wB /dev/stripe/st0</userinput></screen>
+
+      </step>
+
+      <step><para>This process should have created two other devices
+        in the <filename role="directory">/dev/stripe</filename>
+        directory in addition to the <devicename>st0</devicename> device.
+        Those include <devicename>st0a</devicename> and
+        <devicename>st0c</devicename>.  A file system must now be created
+        on the <devicename>st0a</devicename> device using the following
+        <command>newfs</command> command:</para>
+
+      <screen>&prompt.root; <userinput>newfs -U /dev/stripe/st0a</userinput></screen>
+
+      <para>Many numbers will glide across the screen, and after a few
+        seconds, the process will be complete.  The volume has been
+        created and is ready to be mounted.</para>
+    </step>
+  </procedure>
+
+  <para>The following command can be used to manually mount a newly
+    created disk stripe:</para>
+
+  <screen>&prompt.root; <userinput>mount /dev/stripe/st0a /mnt</userinput></screen>
+
+  <para>To mount this striped file system automatically during the boot
+    process, place the volume information in
+    <filename>/etc/fstab</filename> file:</para>
+
+  <screen>&prompt.root; <userinput>echo "/dev/stripe/st0a /mnt ufs rw 2 2" \</userinput>
+    <userinput>&gt;&gt; /etc/fstab</userinput></screen>
+
+  <para>The <filename>geom_stripe</filename> module must also be automatically loaded during
+    system initialization, by adding a line to
+    <filename>/boot/loader.conf</filename>:</para>
+
+  <screen>&prompt.root; <userinput>echo 'geom_stripe_load="YES"' &gt;&gt; /boot/loader.conf</userinput></screen>
+
+  </sect1>
+
+  <sect1 id="GEOM-mirror">
+    <title>RAID1 - Mirroring</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Disk Mirroring</primary>
+    </indexterm>
+
+    <para>Mirroring is a technology used by many corporations and home
+      users to back up data without interruption.  When a mirror exists,
+      it simply means that diskB replicates diskA.  Or, perhaps diskC+D
+      replicates diskA+B.  Regardless of the disk configuration, the
+      important aspect is that information on one disk or partition is
+      being replicated.  Later, that information could be more easily
+      restored, backed up without causing service or access
+      interruption, and even be physically stored in a data
+      safe.</para>
+
+    <para>To begin, ensure the system has two disk drives of equal size,
+      this exercise assumes they are direct access (&man.da.4;)
+      <acronym>SCSI</acronym> disks.</para>
+
+    <para>Begin by installing &os; on the first disk with only two
+      partitions.  One should be a swap partition, double the
+      <acronym>RAM</acronym> size and all remaining space devoted to
+      the root (<filename role="directory">/</filename>) file system.
+      It is possible to have separate partitions for other mount points;
+      however, this will increase the difficulty level ten fold due to
+      manual alteration of the &man.bsdlabel.8; and &man.fdisk.8;
+      settings.</para>
+
+    <para>Reboot and wait for the system to fully initialize.  Once this
+      process has completed, log in as the <username>root</username>
+      user.</para>
+
+    <para>Create the <filename>/dev/mirror/gm</filename> device and link
+      it with <filename>/dev/da1</filename>:</para>
+
+    <screen>&prompt.root; <userinput>gmirror label -vnb round-robin gm0 /dev/da1</userinput></screen>
+
+    <para>The system should respond with:</para>
+    <screen>
+Metadata value stored on /dev/da1.
+Done.</screen>
+
+    <para>Initialize GEOM, this will load the
+      <filename>/boot/kernel/geom_mirror.ko</filename> kernel
+      module:</para>
+
+    <screen>&prompt.root; <userinput>gmirror load</userinput></screen>
+
+    <note>
+      <para>This command should have created the
+	<devicename>gm0</devicename>, device node under the
+	<filename role="directory">/dev/mirror</filename>
+	directory.</para>
+    </note>
+
+    <para>Install a generic <command>fdisk</command> label and boot code
+      to newly created <devicename>gm0</devicename> device:</para>
+
+    <screen>&prompt.root; <userinput>fdisk -vBI /dev/mirror/gm0</userinput></screen>
+
+    <para>Now install generic <command>bsdlabel</command>
+      information:</para>
+
+    <screen>&prompt.root; <userinput>bsdlabel -wB /dev/mirror/gm0s1</userinput></screen>
+
+    <note>
+      <para>If multiple slices and partitions exist, the flags for the
+	previous two commands will require alteration.  They must match
+	the slice and partition size of the other disk.</para>
+    </note>
+
+    <para>Use the &man.newfs.8; utility to create a default file
+      system on the <devicename>gm0s1a</devicename> device node:</para>
+
+    <screen>&prompt.root; <userinput>newfs -U /dev/mirror/gm0s1a</userinput></screen>
+
+    <para>This should have caused the system to spit out some
+      information and a bunch of numbers.  This is good.  Examine the
+      screen for any error messages and mount the device to the
+      <filename role="directory">/mnt</filename> mount point:</para>
+
+    <screen>&prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput></screen>
+
+    <para>Now move all data from the boot disk over to this new file
+      system.  This example uses the &man.dump.8; and &man.restore.8;
+      commands; however, &man.dd.1; would also work with this
+      scenario.</para>
+
+    <screen>&prompt.root; <userinput>dump -L -0 -f- / |(cd /mnt &amp;&amp; restore -r -v -f-)</userinput></screen>
+
+    <para>This must be done for each file system.  Simply place the
+      appropriate file system in the correct location when running the
+      aforementioned command.</para>
+
+    <para>Now edit the replicated <filename>/mnt/etc/fstab</filename>
+      file and remove or comment out the swap file
+      <footnote>
+	<para>It should be noted that commenting out the swap file entry
+	in <filename>fstab</filename> will most likely require you to
+	re-establish a different way of enabling swap space.  Please
+	refer to <xref linkend="adding-swap-space"> for more
+	information.</para>
+      </footnote>.  Change the other file system information to use the
+      new disk.  See the following example:</para>
+
+    <programlisting># Device                Mountpoint      FStype  Options         Dump    Pass#
+#/dev/da0s2b             none            swap    sw              0       0
+/dev/mirror/gm0s1a       /               ufs     rw              1       1</programlisting>
+
+    <para>Now create a <filename>boot.conf</filename> file on both the
+      current and new root partitions.  This file will
+      <quote>help</quote> the system <acronym>BIOS</acronym>
+      boot the correct drive:</para>
+
+    <screen>&prompt.root; <userinput>echo "1:da(1,a)/boot/loader" &gt; /boot.config</userinput></screen>
+
+    <screen>&prompt.root; <userinput>echo "1:da(1,a)/boot/loader" &gt; /mnt/boot.config</userinput></screen>
+
+    <note>
+      <para>We have placed it on both root partitions to ensure proper
+        boot up.  If for some reason the system cannot read from the
+	new root partition, a failsafe is available.</para>
+    </note>
+
+    <para>Now add the following line to the new
+      <filename>/boot/loader.conf</filename>:</para>
+
+    <screen>&prompt.root; <userinput>echo 'geom_mirror_load="YES"' &gt;&gt; /mnt/boot/loader.conf</userinput></screen>
+
+    <para>This will instruct &man.loader.8; utility to load the
+      <filename>geom_mirror.ko</filename> module during system
+      initialization.</para>
+
+    <para>Reboot the system:</para>
+
+    <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
+
+    <para>If all has gone well, the system should have booted from the
+      <devicename>gm0s1a</devicename> device and a <command>login</command>
+      prompt should be waiting.  If something went wrong, see review
+      the forthcoming troubleshooting section.  Now add the
+      <devicename>da0</devicename> disk to <devicename>gm0</devicename>
+      device:</para>
+
+    <screen>&prompt.root; <userinput>gmirror configure -a gm0</userinput>
+&prompt.root; <userinput>gmirror insert gm0 /dev/da0</userinput></screen>
+
+    <para>The <option>-a</option> flag tells &man.gmirror.8; to use
+      automatic synchronization; i.e., mirror the disk writes
+      automatically.  The manual page explains how to rebuild and
+      replace disks, although it uses <devicename>data</devicename>
+      in place of <devicename>gm0</devicename>.</para>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <sect3>
+	<title>System refuses to boot</title>
+
+	<para>If the system boots up to a prompt similar to:</para>
+
+	<programlisting>ffs_mountroot: can't find rootvp
+Root mount failed: 6
+mountroot></programlisting>
+
+	<para>Reboot the machine using the power or reset button.  At
+	  the boot menu, select option six (6).  This will drop the
+	  system to a &man.loader.8; prompt.  Load the kernel module
+	  manually:</para>
+
+	<screen>OK? <userinput>load geom_mirror.ko</userinput>
+OK? <userinput>boot</userinput></screen>
+
+	<para>If this works then for whatever reason the module was not
+	  being loaded properly.  Place:</para>
+
+	<programlisting>options	GEOM_MIRROR</programlisting>
+
+	<para>in the kernel configuration file, rebuild and reinstall.
+	  That should remedy this issue.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="geom-ggate">
+    <title>GEOM Gate Network Devices</title>
+
+    <para>GEOM supports the remote use of devices, such as disks,
+      CD-ROMs, files, etc. through the use of the gate utilities.
+      This is similar to <acronym>NFS</acronym>.</para>
+
+    <para>To begin, an exports file must be created.  This file
+      specifies who is permitted to access the exported resources and
+      what level of access they are offered.  For example, to export
+      the forth slice on the first <acronym>SCSI</acronym> disk, the
+      following <filename>/etc/gg.exports</filename> is more than
+      adequate:</para>
+
+    <programlisting>192.168.1.0/24 RW /dev/da0s4d</programlisting>
+
+    <para>It will allow all hosts inside the private network access
+      the file system on the <devicename>da0s4d</devicename>
+      partition.</para>
+
+    <para>To export this device, ensure it is not currently mounted,
+      and start the &man.ggated.8; server daemon:</para>
+
+    <screen>&prompt.root; <userinput>ggated</userinput></screen>
+
+    <para>Now to <command>mount</command> the device on the client
+      machine, issue the following commands:</para>
+
+    <screen>&prompt.root; <userinput>ggatec create -o rw 192.168.1.1 /dev/da0s4d</userinput></screen>
+    <screen>ggate0</screen>
+    <screen>&prompt.root; <userinput>mount /dev/ggate0 /mnt</userinput></screen>
+
+    <para>From here on, the device may be accessed through the
+      <filename role="directory">/mnt</filename> mount point.</para>
+
+    <note>
+      <para>It should be pointed out that this will fail if the device
+	is currently mounted on either the server machine or any other
+	machine on the network.</para>
+    </note>
+
+    <para>When the device is no longer needed, it may be safely
+      unmounted with the &man.umount.8; command, similar to any other
+      disk device.</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/pl_PL.ISO8859-2/books/handbook/install/Makefile b/pl_PL.ISO8859-2/books/handbook/install/Makefile
new file mode 100644
index 0000000000..738cdb647d
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	install/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/install/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/install/chapter.sgml
new file mode 100644
index 0000000000..4d3b44d9e0
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/chapter.sgml
@@ -0,0 +1,5393 @@
+<!--
+     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>Instalacja FreeBSD</title>
+
+  <sect1 id="install-synopsis">
+    <title>Strzeszczenie</title>
+
+    <indexterm><primary>installation</primary></indexterm>
+
+    <para>FreeBSD is provided with a text-based, easy to use installation
+      program called <application>sysinstall</application>.  This is the
+      default installation program for FreeBSD, although vendors are free to
+      provide their own installation suite if they wish.  This chapter
+      describes how to use <application>sysinstall</application> to install
+      FreeBSD.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>How to create the FreeBSD installation disks.</para>
+      </listitem>
+      
+      <listitem>
+	<para>How FreeBSD refers to, and subdivides, your hard disks.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to start <application>sysinstall</application>.</para>
+      </listitem>
+
+      <listitem>
+	<para>The questions <application>sysinstall</application> will ask
+	  you, what they mean, and how to answer them.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Read the supported hardware list that shipped with the version
+	  of FreeBSD you are installing, and verify that your hardware is
+	  supported.</para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <para>In general, these installation instructions are written
+        for &i386; (<quote>PC compatible</quote>) architecture
+        computers.  Where applicable, instructions specific to other
+        platforms (for example, Alpha) will be listed.  Although this
+	guide is kept as up to date as possible, you may find minor
+	differences between the installer and what is shown here.  It is
+	suggested that you use this chapter as a general guide rather 
+	than a literal installation manual.</para>
+    </note>
+
+  </sect1>
+
+  <sect1 id="install-pre">
+    <title>Pre-installation Tasks</title>
+
+    <sect2 id="install-inventory">
+      <title>Inventory Your Computer</title>
+
+      <para>Before installing FreeBSD you should attempt to inventory the
+	components in your computer.  The FreeBSD installation routines will
+	show you the components (hard disks, network cards, CDROM drives, and
+	so forth) with their model number and manufacturer.  FreeBSD will also
+	attempt to determine the correct configuration for these devices,
+	which includes information about IRQ and IO port usage.  Due to the
+	vagaries of PC hardware this process is not always completely
+	successful, and you may need to correct FreeBSD's determination of
+	your configuration.</para>
+
+      <para>If you already have another operating system installed, such as
+	&windows; or Linux, it is a good idea to use the facilities provided
+	by those operating systems to see how your hardware is already
+	configured.  If you are not sure what settings an expansion
+	card is using, you may find it printed on the card itself.  Popular IRQ
+	numbers are 3, 5, and 7, and IO port addresses are normally written as
+	hexadecimal numbers, such as 0x330.</para>
+
+      <para>We recommend you print or write down this information before
+	installing FreeBSD.  It may help to use a table, like this:</para>
+
+      <table pgwide="1" frame="none">
+	<title>Sample Device Inventory</title>
+
+	<tgroup cols="4">
+          <colspec colwidth="2*">
+          <colspec colwidth="1*">
+          <colspec colwidth="1*">
+          <colspec colwidth="4*">
+	  <thead>
+	    <row>
+	      <entry>Device Name</entry>
+
+	      <entry>IRQ</entry>
+
+	      <entry>IO port(s)</entry>
+
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>First hard disk</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>40&nbsp;GB, made by Seagate, first IDE master</entry>
+	    </row>
+
+	    <row>
+	      <entry>CDROM</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>First IDE slave</entry>
+	    </row>
+
+	    <row>
+	      <entry>Second hard disk</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>20&nbsp;GB, made by IBM, second IDE master</entry>
+	    </row>
+
+	    <row>
+	      <entry>First IDE controller</entry>
+
+	      <entry>14</entry>
+
+	      <entry>0x1f0</entry>
+
+	      <entry></entry>
+	    </row>
+
+	    <row>
+	      <entry>Network card</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>&intel; 10/100</entry>
+	    </row>
+
+	    <row>
+	      <entry>Modem</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>&tm.3com; 56K faxmodem, on COM1</entry>
+	    </row>
+
+	    <row>
+	      <entry>&hellip;</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+    </sect2>
+
+    <sect2>
+      <title>Backup Your Data</title>
+      
+      <para>If the computer you will be installing FreeBSD on contains
+	valuable data, then ensure you have it backed up, and that you have
+	tested the backups before installing FreeBSD.  The FreeBSD
+	installation routine will prompt you before writing any
+	data to your disk, but once that process has started it cannot be
+	undone.</para>
+    </sect2>
+
+    <sect2 id="install-where">
+      <title>Decide Where to Install FreeBSD</title>
+
+      <para>If you want FreeBSD to use your entire hard disk, then there is nothing
+	more to concern yourself with at this point &mdash; you can skip this
+	section.</para>
+
+      <para>However, if you need FreeBSD to co-exist with other operating
+	systems then you need to have a rough understanding of how data is
+	laid out on the disk, and how this affects you.</para>
+
+      <sect3 id="install-where-i386">
+	<title>Disk Layouts for the &i386;</title>
+
+      <para>A PC disk can be divided into discrete chunks.  These chunks are
+	called <firstterm>partitions</firstterm>.  By design, the PC only
+	supports four partitions per disk.  These partitions are called
+	<firstterm>primary partitions</firstterm>.  To work around this
+	limitation and allow more than four partitions, a new partition type
+	was created, the <firstterm>extended partition</firstterm>.  A disk
+	may contain only one extended partition.  Special partitions, called
+	<firstterm>logical partitions</firstterm>, can be created inside this
+	extended partition.</para>
+
+      <para>Each partition has a <firstterm>partition ID</firstterm>, which is
+	a number used to identify the type of data on the partition.  FreeBSD
+	partitions have the partition ID of <literal>165</literal>.</para>
+
+      <para>In general, each operating system that you use will identify
+	partitions in a particular way.  For example, DOS, and its
+	descendants, like &windows;, assign each primary and logical partition a
+	<firstterm>drive letter</firstterm>, starting with
+	<devicename>C:</devicename>.</para>
+
+      <para>FreeBSD must be installed into a primary partition.  FreeBSD can
+	keep all its data, including any files that you create, on this one
+	partition.  However, if you have multiple disks, then you can create a
+	FreeBSD partition on all, or some, of them.  When you install FreeBSD,
+	you must have one partition available.  This might be a blank
+	partition that you have prepared, or it might be an existing partition
+	that contains data that you no longer care about.</para>
+
+      <para>If you are already using all the partitions on all your disks, then
+	you will have to free one of them for FreeBSD using the tools
+	provided by the other operating systems you use (e.g.,
+	<command>fdisk</command> on DOS or &windows;).</para>
+
+      <para>If you have a spare partition then you can use that.  However, you
+	may need to shrink one or more of your existing partitions
+	first.</para>
+
+      <para>A minimal installation of FreeBSD takes as little as 100&nbsp;MB of disk
+	space.  However, that is a <emphasis>very</emphasis> minimal install,
+	leaving almost no space for your own files.  A more realistic minimum
+	is 250&nbsp;MB without a graphical environment, and 350&nbsp;MB or more if you
+	want a graphical user interface.  If you intend to install a lot of
+	third party software as well, then you will need more space.</para>
+
+      <para>You can use a commercial tool such as <application>&partitionmagic;</application>
+	to resize your partitions to make space for
+	FreeBSD.  The <filename>tools</filename> directory on the CDROM
+	contains two free software tools which can carry out this task, namely
+	<application>FIPS</application> and
+	<application>PResizer</application>.  Documentation for both
+	of these is available in the same directory.
+	<application>FIPS</application>,
+	<application>PResizer</application>, and
+	<application>&partitionmagic;</application> can resize
+	<acronym>FAT16</acronym> and <acronym>FAT32</acronym>
+	partitions &mdash; used in &ms-dos; through &windows; ME.
+	<application>&partitionmagic;</application> is the only one of
+	the above applications that can resize <acronym>NTFS</acronym>
+	partitions.</para>
+
+      <warning>
+	<para>Incorrect use of these tools can delete the data on your disk.
+	  Be sure that you have recent, working backups before using
+	  them.</para>
+      </warning>
+
+      <example>
+	<title>Using an Existing Partition Unchanged</title>
+
+	<para>Suppose that you have a computer with a single 4&nbsp;GB disk that
+	  already has a version of &windows; installed, and you have split the
+	  disk into two drive letters, <devicename>C:</devicename> and
+	  <devicename>D:</devicename>, each of which is 2&nbsp;GB in size.  You have
+	  1&nbsp;GB of data on <devicename>C:</devicename>, and 0.5&nbsp;GB of data on
+	  <devicename>D:</devicename>.</para>
+
+	<para>This means that your disk has two partitions on it, one per
+	  drive letter.  You can copy all your existing data from
+	  <devicename>D:</devicename> to <devicename>C:</devicename>, which
+	  will free up the second partition, ready for FreeBSD.</para>
+      </example>
+
+      <example>
+	<title>Shrinking an Existing Partition</title>
+
+	<para>Suppose that you have a computer with a single 4&nbsp;GB disk that
+	  already has a version of &windows; installed.  When you installed
+	  &windows; you created one large partition, giving you a
+	  <devicename>C:</devicename> drive that is 4&nbsp;GB in size.  You are
+	  currently using 1.5&nbsp;GB of space, and want FreeBSD to have 2&nbsp;GB of
+	  space.</para>
+
+	<para>In order to install FreeBSD you will need to either:</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>Backup your &windows; data, and then reinstall &windows;,
+	      asking for a 2&nbsp;GB partition at install time.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Use one of the tools such as <application>&partitionmagic;</application>,
+	      described above, to shrink your &windows;
+		partition.</para>
+	  </listitem>
+	</orderedlist>
+      </example>
+
+      </sect3>
+
+      <sect3>
+	<title>Disk Layouts for the Alpha</title>
+
+	<indexterm><primary>Alpha</primary></indexterm>
+
+	<para>You will need a dedicated disk for FreeBSD on the
+	  Alpha.  It is not possible to share a disk with another
+	  operating system at this time.  Depending on the specific
+	  Alpha machine you have, this disk can either be a SCSI disk
+	  or an IDE disk, as long as your machine is capable of
+	  booting from it.</para>
+
+	<para>Following the conventions of the Digital / Compaq
+	  manuals all SRM input is shown in uppercase.  SRM is case
+	  insensitive.</para>
+
+	<para>To find the names and types of disks in your machine, use
+	  the <literal>SHOW DEVICE</literal> command from the SRM
+	  console prompt:</para>
+
+	<screen>&gt;&gt;&gt;<userinput>SHOW DEVICE</userinput>
+dka0.0.0.4.0               DKA0           TOSHIBA CD-ROM XM-57  3476
+dkc0.0.0.1009.0            DKC0                       RZ1BB-BS  0658
+dkc100.1.0.1009.0          DKC100             SEAGATE ST34501W  0015
+dva0.0.0.0.1               DVA0
+ewa0.0.0.3.0               EWA0              00-00-F8-75-6D-01
+pkc0.7.0.1009.0            PKC0                  SCSI Bus ID 7  5.27
+pqa0.0.0.4.0               PQA0                       PCI EIDE
+pqb0.0.1.4.0               PQB0                       PCI EIDE</screen>
+
+	<para>This example is from a Digital Personal Workstation
+	  433au and shows three disks attached to the machine.  The
+	  first is a CDROM drive called <devicename>DKA0</devicename> and
+	  the other two are disks and are called
+	  <devicename>DKC0</devicename> and
+	  <devicename>DKC100</devicename> respectively.</para>
+
+	<para>Disks with names of the form <devicename>DKx</devicename>
+	  are SCSI disks.  For example <devicename>DKA100</devicename>
+	  refers to a SCSI disk with SCSI target ID 1 on the first SCSI bus (A), 
+	  whereas <devicename>DKC300</devicename> refers to a SCSI disk
+	  with SCSI ID 3 on the third SCSI bus (C).  Devicename <devicename>
+	  PKx</devicename> refers to the SCSI host bus adapter.  As
+	  seen in the <literal>SHOW DEVICE</literal> output SCSI
+	  CDROM drives are treated as any other SCSI hard disk drive.</para>
+
+	<para>IDE disks have names similar to <devicename>DQx</devicename>,
+	  while <devicename>PQx</devicename> is the associated IDE
+	  controller.</para>
+
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Collect Your Network Configuration Details</title>
+
+      <para>If you intend to connect to a network as part of your FreeBSD
+	installation (for example, if you will be installing from an FTP
+	site or an
+	NFS server), then you need to know your network configuration.  You
+	will be prompted for this information during the installation so that
+	FreeBSD can connect to the network to complete the install.</para>
+
+      <sect3>
+	<title>Connecting to an Ethernet Network or Cable/DSL Modem</title>
+
+	<para>If you connect to an Ethernet network, or you have an Internet
+	  connection using an Ethernet adapter via cable or DSL, then you will need the following
+	  information:</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>IP address</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>IP address of the default gateway</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Hostname</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>DNS server IP addresses</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Subnet Mask</para>
+	  </listitem>
+	</orderedlist>
+
+	<para>If you do not know this information, then ask your system
+	  administrator or service provider.  They may say that this
+	  information is assigned automatically, using
+	  <firstterm>DHCP</firstterm>.  If so, make a note of this.</para>
+      </sect3>
+
+      <sect3>
+	<title>Connecting Using a Modem</title>
+
+	<para>If you dial up to an ISP using a regular modem then you can
+	  still install FreeBSD over the Internet, it will just take a very
+	  long time.</para>
+
+	<para>You will need to know:</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>The phone number to dial for your ISP</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>The COM: port your modem is connected to</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>The username and password for your ISP account</para>
+	  </listitem>
+	</orderedlist>
+      </sect3>
+    </sect2>
+    <sect2>
+      <title>Check for FreeBSD Errata</title>
+      
+      <para>Although the FreeBSD project strives to ensure that each release
+	of FreeBSD is as stable as possible, bugs do occasionally creep into
+	the process.  On very rare occasions those bugs affect the
+	installation process.  As these problems are discovered and fixed, they
+	are noted in the <ulink url="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">FreeBSD Errata</ulink>, which is found on the FreeBSD web site.  You
+	should check the errata before installing to make sure that there are
+	no late-breaking problems which you should be aware of.</para>
+
+      <para>Information about all the releases, including the errata for each
+	release, can be found on the 
+	<ulink
+	url="&url.base;/releases/index.html">release
+	information</ulink> section of the 
+	<ulink
+	  url="&url.base;/index.html">FreeBSD web site</ulink>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Obtain the FreeBSD Installation Files</title>
+
+      <para>The FreeBSD installation process can install FreeBSD from files
+	located in any of the following places:</para>
+
+      <itemizedlist>
+	<title>Local Media</title>
+	
+	<listitem>
+	  <para>A CDROM or DVD</para>
+	</listitem>
+
+	<listitem>
+	  <para>A DOS partition on the same computer</para>
+	</listitem>
+
+	<listitem>
+	  <para>A SCSI or QIC tape</para>
+	</listitem>
+
+	<listitem>
+	  <para>Floppy disks</para>
+	</listitem>
+      </itemizedlist>
+
+      <itemizedlist>
+	<title>Network</title>
+
+	<listitem>
+	  <para>An FTP site, going through a firewall, or using an HTTP proxy,
+	    as necessary</para>
+	</listitem>
+
+	<listitem>
+	  <para>An NFS server</para>
+	</listitem>
+
+	<listitem>
+	  <para>A dedicated parallel or serial connection</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>If you have purchased FreeBSD on CD or DVD then you already have
+	everything you need, and should proceed to the next section 
+	(<xref linkend="install-floppies">).</para>
+
+      <para>If you have not obtained the FreeBSD installation files you should
+	skip ahead to <xref linkend="install-diff-media"> which explains how
+	to prepare to install FreeBSD from any of the above.  After reading
+	that section, you should come back here, and read on to 
+	<xref linkend="install-floppies">.</para>
+    </sect2>
+
+    <sect2 id="install-floppies">
+      <title>Prepare the Boot Media</title>
+      
+      <para>The FreeBSD installation process is started by booting your
+	computer into the FreeBSD installer&mdash;it is not a program you run
+	within another operating system.  Your computer normally boots using
+	the operating system installed on your hard disk, but it can also be
+	configured to use a <quote>bootable</quote> floppy disk.
+	Most modern computers can also
+	boot from a CDROM in the CDROM drive.</para>
+
+      <tip>
+	<para>If you have FreeBSD on CDROM or DVD (either one you purchased
+	  or you prepared yourself), and your computer allows you to boot from
+	  the CDROM or DVD (typically a BIOS option called <quote>Boot
+	    Order</quote> or similar), then you can skip this section.  The
+	  FreeBSD CDROM and DVD images are bootable and can be used to install
+	  FreeBSD without any other special preparation.</para>
+      </tip>
+    
+      <para>To create boot floppy images, follow these steps:</para>
+
+      <procedure>
+	<step>
+	  <title>Acquire the Boot Floppy Images</title>
+	  
+	  <para>The boot disks are available on your installation media
+	    in the <filename>floppies/</filename> directory, and
+	    can also be downloaded from the floppies directory, <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>&lt;arch&gt;</replaceable>/<replaceable>&lt;version&gt;</replaceable>-RELEASE/floppies/</literal>.
+	    Replace <replaceable>&lt;arch&gt;</replaceable> and
+	    <replaceable>&lt;version&gt;</replaceable>
+	    with the architecture and the version number
+	    which you want to install, respectively.
+	    For example, the boot floppy images for
+	    &os;&nbsp;&rel.current;-RELEASE for &i386; are available
+	    from <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/floppies/"></ulink>.</para>
+
+	  <para>The floppy images have a <filename>.flp</filename> extension.
+	    The <filename>floppies/</filename> directory contains a number of
+	    different images, and the ones you will need to use depends on the
+	    version of FreeBSD you are installing, and in some cases, the
+	    hardware you are installing to.
+	    In most cases you will need three
+	    floppies, <filename>boot.flp</filename>,
+	    <filename>kern1.flp</filename>, and
+	    <filename>kern2.flp</filename>.  Check
+	    <filename>README.TXT</filename> in the same directory for the
+	    most up to date information about these floppy images.</para>
+
+	  <note><para>Additional device drivers may
+	    be necessary for 5.X systems older than &os;&nbsp;5.3.
+	    These drivers are provided on the
+	    <filename>drivers.flp</filename> image.</para></note>
+
+	  <important>
+	    <para>Your FTP program must use <emphasis>binary mode</emphasis>
+	      to download these disk images.  Some web browsers have been
+	      known to use <emphasis>text</emphasis> (or
+	      <emphasis>ASCII</emphasis>) mode, which will be apparent if you
+	      cannot boot from the disks.</para>
+	  </important>
+	</step>
+
+	<step>
+	  <title>Prepare the Floppy Disks</title>
+	  
+	  <para>You must prepare one floppy disk per image file you had to
+	    download.  It is imperative that these disks are free from
+	    defects.  The easiest way to test this is to format the disks
+	    for yourself.  Do not trust pre-formatted floppies.  The format
+	    utility in &windows; will not tell about the presence of
+	    bad blocks, it simply marks them as <quote>bad</quote>
+	    and ignores them.  It is advised that you use brand new
+	    floppies if choosing this installation route.</para>
+
+	  <important>
+	    <para>If you try to install FreeBSD and the installation
+	      program crashes, freezes, or otherwise misbehaves, one of
+	      the first things to suspect is the floppies.  Try writing
+	      the floppy image files to new disks and try
+	      again.</para>
+	  </important>
+	</step>
+
+	<step>
+	  <title>Write the Image Files to the Floppy Disks</title>
+
+	  <para>The <filename>.flp</filename> files are
+	    <emphasis>not</emphasis> regular files you copy to the disk.
+	    They are images of the complete contents of the
+	    disk.  This means that you <emphasis>cannot</emphasis> simply
+	    copy files from one disk to another.
+	    Instead, you must use specific tools to write the
+	    images directly to the disk.</para>
+
+	  <indexterm><primary>DOS</primary></indexterm>
+	  <para>If you are creating the floppies on a computer running
+      &ms-dos;/&windows;, then we provide a tool to do
+      this called <command>fdimage</command>.</para>
+
+	  <para>If you are using the floppies from the CDROM, and your
+	    CDROM is the <devicename>E:</devicename> drive, then you would 
+	    run this:</para>
+
+	  <screen><prompt>E:\&gt;</prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen>
+
+	  <para>Repeat this command for each <filename>.flp</filename>
+	    file, replacing the floppy disk each time, being sure to label
+	    the disks with the name of the file that you copied to them.
+	    Adjust the command line as necessary, depending on where you have
+	    placed the <filename>.flp</filename> files.  If you do not have
+	    the CDROM, then <command>fdimage</command> can be downloaded from
+	    the <ulink
+	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename class="directory">tools</filename>
+	    directory</ulink> on the FreeBSD FTP site.</para>
+	  
+	  <para>If you are writing the floppies on a &unix; system (such as
+	    another FreeBSD system) you can use the &man.dd.1; command to
+	    write the image files directly to disk.  On FreeBSD, you would
+	    run:</para>
+	  
+	  <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput></screen>
+
+	  <para>On FreeBSD, <filename>/dev/fd0</filename> refers to the
+	    first floppy disk (the <devicename>A:</devicename> drive).
+	    <filename>/dev/fd1</filename> would be the
+	    <devicename>B:</devicename> drive, and so on.  Other &unix;
+	    variants might have different names for the floppy disk
+	    devices, and you will need to check the documentation for the
+	    system as necessary.</para>
+	</step>
+      </procedure>
+
+      <para>You are now ready to start installing FreeBSD.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-start">
+    <title>Starting the Installation</title>
+
+    <important>
+      <para>By default, the installation will not make any changes to your
+	disk(s) until you see the following message:</para>
+
+      <literallayout class="monospaced">Last Chance: Are you SURE you want continue the installation?
+
+If you're running this on a disk with data you wish to save then WE
+STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding!
+
+We can take no responsibility for lost disk contents!</literallayout>
+
+      <para>The install can be exited at any time prior to the final
+	warning without changing the contents of the hard drive.  If you are
+	concerned that you have configured something incorrectly you can just
+	turn the computer off before this point, and no damage will be
+	done.</para>
+    </important>
+
+    <sect2 id="install-starting">
+      <title>Booting</title>
+
+      <sect3 id="install-starting-i386">
+        <title>Booting for the &i386;</title>
+
+      <procedure>
+	<step>
+	  <para>Start with your computer turned off.</para>
+	</step>
+
+	<step>
+	  <para>Turn on the computer.  As it starts it should display an
+	    option to enter the system set up menu, or BIOS, commonly reached
+	    by keys like <keycap>F2</keycap>, <keycap>F10</keycap>,
+	    <keycap>Del</keycap>, or
+	    <keycombo action="simul">
+	      <keycap>Alt</keycap>
+	      <keycap>S</keycap>
+	    </keycombo>.  Use whichever keystroke is indicated on screen.  In
+	    some cases your computer may display a graphic while it starts.
+	    Typically, pressing <keycap>Esc</keycap> will dismiss the graphic
+	    and allow you to see the necessary messages.</para>
+	</step>
+
+	<step>
+	  <para>Find the setting that controls which devices the system boots
+	    from.  This is usually labeled as the <quote>Boot Order</quote>
+            and commonly shown as a list of devices, such as
+	    <literal>Floppy</literal>, <literal>CDROM</literal>,
+	    <literal>First Hard Disk</literal>, and so on.</para>
+
+	  <para>If you needed to prepare boot floppies, then make sure that the
+	    floppy disk is selected.  If you are booting from the CDROM then
+	    make sure that that is selected instead.  In case of doubt, you
+	    should consult the manual that came with your computer, and/or its
+	    motherboard.</para>
+
+	  <para>Make the change, then save and exit.  The computer should now
+	    restart.</para>
+	</step>
+
+	<step>
+	  <para>If you needed to prepare boot floppies, as described in 
+	    <xref linkend="install-floppies">, then one of them will be the
+	    first boot disc, probably the one containing
+	    <filename>kern.flp</filename>.  Put this disc in your floppy
+	    drive.</para>
+
+	  <para>If you are booting from CDROM, then you will need to turn on
+	    the computer, and insert the CDROM at the first
+	    opportunity.</para>
+
+	  <para>If your computer starts up as normal and loads your existing
+	    operating system, then either:</para>
+
+	  <orderedlist>
+	    <listitem>
+	      <para>The disks were not inserted early enough in the boot
+		process.  Leave them in, and try restarting your
+		computer.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>The BIOS changes earlier did not work correctly.  You
+		should redo that step until you get the right option.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>Your particular BIOS does not support booting from
+		the desired media.</para>
+	    </listitem>
+	</orderedlist>
+	</step>
+    
+	<step>
+	  <para>FreeBSD will start to boot.  If you are booting from CDROM you
+	    will see a display similar to this (version information omitted):</para>
+	  
+	  <screen>Verifying DMI Pool Data ........
+Boot from ATAPI CD-ROM :
+ 1. FD 2.88MB  System Type-(00)
+Uncompressing ... done
+
+BTX loader 1.00 BTX version is 1.01
+Console: internal video/keyboard
+BIOS drive A: is disk0
+BIOS drive B: is disk1
+BIOS drive C: is disk2
+BIOS drive D: is disk3
+BIOS 639kB/261120kB available memory
+
+FreeBSD/i386 bootstrap loader, Revision 0.8
+
+/kernel text=0x277391 data=0x3268c+0x332a8 |
+
+|
+Hit [Enter] to boot immediately, or any other key for command prompt.
+Booting [kernel] in 9 seconds... _</screen>
+	
+	  <para>If you are booting from floppy disc, you will see a display
+	    similar to this (version information omitted):</para>
+	
+	  <screen>Verifying DMI Pool Data ........ 
+
+BTX loader 1.00  BTX version is 1.01 
+Console: internal video/keyboard 
+BIOS drive A: is disk0 
+BIOS drive C: is disk1 
+BIOS 639kB/261120kB available memory 
+
+FreeBSD/i386 bootstrap loader, Revision 0.8 
+
+/kernel text=0x277391 data=0x3268c+0x332a8 |
+
+Please insert MFS root floppy and press enter:</screen>
+
+	  <para>Follow these instructions by removing the
+	    <filename>kern.flp</filename> disc, insert the
+	    <filename>mfsroot.flp</filename> disc, and press
+	    <keycap>Enter</keycap>.  &os;&nbsp;5.3
+	    and above provide other floppy disks set, as described
+	    in <link linkend="install-floppies">previous
+	    section</link>.  Boot from first floppy;
+	    when prompted, insert the other disks as required.</para>
+	</step>
+
+	<step>
+	  <para>Whether you booted from floppy or CDROM, the
+	    boot process will then get to this point:</para>
+
+	  <screen>Hit [Enter] to boot immediately, or any other key for command prompt. 
+Booting [kernel] in 9 seconds... _</screen>
+
+	  <para>Either wait ten seconds, or press <keycap>Enter</keycap></para>
+	</step>
+      </procedure>
+
+      </sect3>
+      <sect3>
+        <title>Booting for the Alpha</title>
+
+	<indexterm><primary>Alpha</primary></indexterm>
+
+      <procedure>
+	<step>
+	  <para>Start with your computer turned off.</para>
+	</step>
+
+	<step>
+	  <para>Turn on the computer and wait for a boot monitor
+	    prompt.</para>
+        </step>
+
+	<step>
+	  <para>If you needed to prepare boot floppies, as described in 
+	    <xref linkend="install-floppies"> then one of them will be the
+	    first boot disc, probably the one containing
+	    <filename>kern.flp</filename>.  Put this disc in your floppy
+	    drive and type the following command to boot the disk
+	    (substituting the name of your floppy drive if
+	    necessary):</para>
+
+	  <screen>&gt;&gt;&gt;<userinput>BOOT DVA0 -FLAGS '' -FILE ''</userinput></screen>
+
+	  <para>If you are booting from CDROM, insert the CDROM into
+	    the drive and type the following command to start the
+	    installation (substituting the name of the appropriate
+	    CDROM drive if necessary):</para>
+
+          <screen>&gt;&gt;&gt;<userinput>BOOT DKA0 -FLAGS '' -FILE ''</userinput></screen>
+	</step>
+    
+	<step>
+	  <para>FreeBSD will start to boot.  If you are booting from a
+	    floppy disc, at some point you will see the message:</para>
+
+	  <screen>Please insert MFS root floppy and press enter:</screen>
+
+	  <para>Follow these instructions by removing the
+	    <filename>kern.flp</filename> disc, insert the
+	    <filename>mfsroot.flp</filename> disc, and press
+	    <keycap>Enter</keycap>.</para>
+	</step>
+
+	<step>
+	  <para>Whether you booted from floppy or CDROM, the
+	    boot process will then get to this point:</para>
+
+	  <screen>Hit [Enter] to boot immediately, or any other key for command prompt. 
+Booting [kernel] in 9 seconds... _</screen>
+
+	  <para>Either wait ten seconds, or press <keycap>Enter</keycap>.  This
+	    will then launch the kernel configuration menu.</para>
+	</step>
+      </procedure>
+
+      </sect3>
+
+    </sect2>
+
+    <sect2 id="view-probe">
+      <title>Reviewing the Device Probe Results</title>
+
+      <para>The last few hundred lines that have been displayed on screen are
+	stored and can be reviewed.</para>
+
+      <para>To review the buffer, press <keycap>Scroll Lock</keycap>.  This
+	turns on scrolling in the display.  You can then use the arrow keys, or
+	<keycap>PageUp</keycap> and <keycap>PageDown</keycap> to view the
+	results.  Press <keycap>Scroll Lock</keycap> again to stop
+	scrolling.</para>
+
+      <para>Do this now, to review the text that scrolled off the screen when
+	the kernel was carrying out the device probes.  You will see text
+	similar to <xref linkend="install-dev-probe">, although the precise
+	text will differ depending on the devices that you have in your
+	computer.</para>
+
+      <figure id="install-dev-probe">
+	<title>Typical Device Probe Results</title>
+
+	<screen>avail memory = 253050880 (247120K bytes) 
+Preloaded elf kernel "kernel" at 0xc0817000.
+Preloaded mfs_root "/mfsroot" at 0xc0817084.
+md0: Preloaded image &lt;/mfsroot&gt; 4423680 bytes at 0xc03ddcd4
+
+md1: Malloc disk
+Using $PIR table, 4 entries at 0xc00fde60
+npx0: &lt;math processor&gt; on motherboard   
+npx0: INT 16 interface   
+pcib0: &lt;Host to PCI bridge&gt; on motherboard
+pci0: &lt;PCI bus&gt; on pcib0
+pcib1:&lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge&gt; at device 1.0 on pci0
+pci1: &lt;PCI bus&gt; on pcib1
+pci1: &lt;Matrox MGA G200 AGP graphics accelerator&gt; at 0.0 irq 11
+isab0: &lt;VIA 82C586 PCI-ISA bridge&gt; at device 7.0 on pci0
+isa0: &lt;iSA bus&gt; on isab0
+atapci0: &lt;VIA 82C586 ATA33 controller&gt; port 0xe000-0xe00f at device 7.1 on pci0
+ata0: at 0x1f0 irq 14 on atapci0
+ata1: at 0x170 irq 15 on atapci0
+uhci0 &lt;VIA 83C572 USB controller&gt; port 0xe400-0xe41f irq 10 at device 7.2 on pci
+0
+usb0: &lt;VIA 83572 USB controller&gt; on uhci0
+usb0: USB revision 1.0
+uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1
+uhub0: 2 ports with 2 removable, self powered
+pci0: &lt;unknown card&gt; (vendor=0x1106, dev=0x3040) at 7.3
+dc0: &lt;ADMtek AN985 10/100BaseTX&gt; port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir
+q 11 at device 8.0 on pci0
+dc0: Ethernet address: 00:04:5a:74:6b:b5
+miibus0: &lt;MII bus&gt; on dc0
+ukphy0: &lt;Generic IEEE 802.3u media interface&gt; on miibus0
+ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto
+ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)&gt; port 0xec00-0xec1f irq 9 at device 10.
+0 on pci0
+ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit)
+isa0: too many dependant configs (8)
+isa0: unexpected small tag 14
+orm0: &lt;Option ROM&gt; at iomem 0xc0000-0xc7fff on isa0
+fdc0: &lt;NEC 72065B or clone&gt; at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0
+fdc0: FIFO enabled, 8 bytes threshold
+fd0: &lt;1440-KB 3.5" drive&gt; on fdc0 drive 0
+atkbdc0: &lt;Keyboard controller (i8042)&gt; at port 0x60,0x64 on isa0
+atkbd0: &lt;AT Keyboard&gt; flags 0x1 irq1 on atkbdc0
+kbd0 at atkbd0
+psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0
+psm0: model Generic PS/@ mouse, device ID 0
+vga0: &lt;Generic ISA VGA&gt; at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
+sc0: &lt;System console&gt; at flags 0x100 on isa0
+sc0: VGA &lt;16 virtual consoles, flags=0x300&gt;
+sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0
+sio0: type 16550A
+sio1 at port 0x2f8-0x2ff irq 3 on isa0
+sio1: type 16550A
+ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0
+pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode
+ppc0: FIFO with 16/16/15 bytes threshold
+plip0: &lt;PLIP network interface&gt; on ppbus0
+ad0: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata0-master UDMA33
+acd0: CD-RW &lt;LITE-ON LTR-1210B&gt; at ata1-slave PIO4
+Mounting root from ufs:/dev/md0c
+/stand/sysinstall running as init on vty0</screen>
+      </figure>
+
+      <para>Check the probe results carefully to make sure that FreeBSD found
+	all the devices you expected.  If a device was not found, then it will
+	not be listed.  If the device's driver required configuring
+	with the IRQ and port address then you should check that you entered
+	them correctly.</para>
+
+      <para>If you need to make changes to the UserConfig device probing,
+	it is easy to exit the <application>sysinstall</application> program
+	and start over again.  It is also a good way to become more familiar
+	with the process.</para>
+
+      <figure id="sysinstall-exit">
+	<title>Select Sysinstall Exit</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/sysinstall-exit" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Use the arrow keys to select 
+	<guimenuitem>Exit Install</guimenuitem> from the Main
+	Install Screen menu.  The following message will display:</para>
+
+
+      <screen>                      User Confirmation Requested 
+         Are you sure you wish to exit? The system will reboot 
+           (be sure to remove any floppies from the drives).
+
+                            [ Yes ]    No</screen>
+
+      <para>The install program will start again if the CDROM is left
+	in the drive and &gui.yes; is selected.</para>
+
+      <para>If you are booting from floppies it will be necessary to remove
+	the <filename>mfsroot.flp</filename> floppy and replace it with
+	<filename>kern.flp</filename> before rebooting.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="using-sysinstall">
+    <title>Introducing Sysinstall</title>
+
+    <para>The <application>sysinstall</application> utility is the installation
+      application provided by the FreeBSD Project.  It is console based and is
+      divided into a number of menus and screens that you can use to
+      configure and control the installation process.</para>
+
+    <para>The <application>sysinstall</application> menu system is controlled
+      by the arrow keys, <keycap>Enter</keycap>, <keycap>Space</keycap>, and
+      other keys.  A detailed description of these keys and what they do is
+      contained in <application>sysinstall</application>'s usage 
+      information.</para>
+
+    <para>To review this information, ensure that the
+      <guimenuitem>Usage</guimenuitem> entry is highlighted and that the
+      <guibutton>[Select]</guibutton> button is selected, as shown in <xref
+      linkend="sysinstall-main3">, then press <keycap>Enter</keycap>.</para>
+
+    <para>The instructions for using the menu system will be displayed.  After
+      reviewing them, press <keycap>Enter</keycap> to return to the Main
+      Menu.</para>
+
+    <figure id="sysinstall-main3">
+      <title>Selecting Usage from Sysinstall Main Menu</title>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="install/main1" format="PNG">
+	</imageobject>
+      </mediaobject>
+    </figure>
+
+    <sect2 id="select-doc">
+      <title>Selecting the Documentation Menu</title>
+
+      <para>From the Main Menu, select <guimenuitem>Doc</guimenuitem> with
+	the arrow keys and
+	press <keycap>Enter</keycap>.</para>
+
+      <figure id="main-doc">
+	<title>Selecting Documentation Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/main-doc" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>This will display the Documentation Menu.</para>
+
+      <figure id="docmenu1">
+	<title>Sysinstall Documentation Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/docmenu1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>It is important to read the documents provided.</para>
+
+      <para>To view a document, select it with the arrow keys and
+	press <keycap>Enter</keycap>.  When finished reading a document,
+	pressing <keycap>Enter</keycap> will return to the Documentation
+	Menu.</para>
+
+      <para>To return to the Main Installation Menu, select
+	<guimenuitem>Exit</guimenuitem> with the 
+	arrow keys and press <keycap>Enter</keycap>.</para>
+    </sect2>
+
+    <sect2 id="keymap">
+      <title>Selecting the Keymap Menu</title>
+
+      <para>To change the keyboard mapping, use the arrow keys to select
+	<guimenuitem>Keymap</guimenuitem> from the menu and press
+	<keycap>Enter</keycap>.  This is only required if you are
+	using a non-standard or non-US keyboard.</para>
+
+      <figure id="sysinstall-keymap">
+	<title>Sysinstall Main Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/main-keymap" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>A different keyboard mapping may be chosen by selecting the
+	menu item using up/down arrow keys and pressing <keycap>Space</keycap>.
+	Pressing <keycap>Space</keycap> again will unselect the item.
+	When finished, choose the &gui.ok; using the arrow keys and press
+	<keycap>Enter</keycap>.</para>
+
+      <para>Only a partial list is shown in this screen representation.
+	Selecting &gui.cancel; by pressing <keycap>Tab</keycap> will use the default
+	keymap and return to the Main Install Menu.</para>
+
+      <figure id="sysinstall-keymap-menu">
+	<title>Sysinstall Keymap Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/keymap" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+    </sect2>
+
+    <sect2 id="viewsetoptions">
+      <title>Installation Options Screen</title>
+
+    <para>Select <guimenuitem>Options</guimenuitem> and press
+	<keycap>Enter</keycap>.</para>
+
+    <figure id="sysinstall-options">
+      <title>Sysinstall Main Menu</title>
+
+      <mediaobject>
+        <imageobject>
+	  <imagedata fileref="install/main-options" format="PNG">
+	</imageobject>
+      </mediaobject>
+    </figure>
+
+      <figure id="options">
+	<title>Sysinstall Options</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/options" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The default values are usually fine for most users and do
+	not need to be changed.  The release name will vary according
+	to the version being installed.</para>
+
+      <para>The description of the selected item will appear at the
+	bottom of the screen highlighted in blue.  Notice that one of the
+	options is <guimenuitem>Use Defaults</guimenuitem> to reset all
+	values to startup defaults.</para>
+
+      <para>Press <keycap>F1</keycap> to read the help screen about the
+	various options.</para>
+
+      <para>Pressing <keycap>Q</keycap> will return to the Main Install
+	menu.</para>
+    </sect2>
+
+    <sect2 id="start-install">
+      <title>Begin a Standard Installation</title>
+
+      <para>The <guimenuitem>Standard</guimenuitem> installation is the
+	option recommended for those new to &unix; or FreeBSD.  Use the arrow
+	keys to select <guimenuitem>Standard</guimenuitem> and
+	then press <keycap>Enter</keycap> to start the installation.</para>
+
+      <figure id="sysinstall-standard">
+	<title>Begin Standard Installation</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/main-std" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-steps">
+    <title>Allocating Disk Space</title>
+
+    <para>Your first task is to allocate disk space for FreeBSD, and label
+      that space so that <application>sysinstall</application> can prepare
+      it.  In order to do this you need to know how FreeBSD expects to find
+      information on the disk.</para>
+
+    <sect2 id="install-drive-bios-numbering">
+      <title>BIOS Drive Numbering</title>
+
+      <para>Before you install and configure FreeBSD on your system, there is an
+	important subject that you should be aware of, especially if you have
+	multiple hard drives.</para>
+
+      <indexterm><primary>DOS</primary></indexterm>
+      <indexterm><primary>Microsoft Windows</primary></indexterm>
+      <para>In a PC running a BIOS-dependent operating system such as
+	&ms-dos; or &microsoft.windows;, the BIOS is able to abstract the
+	normal disk drive order, and
+	the operating system goes along with the change.  This allows the user
+	to boot from a disk drive other than the so-called <quote>primary
+	  master</quote>.  This is especially convenient for some users who have
+	found that the simplest and cheapest way to keep a system backup is to
+	buy an identical second hard drive, and perform routine copies of the
+	first drive to the second drive using 
+	<application><trademark class="registered">Ghost</trademark></application> or <application>XCOPY</application>
+	.  Then, if the
+	first drive fails, or is attacked by a virus, or is scribbled upon by an
+	operating system defect, he can easily recover by instructing the BIOS
+	to logically swap the drives.  It is like switching the cables on the
+	drives, but without having to open the case.</para>
+
+      <indexterm><primary>SCSI</primary></indexterm>
+      <indexterm><primary>BIOS</primary></indexterm>
+      <para>More expensive systems with SCSI controllers often include BIOS
+	extensions which allow the SCSI drives to be re-ordered in a similar
+	fashion for up to seven drives.</para>
+
+      <para>A user who is accustomed to taking advantage of these features may
+	become surprised when the results with FreeBSD are not as expected.
+	FreeBSD does not use the BIOS, and does not know the <quote>logical BIOS
+	  drive mapping</quote>.  This can lead to very perplexing situations,
+	especially when drives are physically identical in geometry, and have
+	also been made as data clones of one another.</para>
+
+      <para>When using FreeBSD, always restore the BIOS to natural drive
+	numbering before installing FreeBSD, and then leave it that way.  If you
+	need to switch drives around, then do so, but do it the hard way, and
+	open the case and move the jumpers and cables.</para>
+
+      <sidebar>
+	<title>An Illustration from the Files of Bill and Fred's Exceptional
+	  Adventures:</title>
+      
+	<para>Bill breaks-down an older Wintel box to make another FreeBSD box
+	  for Fred.  Bill installs a single SCSI drive as SCSI unit zero and
+	  installs FreeBSD on it.</para>
+
+	<para>Fred begins using the system, but after several days notices that
+	  the older SCSI drive is reporting numerous soft errors and reports
+	  this fact to Bill.</para>
+
+	<para>After several more days, Bill decides it is time to address the
+	  situation, so he grabs an identical SCSI drive from the disk drive
+	  <quote>archive</quote> in the back room.  An initial surface scan
+	  indicates that
+	  this drive is functioning well, so Bill installs this drive as SCSI
+	  unit four and makes an image copy from drive zero to drive four.  Now
+	  that the new drive is installed and functioning nicely, Bill decides
+	  that it is a good idea to start using it, so he uses features in the
+	  SCSI BIOS to re-order the disk drives so that the system boots from
+	  SCSI unit four.  FreeBSD boots and runs just fine.</para>
+
+	<para>Fred continues his work for several days, and soon Bill and Fred
+	  decide that it is time for a new adventure &mdash; time to upgrade to a
+	  newer version of FreeBSD.  Bill removes SCSI unit zero because it was
+	  a bit flaky and replaces it with another identical disk drive from
+	  the <quote>archive</quote>.  Bill then installs the new version of
+	  FreeBSD onto the new SCSI unit zero using Fred's magic Internet FTP
+	  floppies.  The installation goes well.</para>
+
+	<para>Fred uses the new version of FreeBSD for a few days, and certifies
+	  that it is good enough for use in the engineering department.  It is
+	  time to copy all of his work from the old version.  So Fred mounts
+	  SCSI unit four (the latest copy of the older FreeBSD version).  Fred
+	  is dismayed to find that none of his precious work is present on SCSI
+	  unit four.</para>
+
+	<para>Where did the data go?</para>
+
+	<para>When Bill made an image copy of the original SCSI unit zero onto
+	  SCSI unit four, unit four became the <quote>new clone</quote>.
+	  When Bill re-ordered the SCSI BIOS so that he could boot from
+	  SCSI unit four, he was only fooling himself.
+	  FreeBSD was still running on SCSI unit zero.
+	  Making this kind of BIOS change will cause some or all of the Boot and
+	  Loader code to be fetched from the selected BIOS drive, but when the
+	  FreeBSD kernel drivers take-over, the BIOS drive numbering will be
+	  ignored, and FreeBSD will transition back to normal drive numbering.
+	  In the illustration at hand, the system continued to operate on the
+	  original SCSI unit zero, and all of Fred's data was there, not on SCSI
+	  unit four.  The fact that the system appeared to be running on SCSI
+	  unit four was simply an artifact of human expectations.</para>
+
+	<para>We are delighted to mention that no data bytes were killed or
+	  harmed in any way by our discovery of this phenomenon.  The older SCSI
+	  unit zero was retrieved from the bone pile, and all of Fred's work was
+	  returned to him, (and now Bill knows that he can count as high as
+	  zero).</para>
+
+	<para>Although SCSI drives were used in this illustration, the concepts
+	  apply equally to IDE drives.</para>
+      </sidebar>
+    </sect2>
+
+    <sect2 id="main-fdisk">
+      <title>Creating Slices Using FDisk</title>
+
+      <note>
+	<para>No changes you make at this point will be written to the disk.
+	  If you think you have made a mistake and want to start again you can
+	  use the menus to exit <application>sysinstall</application> and try
+	  again or press <keycap>U</keycap> to use the <guimenuitem>Undo</guimenuitem> option.
+	  If you get confused and can not see how to exit you can
+	  always turn your computer off.</para>
+      </note>
+
+      <para>After choosing to begin a standard installation in
+	<application>sysinstall</application> you will be shown this
+	message:</para>
+
+      <screen>                                 Message
+ In the next menu, you will need to set up a DOS-style ("fdisk")
+ partitioning scheme for your hard disk. If you simply wish to devote
+ all disk space to FreeBSD (overwriting anything else that might be on
+ the disk(s) selected) then use the (A)ll command to select the default
+ partitioning scheme followed by a (Q)uit. If you wish to allocate only
+ free space to FreeBSD, move to a partition marked "unused" and use the
+ (C)reate command. 
+                                [  OK  ] 
+
+                      [ Press enter or space ]</screen>
+
+      <para>Press <keycap>Enter</keycap> as instructed.  You will then be
+	shown a list of all the hard drives that the kernel found when it
+	carried out the device probes.  
+	<xref linkend="sysinstall-fdisk-drive1"> shows an example from a
+	system with two IDE disks.  They have been called
+	<devicename>ad0</devicename> and <devicename>ad2</devicename>.</para>
+
+      <figure id="sysinstall-fdisk-drive1">
+	<title>Select Drive for FDisk</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/fdisk-drive1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>You might be wondering why <devicename>ad1</devicename> is not
+	listed here.  Why has it been missed?</para>
+
+      <para>Consider what would happen if you had two IDE hard disks, one
+	as the master on the first IDE controller, and one as the master on
+	the second IDE controller.  If FreeBSD numbered these as it found
+	them, as <devicename>ad0</devicename> and
+	<devicename>ad1</devicename> then everything would work.</para>
+
+      <para>But if you then added a third disk, as the slave device on the
+	first IDE controller, it would now be <devicename>ad1</devicename>,
+	and the previous <devicename>ad1</devicename> would become
+	<devicename>ad2</devicename>.  Because device names (such as
+	<devicename>ad1s1a</devicename>) are used to find filesystems, you
+	may suddenly discover that some of your filesystems no longer
+	appear correctly, and you would need to change your FreeBSD
+	configuration.</para>
+      
+      <para>To work around this, the kernel can be configured to name IDE
+	disks based on where they are, and not the order in which they were
+	found.  With this scheme the master disk on the second IDE
+	controller will <emphasis>always</emphasis> be
+	<devicename>ad2</devicename>, even if there are no
+	<devicename>ad0</devicename> or <devicename>ad1</devicename>
+	devices.</para>
+
+      <para>This configuration is the default for the FreeBSD kernel, which
+	is why this display shows <devicename>ad0</devicename> and
+	<devicename>ad2</devicename>.  The machine on which this screenshot
+	was taken had IDE disks on both master channels of the IDE
+	controllers, and no disks on the slave channels.</para>
+
+      <para>You should select the disk on which you want to install FreeBSD,
+	and then press &gui.ok;.
+	<application>FDisk</application> will start, with a display similar to
+	that shown in <xref linkend="sysinstall-fdisk1">.</para>
+
+      <para>The <application>FDisk</application> display is broken into three
+	sections.</para>
+
+      <para>The first section, covering the first two lines of the display,
+	shows details about the currently selected disk, including its FreeBSD
+	name, the disk geometry, and the total size of the disk.</para>
+
+      <para>The second section shows the slices that are currently on the
+	disk, where they start and end, how large they are, the name FreeBSD
+	gives them, and their description and sub-type.  This example shows two
+	small unused slices, which are artifacts of disk layout schemes on the
+	PC.  It also shows one large <acronym>FAT</acronym> slice, which almost certainly appears
+	as <devicename>C:</devicename> in &ms-dos; / &windows;, and an extended
+	slice, which may contain other drive letters for &ms-dos; / &windows;.</para>
+
+      <para>The third section shows the commands that are available in
+	<application>FDisk</application>.</para>
+
+      <figure id="sysinstall-fdisk1">
+	<title>Typical Fdisk Partitions before Editing</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/fdisk-edit1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>What you do now will depend on how you want to slice up your
+	disk.</para>
+
+      <para>If you want to use FreeBSD for the entire disk (which will delete
+	all the other data on this disk when you confirm that you want
+	<application>sysinstall</application> to continue later in the
+	installation process) then you can press <keycap>A</keycap>, which
+	corresponds to the <guimenuitem>Use Entire Disk</guimenuitem> option.
+	The existing slices will be removed, and replaced with a small area
+	flagged as <literal>unused</literal> (again, an artifact of PC disk
+	layout), and then one large slice for FreeBSD.  If you do this, then
+	you should select the newly created FreeBSD slice using the arrow
+	keys, and press <keycap>S</keycap> to mark the slice as being
+	bootable.  The screen will then look very similar to 
+	<xref linkend="sysinstall-fdisk2">.  Note the
+	<literal>A</literal> in the <literal>Flags</literal> column, which
+	indicates that this slice is <emphasis>active</emphasis>, and will be
+	booted from.</para>
+
+      <para>If you will be deleting an existing slice to make space for
+	FreeBSD then you should select the slice using the arrow keys, and
+	then press <keycap>D</keycap>.  You can then press <keycap>C</keycap>,
+	and be prompted for size of slice you want to create.  Enter the
+	appropriate figure and press <keycap>Enter</keycap>.  The default
+        value in this box represents the largest possible slice you can
+	make, which could be the largest contiguous block of unallocated
+	space or the size of the entire hard disk.</para>
+      
+      <para>If you have already made space for FreeBSD (perhaps by using a
+	tool such as <application>&partitionmagic;</application>) then you can
+	press <keycap>C</keycap> to create a new slice.  Again, you will be
+	prompted for the size of slice you would like to create.</para>
+
+      <figure id="sysinstall-fdisk2">
+	<title>Fdisk Partition Using Entire Disk</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/fdisk-edit2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>When finished, press <keycap>Q</keycap>.  Your changes will be
+	saved in <application>sysinstall</application>, but will not yet be
+	written to disk.</para>
+    </sect2>
+
+    <sect2 id="bootmgr">
+      <title>Install a Boot Manager</title>
+
+      <para>You now have the option to install a boot manager.  In general,
+	you should choose to install the FreeBSD boot manager if:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>You have more than one drive, and have installed FreeBSD onto
+	    a drive other than the first one.</para>
+	</listitem>
+
+	<listitem>
+	  <para>You have installed FreeBSD alongside another operating system
+	    on the same disk, and you want to choose whether to start FreeBSD
+	    or the other operating system when you start the computer.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>If FreeBSD is going to be the only operating system on
+	this machine, installed on the first hard disk, then the
+	<guimenuitem>Standard</guimenuitem> boot manager will suffice.
+	Choose <guimenuitem>None</guimenuitem> if you are using a
+	third-party boot manager capable of booting FreeBSD.</para>
+
+      <para>Make your choice and press <keycap>Enter</keycap>.</para>
+
+      <figure id="sysinstall-bootmgr">
+	<title>Sysinstall Boot Manager Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/boot-mgr" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The help screen, reached by pressing <keycap>F1</keycap>,
+	discusses the problems that can be encountered when trying to share
+	the hard disk between operating systems.</para>
+    </sect2>
+
+    <sect2>
+      <title>Creating Slices on Another Drive</title>
+
+      <para>If there is more than one drive, it will return to the
+	Select Drives screen after the boot manager selection.  If you wish to
+	install FreeBSD on to more than one disk, then you can select another
+	disk here and repeat the slice process using
+	<application>FDisk</application>.</para>
+
+      <important>
+	<para>If you are installing FreeBSD on a drive other than your
+	  first, then the FreeBSD boot manager needs to be installed on
+	  both drives.</para>
+      </important>
+
+      <figure id="sysinstall-fdisk-drive2">
+	<title>Exit Select Drive</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/fdisk-drive2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The <keycap>Tab</keycap> key toggles between the last drive
+	selected, &gui.ok;, and 
+	&gui.cancel;.</para>
+
+      <para>Press the <keycap>Tab</keycap> once to toggle to the
+	&gui.ok;, then
+	press <keycap>Enter</keycap>
+	to continue with the installation.</para>
+    </sect2>
+
+    <sect2 id="bsdlabeleditor">
+      <title>Creating Partitions Using
+	<application>Disklabel</application></title>
+      
+      <para>You must now create some partitions inside each slice that you
+	have just created.  Remember that each partition is lettered, from
+	<literal>a</literal> through to <literal>h</literal>, and that
+	partitions <literal>b</literal>, <literal>c</literal>, and
+	<literal>d</literal> have conventional meanings that you should adhere
+	to.</para>
+
+      <para>Certain applications can benefit from particular partition
+	schemes, especially if you are laying out partitions across more than
+	one disk.  However, for this, your first FreeBSD installation, you do
+	not need to give too much thought to how you partition the disk.  It
+	is more important that you install FreeBSD and start learning how to
+	use it.  You can always re-install FreeBSD to change your partition
+	scheme when you are more familiar with the operating system.</para>
+
+      <para>This scheme features four partitions&mdash;one for swap space, and
+	three for filesystems.</para>
+
+      <table frame="none" pgwide="1">
+	<title>Partition Layout for First Disk</title>
+
+	<tgroup cols="4">
+          <colspec colwidth="1*">
+          <colspec colwidth="1*">
+          <colspec colwidth="1*">
+          <colspec colwidth="4*">
+
+	  <thead>
+	    <row>
+	      <entry>Partition</entry>
+	      
+	      <entry>Filesystem</entry>
+
+	      <entry>Size</entry>
+
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><literal>a</literal></entry>
+
+	      <entry><filename>/</filename></entry>
+
+	      <entry>100&nbsp;MB</entry>
+
+	      <entry>This is the root filesystem.  Every other filesystem
+		will be mounted somewhere under this one.  100&nbsp;MB is a
+		reasonable size for this filesystem.  You will not be storing
+		too much data on it, as a regular FreeBSD install will put
+		about 40&nbsp;MB of data here.  The remaining space is for temporary
+		data, and also leaves expansion space if future versions of
+		FreeBSD need more space in <filename>/</filename>.</entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>b</literal></entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>2-3 x RAM</entry>
+
+	      <entry><para>The system's swap space is kept on this partition.
+		  Choosing the right amount of swap space can be a bit of an
+		  art.  A good rule of thumb is that your swap
+		  space should be two or three times as much as the
+		  available physical memory (RAM).
+		  You should also have at least 64&nbsp;MB of swap, so if you have
+		  less than 32&nbsp;MB of RAM in your computer then set the swap
+		  amount to 64&nbsp;MB.</para><para>
+
+		  If you have more than one disk then you can put swap
+		  space on each disk.  FreeBSD will then use each disk for 
+		  swap, which effectively speeds up the act of swapping.  In
+		  this case, calculate the total amount of swap you need
+		  (e.g., 128&nbsp;MB), and then divide this by the number of disks
+		  you have (e.g., two disks) to give the amount of swap you
+		  should put on each disk, in this example, 64&nbsp;MB of swap per
+		  disk.</para></entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>e</literal></entry>
+
+	      <entry><filename>/var</filename></entry>
+
+	      <entry>50&nbsp;MB</entry>
+
+	      <entry>The <filename>/var</filename> directory contains
+		files that are constantly varying;
+		log files, and other administrative files.  Many
+		of these files are read-from or written-to extensively during
+		FreeBSD's day-to-day running.  Putting these files on another
+		filesystem allows FreeBSD to optimize the access of these
+		files without affecting other files in other directories that
+		do not have the same access pattern.</entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>f</literal></entry>
+
+	      <entry><filename>/usr</filename></entry>
+
+	      <entry>Rest of disk</entry>
+
+	      <entry>All your other files will typically be stored in
+		<filename>/usr</filename> and its subdirectories.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+      
+      <para>If you will be installing FreeBSD on to more than one disk then
+	you must also create partitions in the other slices that you
+	configured.  The easiest way to do this is to create two partitions on
+	each disk, one for the swap space, and one for a filesystem.</para>
+
+      <table frame="none" pgwide="1">
+	<title>Partition Layout for Subsequent Disks</title>
+
+	<tgroup cols="4">
+          <colspec colwidth="1*">
+          <colspec colwidth="1*">
+          <colspec colwidth="2*">
+          <colspec colwidth="3*">
+
+	  <thead>
+	    <row>
+	      <entry>Partition</entry>
+	      
+	      <entry>Filesystem</entry>
+
+	      <entry>Size</entry>
+
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><literal>b</literal></entry>
+
+	      <entry>N/A</entry>
+
+	      <entry>See description</entry>
+
+	      <entry>As already discussed, you can split swap space across
+		each disk.  Even though the <literal>a</literal> partition is
+		free, convention dictates that swap space stays on the
+		<literal>b</literal> partition.</entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>e</literal></entry>
+
+	      <entry>/disk<replaceable>n</replaceable></entry>
+
+	      <entry>Rest of disk</entry>
+
+	      <entry>The rest of the disk is taken up with one big partition.
+		This could easily be put on the <literal>a</literal>
+		partition, instead of the <literal>e</literal> partition.
+		However, convention says that the <literal>a</literal>
+		partition on a slice is reserved for the filesystem that will
+		be the root (<filename>/</filename>) filesystem.  You do not
+		have to follow this convention, but
+		<application>sysinstall</application> does, so following it
+		yourself makes the installation slightly cleaner.  You can
+		choose to mount this filesystem anywhere; this example
+		suggests that you mount them as directories
+		<filename>/disk<replaceable>n</replaceable></filename>, where
+		<replaceable>n</replaceable> is a number that changes for each
+		disk.  But you can use another scheme if you prefer.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <para>Having chosen your partition layout you can now create it using
+	<application>sysinstall</application>.  You will see this
+	message:</para>
+
+      <screen>                                 Message
+ Now, you need to create BSD partitions inside of the fdisk
+ partition(s) just created. If you have a reasonable amount of disk
+ space (200MB or more) and don't have any special requirements, simply
+ use the (A)uto command to allocate space automatically. If you have
+ more specific needs or just don't care for the layout chosen by
+ (A)uto, press F1 for more information on manual layout.  
+
+                                [  OK  ]
+                          [ Press enter or space ]</screen>
+
+      <para>Press <keycap>Enter</keycap> to start the FreeBSD partition
+	editor, called <application>Disklabel</application>.</para>
+
+      <para><xref linkend="sysinstall-label"> shows the display when you first
+	start <application>Disklabel</application>.  The display is divided in
+	to three sections.</para>
+
+      <para>The first few lines show the name of the disk you are currently
+	working on, and the slice that contains the partitions you are
+	creating (at this point <application>Disklabel</application> calls
+	this the <literal>Partition name</literal> rather than slice name).
+	This display also shows the amount of free space within the slice;
+	that is, space that was set aside in the slice, but that has not yet
+	been assigned to a partition.</para>
+
+      <para>The middle of the display shows the partitions that have been
+	created, the name of the filesystem that each partition contains,
+	their size, and some options pertaining to the creation of the
+	filesystem.</para>
+
+      <para>The bottom third of the screen shows the keystrokes that are valid
+	in <application>Disklabel</application>.</para>
+
+      <figure id="sysinstall-label">
+	<title>Sysinstall Disklabel Editor</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-ed1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para><application>Disklabel</application> can automatically create
+	partitions for you and assign them default sizes.  Try this now, by
+	Pressing <keycap>A</keycap>.  You will see a display similar to that
+	shown in <xref linkend="sysinstall-label2">.  Depending on the size of
+	the disk you are using, the defaults may or may not be appropriate.
+	This does not matter, as you do not have to accept the
+	defaults.</para>
+
+	<note>
+	  <para>The default partitioning assigns
+	    the <filename>/tmp</filename> directory its own partition instead
+	    of being part of the <filename>/</filename> partition.  This
+	    helps avoid filling the <filename>/</filename> partition with
+	    temporary files.</para>
+	</note>
+
+      <figure id="sysinstall-label2">
+	<title>Sysinstall Disklabel Editor with Auto Defaults</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-auto" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>If you choose to not use the default partitions and wish to
+	replace them with your
+	own, use the arrow keys to select the first partition, and press
+	<keycap>D</keycap> to delete it.  Repeat this to delete all the
+	suggested partitions.</para>
+
+      <para>To create the first partition (<literal>a</literal>, mounted as
+	<filename>/</filename> &mdash; root), make sure the proper disk slice at the top of
+	the screen is selected and press <keycap>C</keycap>.  A dialog box
+	will appear prompting you for the size of the new partition (as shown
+	in <xref linkend="sysinstall-label-add">).  You can enter the size as
+	the number of disk blocks you want to use, or as a
+	number followed by either <literal>M</literal> for megabytes,
+	<literal>G</literal> for gigabytes, or <literal>C</literal> for
+	cylinders.</para>
+
+      <note><para>Beginning with FreeBSD&nbsp;5.X, users can: select
+	<acronym>UFS2</acronym> (which is default on &os;&nbsp;5.1 and
+	above) using the <literal>Custom Newfs</literal>
+	(<keycap>Z</keycap>) option, create labels with
+	<literal>Auto Defaults</literal> and modify them with the <literal>Custom Newfs</literal> option or
+	add <option>-O 2</option> during the regular creation period.
+	Do not forget to add <option>-U</option> for SoftUpdates if you use the <literal>Custom Newfs</literal>
+	option!</para></note>
+
+      <figure id="sysinstall-label-add">
+	<title>Free Space for Root Partition</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-root1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The default size shown will create a partition that takes up the
+	rest of the slice.  If you are using the partition sizes described
+	in the earlier example, then delete the existing figure using
+	<keycap>Backspace</keycap>, and then type in
+	<userinput>64M</userinput>, as shown in 
+	<xref linkend="sysinstall-label-add2">.  Then press
+	&gui.ok;.</para>
+      
+      <figure id="sysinstall-label-add2">
+	<title>Edit Root Partition Size</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-root2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Having chosen the partition's size you will then be asked whether
+	this partition will contain a filesystem or swap space.  The dialog
+	box is shown in <xref linkend="sysinstall-label-type">.  This first
+	partition will contain a filesystem, so check that
+	<guimenuitem>FS</guimenuitem> is selected and press
+	<keycap>Enter</keycap>.</para>
+
+      <figure id="sysinstall-label-type">
+	<title>Choose the Root Partition Type</title>
+	
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-fs" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+      
+      <para>Finally, because you are creating a filesystem, you must tell
+	<application>Disklabel</application> where the filesystem is to be
+	mounted.  The dialog box is shown in 
+	<xref linkend="sysinstall-label-mount">.  The root filesystem's mount
+	point is <filename>/</filename>, so type <userinput>/</userinput>, and
+	then press <keycap>Enter</keycap>.</para>
+
+      <figure id="sysinstall-label-mount">
+	<title>Choose the Root Mount Point</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-root3" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The display will then update to show you the newly created
+	partition.  You should repeat this procedure for the other
+	partitions.  When you create the swap partition, you will not be
+	prompted for the filesystem mount point, as swap partitions are never
+	mounted.  When you create the final partition,
+	<filename>/usr</filename>, you can leave the suggested size as is, to
+	use the rest of the slice.</para>
+
+      <para>Your final FreeBSD DiskLabel Editor screen will appear similar to
+	<xref linkend="sysinstall-label4">, although your values chosen may
+	be different.  Press <keycap>Q</keycap> to finish.</para>
+
+      <figure id="sysinstall-label4">
+	<title>Sysinstall Disklabel Editor</title>
+	
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/disklabel-ed2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-choosing">
+    <title>Choosing What to Install</title>
+
+    <sect2 id="distset">
+      <title>Select the Distribution Set</title>
+
+      <para>Deciding which distribution set to install will depend largely
+	on the intended use of the system and the amount of disk space
+	available.  The predefined options range from installing the
+	smallest possible configuration to everything.  Those who are
+	new to &unix; and/or FreeBSD should almost certainly select one
+	of these canned options.  Customizing a distribution set is
+	typically for the more experienced user.</para>
+
+      <para>Press <keycap>F1</keycap> for more information on the 
+	distribution set options and what they contain.  When finished
+	reviewing the help, pressing <keycap>Enter</keycap> will return
+	to the Select Distributions Menu.</para>
+
+      <para>If a graphical user interface is desired then a distribution
+	set that is preceded by an <literal>X</literal> should be
+	chosen.  The configuration of the X server and selection of a default
+	desktop must be done after the installation of &os;.  More
+	information regarding the configuration of a X server can be
+	found in <xref linkend="x11">.</para>
+
+      <para>The default version of X11 that is installed depends on the
+	version of FreeBSD that you are installing.  For FreeBSD versions
+	prior to 5.3, <application>&xfree86;&nbsp;4.X</application> is installed.  For &os;&nbsp;5.3 and later,
+	<application>&xorg;</application> is the default.</para>
+
+      <para>If compiling a custom kernel is anticipated, select an option
+	which includes the source code.  For more information on why a
+	custom kernel should be built or how to build a custom kernel, see
+	<xref linkend="kernelconfig">.</para>
+
+      <para>Obviously, the most versatile system is one that includes
+	everything.  If there is adequate disk space, select 
+	<guimenuitem>All</guimenuitem> as shown in
+	<xref linkend="distribution-set1"> by using the arrow keys and
+	press <keycap>Enter</keycap>.  If there is a concern about disk
+	space consider using an option that is more suitable for the
+	situation.
+	Do not fret over the perfect choice, as other distributions can be
+	added after installation.</para>
+
+      <figure id="distribution-set1">
+	<title>Choose Distributions</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/dist-set" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+    </sect2>
+
+    <sect2 id="portscol">
+      <title>Installing the Ports Collection</title>
+
+      <para>After selecting the desired distribution, an opportunity to
+	install the FreeBSD Ports Collection is presented.  The ports
+	collection is an easy and convenient way to install software.
+	The Ports Collection does not contain the source code necessary
+	to compile the software.  Instead, it is a collection of files which
+	automates the downloading, compiling and installation
+	of third-party software packages.
+	<xref linkend="ports"> discusses how to use the ports
+	collection.</para>
+
+      <para>The installation program does not check to see if you have
+	adequate space.  Select this option only if you have
+	adequate hard disk space. As of FreeBSD &rel.current;, the FreeBSD
+	Ports Collection takes up about &ports.size; of disk space.
+	You can safely assume a larger value for more recent versions
+	of FreeBSD.</para>
+
+<screen>                         User Confirmation Requested
+ Would you like to install the FreeBSD ports collection? 
+
+ This will give you ready access to over &os.numports; ported software packages,
+ at a cost of around &ports.size; of disk space when "clean" and possibly much
+ more than that if a lot of the distribution tarballs are loaded
+ (unless you have the extra CDs from a FreeBSD CD/DVD distribution
+ available and can mount it on /cdrom, in which case this is far less
+ of a problem). 
+
+ The Ports Collection is a very valuable resource and well worth having
+ on your /usr partition, so it is advisable to say Yes to this option. 
+
+ For more information on the Ports Collection &amp; the latest ports,
+ visit: 
+     http://www.FreeBSD.org/ports  
+
+                              [ Yes ]     No</screen>
+
+      <para>Select &gui.yes; with the arrow keys to
+	install the Ports Collection or &gui.no; to
+	skip this option.  Press <keycap>Enter</keycap> to continue.
+	The Choose Distributions menu will redisplay.</para>
+
+      <figure id="distribution-set2">
+	<title>Confirm Distributions</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/dist-set2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>If satisfied with the options, select
+	<guimenuitem>Exit</guimenuitem> with the arrow keys, ensure that
+	&gui.ok; is highlighted, and pressing
+	<keycap>Enter</keycap> to continue.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-media">
+    <title>Choosing Your Installation Media</title>
+
+    <para>If Installing from a CDROM or DVD, use the arrow keys to highlight 
+      <guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>.  Ensure
+      that &gui.ok; is highlighted, then press
+      <keycap>Enter</keycap> to proceed with the installation.</para>
+    
+    <para>For other methods of installation, select the appropriate
+      option and follow the instructions.</para>
+
+    <para>Press <keycap>F1</keycap> to display the Online Help for
+      installation media.  Press <keycap>Enter</keycap> to return
+      to the media selection menu.</para>
+
+    <figure id="choose-media">
+      <title>Choose Installation Media</title>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="install/media" format="PNG">
+	</imageobject>
+      </mediaobject>
+    </figure>
+
+    <note>
+      <title>FTP Installation Modes</title>
+
+      <indexterm>
+	<primary>installation</primary>
+	<secondary>network</secondary>
+	<tertiary>FTP</tertiary>
+      </indexterm>
+      
+      <para>There are three FTP installation modes you can choose from:
+	active FTP, passive FTP, or via a HTTP proxy.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>FTP Active: <guimenuitem>Install from an FTP
+	      server</guimenuitem></term>
+	  
+	  <listitem>
+	    <para>This option will make all FTP transfers 
+	      use <quote>Active</quote>
+	      mode.  This will not work through firewalls, but will
+	      often work with older FTP servers that do not support
+	      passive mode.  If your connection hangs with passive
+	      mode (the default), try active!</para>
+	  </listitem>
+	</varlistentry>
+	
+	<varlistentry>
+	  <term>FTP Passive: <guimenuitem>Install from an FTP server through a
+	      firewall</guimenuitem></term>
+	  
+	  <listitem>
+	    <indexterm>
+	      <primary>FTP</primary>
+	      <secondary>passive mode</secondary>
+	    </indexterm>
+
+	    <para>This option instructs <application>sysinstall</application> to use 
+	      <quote>Passive</quote> mode for all FTP operations.  
+	      This allows the user to pass through firewalls
+	      that do not allow incoming connections on random TCP ports.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	
+	<varlistentry>
+	  <term>FTP via a HTTP proxy: <guimenuitem>Install from an FTP server
+	      through a http proxy</guimenuitem></term>
+	    
+	  <listitem>
+	    <indexterm>
+	      <primary>FTP</primary>
+	      <secondary>via a HTTP proxy</secondary>
+	    </indexterm>
+	    
+	    <para>This option instructs <application>sysinstall</application> to use the HTTP
+	      protocol (like a web browser) to connect to a proxy
+	      for all FTP operations.  The proxy will translate
+	      the requests and send them to the FTP server.
+	      This allows the user to pass through firewalls
+	      that do not allow FTP at all, but offer a HTTP
+	      proxy.
+	      In this case, you have to specify the proxy in
+	      addition to the FTP server.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+      
+      <para>For a proxy FTP server, you should usually give the name of the
+	server you really want as a part of the username, after an
+	<quote>@</quote> sign.  The proxy server then <quote>fakes</quote>
+	the real server.  For example, assuming you want to install from
+	<hostid role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy FTP
+	server <hostid role="fqdn">foo.example.com</hostid>, listening on port
+	1024.</para>
+      
+      <para>In this case, you go to the options menu, set the FTP username
+	to <literal>ftp@ftp.FreeBSD.org</literal>, and the password to your
+	email address.  As your installation media, you specify FTP (or
+	passive FTP, if the proxy supports it), and the URL
+	<literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para>
+
+      <para>Since <filename>/pub/FreeBSD</filename> from 
+	<hostid role="fqdn">ftp.FreeBSD.org</hostid> is proxied under 
+	<hostid role="fqdn">foo.example.com</hostid>, you are able to install
+	from <emphasis>that</emphasis> machine (which will fetch the files
+	from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your 
+	installation requests them).</para>
+    </note>
+  </sect1>
+
+  <sect1 id="install-final-warning">
+    <title>Committing to the Installation</title>
+
+    <para>The installation can now proceed if desired.  This is also
+      the last chance for aborting the installation to prevent changes
+      to the hard drive.</para>
+
+    <screen>                       User Confirmation Requested
+ Last Chance! Are you SURE you want to continue the installation? 
+
+ If you're running this on a disk with data you wish to save then WE
+ STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! 
+
+ We can take no responsibility for lost disk contents!  
+
+                             [ Yes ]    No</screen>
+
+    <para>Select &gui.yes; and press 
+      <keycap>Enter</keycap> to proceed.</para>
+
+    <para>The installation time will vary according to the distribution
+      chosen, installation media, and the speed of the computer.
+      There will be a series of
+      messages displayed indicating the status.</para>
+    
+    <para>The installation is complete when the following message is
+      displayed:</para>
+
+    <screen>                               Message 
+
+Congratulations! You now have FreeBSD installed on your system. 
+
+We will now move on to the final configuration questions. 
+For any option you do not wish to configure, simply select No. 
+
+If you wish to re-enter this utility after the system is up, you may
+do so by typing: /stand/sysinstall .  
+
+                                 [ OK ] 
+
+                      [  Press enter to continue  ]</screen>
+
+    <para>Press <keycap>Enter</keycap> to proceed with post-installation
+      configurations.</para>
+
+    <para>Selecting &gui.no; and pressing
+      <keycap>Enter</keycap> will abort
+      the installation so no changes will be made to your system.  The
+      following message will appear:</para>
+
+    <screen>                                Message
+Installation complete with some errors.  You may wish to scroll
+through the debugging messages on VTY1 with the scroll-lock feature. 
+You can also choose "No" at the next prompt and go back into the
+installation menus to retry whichever operations have failed. 
+
+                                 [ OK ]</screen>
+
+    <para>This message is generated because nothing was installed.
+      Pressing <keycap>Enter</keycap> will return to the
+      Main Installation Menu to exit the installation.</para>
+  </sect1>
+
+  <sect1 id="install-post">
+    <title>Post-installation</title>
+
+    <para>Configuration of various options follows the successful 
+      installation.    An option can be configured by re-entering the
+      configuration options before booting the new FreeBSD
+      system or after installation using
+      <command>sysinstall</command> (<command>/stand/sysinstall</command>
+      in &os; versions older than 5.2) and selecting
+      <guimenuitem>Configure</guimenuitem>.</para>
+
+    <sect2 id="inst-network-dev">
+      <title>Network Device Configuration</title>
+
+      <para>If you previously configured PPP for an FTP install, this screen
+	will not display and can be configured later as described
+	above.</para>
+
+      <para>For detailed information on Local Area Networks and
+	configuring FreeBSD as a gateway/router refer to the
+	<link linkend="advanced-networking">Advanced Networking</link>
+	chapter.</para>
+
+      <screen>                      User Confirmation Requested 
+   Would you like to configure any Ethernet or SLIP/PPP network devices?
+
+                             [ Yes ]   No</screen>
+
+      <para>To configure a network device, select
+	&gui.yes; and press <keycap>Enter</keycap>.
+      Otherwise, select &gui.no; to continue.</para>
+
+      <figure id="ed-config1">
+	<title>Selecting an Ethernet Device</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/ed0-conf" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Select the interface to be configured with the arrow keys and press
+	<keycap>Enter</keycap>.</para>
+
+      <screen>                      User Confirmation Requested 
+       Do you want to try IPv6 configuration of the interface?
+
+                              Yes   [ No ]</screen>
+
+      <para>In this private local area network, the current Internet
+	type protocol (<acronym>IPv4</acronym>) was sufficient and &gui.no;
+	was selected with the arrow keys and <keycap>Enter</keycap>
+	pressed.</para>
+
+      <para>If you are connected to an existing <acronym>IPv6</acronym> network
+	with an <acronym>RA</acronym> server, then choose
+	&gui.yes; and press <keycap>Enter</keycap>.
+	It will take several seconds to scan for RA servers.</para>
+
+      <screen>                             User Confirmation Requested 
+        Do you want to try DHCP configuration of the interface?
+
+                              Yes   [ No ]</screen>
+
+      <para>If DHCP (Dynamic Host Configuration Protocol) is not required
+	select &gui.no; with the arrow keys and press
+	<keycap>Enter</keycap>.</para>
+
+      <para>Selecting &gui.yes; will execute
+	<application>dhclient</application>, and if successful, will fill
+	in the network configuration information automatically.  Refer to
+	<xref linkend="network-dhcp"> for more information.</para>
+
+      <para>The following Network Configuration screen shows the
+	configuration of the Ethernet device for a system that will act
+	as the gateway for a Local Area Network.</para>
+
+      <figure id="ed-config2">
+	<title>Set Network Configuration for ed0</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/ed0-conf2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Use <keycap>Tab</keycap> to select the information fields and
+	fill in appropriate information:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Host</term>
+
+	  <listitem>
+	    <para>The fully-qualified hostname, such as <hostid role="fqdn">k6-2.example.com</hostid> in
+	      this case.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Domain</term>
+
+	  <listitem>
+	    <para>The name of the domain that your machine is
+	      in, such as <hostid role="domainname">example.com</hostid> for this case.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>IPv4 Gateway</term>
+
+	  <listitem>
+	    <para>IP address of host forwarding packets to non-local
+	      destinations.  You must fill this in if the machine is a node
+	      on the network.  <emphasis>Leave this field blank</emphasis>
+	      if the machine is the gateway to the Internet for the
+	      network.  The IPv4 Gateway is also known as the default
+	      gateway or default route.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Name server</term>
+
+	  <listitem>
+	    <para>IP address of your local DNS server.  There is no local
+	      DNS server on this private local area network so the IP
+	      address of the provider's DNS server
+	      (<hostid role="ipaddr">208.163.10.2</hostid>) was used.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>IPv4 address</term>
+
+	  <listitem>
+	    <para>The IP address to be used for this interface was
+	      <hostid role="ipaddr">192.168.0.1</hostid></para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Netmask</term>
+
+	  <listitem>
+	    <para>The address block being used for this local area
+	      network is a Class C block
+	      (<hostid role="ipaddr">192.168.0.0</hostid> -
+	      <hostid role="ipaddr">192.168.255.255</hostid>).
+	      The default netmask is for a Class C network
+	      (<hostid role="netmask">255.255.255.0</hostid>).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Extra options to ifconfig</term>
+
+	  <listitem>
+	    <para>Any interface-specific options to <command>ifconfig</command>
+	      you would like to add.  There were none in this case.</para>
+	  </listitem>
+	</varlistentry>
+
+      </variablelist>
+
+      <para>Use <keycap>Tab</keycap> to select &gui.ok;
+	when finished and press <keycap>Enter</keycap>.</para>
+
+
+      <screen>                      User Confirmation Requested 
+        Would you like to Bring Up the ed0 interface right now?
+
+                             [ Yes ]   No</screen>
+
+      <para>Choosing &gui.yes; and pressing
+	<keycap>Enter</keycap> will bring
+	the machine up on the network and be ready for use.  However,
+	this does not accomplish much during installation, since
+	the machine still needs to be rebooted.</para>
+    </sect2>
+
+    <sect2 id="gateway">
+      <title>Configure Gateway</title>
+
+      <screen>                       User Confirmation Requested 
+       Do you want this machine to function as a network gateway?
+
+                              [ Yes ]    No</screen>
+
+      <para>If the machine will be acting as the gateway for a local area
+	network and forwarding packets between other machines then select
+	&gui.yes; and press <keycap>Enter</keycap>.
+	If the machine is a node on a network then 
+	select &gui.no; and press
+	<keycap>Enter</keycap> to continue.</para>
+    </sect2>
+
+    <sect2 id="inetd-services">
+      <title>Configure Internet Services</title>
+
+      <screen>                      User Confirmation Requested
+Do you want to configure inetd and the network services that it provides?
+
+                               Yes   [ No ]</screen>
+
+      <para>If &gui.no; is selected, various services
+	such <application>telnetd</application> will not be enabled.  This
+	means that remote users will not be able to
+	<application>telnet</application> into this machine.  Local users
+	will be still be able to access remote machines with
+	<application>telnet</application>.</para>
+
+      <para>These services can be enabled after installation by editing
+	<filename>/etc/inetd.conf</filename> with your favorite text editor.
+	See <xref linkend="network-inetd-overview"> for more information.</para>
+
+      <para>Select &gui.yes; if you wish to
+	configure these services during install.  An additional
+	confirmation will display:</para>
+
+      <screen>                      User Confirmation Requested
+The Internet Super Server (inetd) allows a number of simple Internet
+services to be enabled, including finger, ftp and telnetd.  Enabling
+these services may increase risk of security problems by increasing
+the exposure of your system.
+
+With this in mind, do you wish to enable inetd?
+
+                             [ Yes ]   No</screen>
+
+      <para>Select &gui.yes; to continue.</para>
+
+      <screen>                      User Confirmation Requested
+inetd(8) relies on its configuration file, /etc/inetd.conf, to determine
+which of its Internet services will be available.  The default FreeBSD
+inetd.conf(5) leaves all services disabled by default, so they must be
+specifically enabled in the configuration file before they will
+function, even once inetd(8) is enabled.  Note that services for
+IPv6 must be separately enabled from IPv4 services.
+
+Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to
+use the current settings.
+
+                             [ Yes ]   No</screen>
+
+      <para>Selecting &gui.yes; will allow adding
+	services by deleting the <literal>#</literal> at the beginning
+	of a line.</para>
+
+      <figure id="inetd-edit">
+	<title>Editing <filename>inetd.conf</filename></title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/edit-inetd-conf" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>After adding the desired services, pressing <keycap>Esc</keycap>
+	will display a menu which will allow exiting and saving 
+	the changes.</para>
+
+    </sect2>
+
+    <sect2 id="ftpanon">
+      <title>Anonymous FTP</title>
+
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
+      <screen>                      User Confirmation Requested
+ Do you want to have anonymous FTP access to this machine? 
+
+                              Yes    [ No ]</screen>
+
+      <sect3 id="deny-anon">
+	<title>Deny Anonymous FTP</title>
+      
+	<para>Selecting the default &gui.no; and pressing
+	  <keycap>Enter</keycap> will still allow users who have accounts
+	  with passwords to use FTP to access the machine.</para>
+      </sect3>
+
+      <sect3 id="ftpallow">
+	<title>Allow Anonymous FTP</title>
+
+	<para>Anyone can access your machine if you elect to allow
+	  anonymous FTP connections.  The security implications should be
+	  considered before enabling this option.  For more information
+	  about security see <xref linkend="security">.</para>
+
+	<para>To allow anonymous FTP, use the arrow keys to select
+	  &gui.yes; and press <keycap>Enter</keycap>.
+	  The following screen (or similar) will display:</para>
+
+	<figure id="anon-ftp2">
+	  <title>Default Anonymous FTP Configuration</title>
+
+	  <mediaobject>
+	    <imageobject>
+	      <imagedata fileref="install/ftp-anon1" format="PNG">
+	    </imageobject>
+	  </mediaobject>
+	</figure>
+
+	<para>Pressing <keycap>F1</keycap> will display the help:</para>
+
+	<screen>This screen allows you to configure the anonymous FTP user.
+
+The following configuration values are editable:
+
+UID:     The user ID you wish to assign to the anonymous FTP user.
+         All files uploaded will be owned by this ID.
+
+Group:   Which group you wish the anonymous FTP user to be in.
+
+Comment: String describing this user in /etc/passwd
+
+
+FTP Root Directory:
+
+        Where files available for anonymous FTP will be kept.
+
+Upload subdirectory:
+
+        Where files uploaded by anonymous FTP users will go.</screen>
+
+	<para>The ftp root directory will be put in <filename>/var</filename>
+	  by default.  If you do not have enough room there for the
+	  anticipated FTP needs, the <filename>/usr</filename> directory
+	  could be used by setting the FTP Root Directory to
+	  <filename>/usr/ftp</filename>.</para>
+
+	<para>When you are satisfied with the values, press 
+	  <keycap>Enter</keycap> to continue.</para>
+
+	<screen>                          User Confirmation Requested 
+         Create a welcome message file for anonymous FTP users?
+
+                              [ Yes ]    No</screen>
+
+	<para>If you select &gui.yes; and press
+	  <keycap>Enter</keycap>, an editor will automatically start
+	  allowing you to edit the message.</para>
+
+	<figure id="anon-ftp4">
+	  <title>Edit the FTP Welcome Message</title>
+
+	  <mediaobject>
+	    <imageobject>
+	      <imagedata fileref="install/ftp-anon2" format="PNG">
+	    </imageobject>
+	  </mediaobject>
+	</figure>
+
+	<para>This is a text editor called <command>ee</command>.  Use the
+	  instructions to change the message or change the message later
+	  using a text editor of your choice.  Note the file name/location
+	  at the bottom of the editor screen.</para>
+
+	<para>Press <keycap>Esc</keycap> and a pop-up menu will default
+	  to <guimenuitem>a) leave editor</guimenuitem>.  Press
+	  <keycap>Enter</keycap> to exit and continue.  Press
+	  <keycap>Enter</keycap> again to save changes if you made
+	  any.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="nfsconf">
+      <title>Configure Network File System</title>
+
+      <para>Network File System (NFS) allows sharing of files across a
+	network.  A machine can be configured as a server, a client, or
+	both.  Refer to <xref linkend="network-nfs"> for a more information.</para>
+
+      <sect3 id="nsf-server-options">
+	<title>NFS Server</title>
+
+	<screen>                       User Confirmation Requested
+ Do you want to configure this machine as an NFS server? 
+
+                              Yes    [ No ]</screen>
+
+	<para>If there is no need for a Network File System server,
+	  select &gui.no; and press
+	  <keycap>Enter</keycap>.</para>
+
+	<para>If &gui.yes; is chosen, a message will
+	  pop-up indicating that the <filename>exports</filename> file must be
+	  created.</para>
+
+	<screen>                               Message
+Operating as an NFS server means that you must first configure an
+/etc/exports file to indicate which hosts are allowed certain kinds of
+access to your local filesystems.
+Press [Enter] now to invoke an editor on /etc/exports
+                               [ OK ]</screen>
+
+	<para>Press <keycap>Enter</keycap> to continue.  A text editor will
+	  start allowing the <filename>exports</filename> file to be created
+	  and edited.</para>
+
+	<figure id="nfs-server-edit">
+	  <title>Editing <filename>exports</filename></title>
+
+	  <mediaobject>
+	    <imageobject>
+	      <imagedata fileref="install/nfs-server-edit" format="PNG">
+	    </imageobject>
+	  </mediaobject>
+	</figure>
+
+	<para>Use the instructions to add the actual exported filesystems
+	  now or later using a text editor of your choice.  Note the
+	  file name/location at the bottom of the editor screen.</para>
+
+	<para>Press <keycap>Esc</keycap> and a pop-up menu will default to
+	  <guimenuitem>a) leave editor</guimenuitem>.  Press
+	  <keycap>Enter</keycap> to exit and continue.</para>
+      </sect3>
+
+      <sect3 id="nfs-client-options">
+	<title>NFS Client</title>
+
+	<para>The NFS client allows your machine to access NFS servers.</para>
+
+	<screen>                       User Confirmation Requested
+ Do you want to configure this machine as an NFS client? 
+
+                              Yes   [ No ]</screen>
+
+	<para>With the arrow keys, select &gui.yes;
+	  or &gui.no; as appropriate and
+	  press <keycap>Enter</keycap>.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="securityprofile">
+      <title>Security Profile</title>
+
+      <para>A <quote>security profile</quote> is a set of
+	configuration options that attempts to achieve the desired
+	ratio of security to convenience by enabling and disabling
+	certain programs and other settings.  The more severe the
+	security profile, the fewer programs will be enabled by
+	default.  This is one of the basic principles of security: do
+	not run anything except what you must.</para>
+
+      <para>Please note that the security profile is just a default
+	setting.  All programs can be enabled and disabled after you
+	have installed FreeBSD by editing or adding the appropriate
+	line(s) to <filename>/etc/rc.conf</filename>.  For more
+	information, please see the &man.rc.conf.5; manual
+	page.</para>
+
+      <para>The following table describes what each of the security
+	profiles does.  The columns are the choices you have for a
+	security profile, and the rows are the program or feature that
+	the profile enables or disables.</para>
+
+      <table>
+	<title>Possible Security Profiles</title>
+
+	<tgroup cols=3>
+	  <thead>
+	    <row>
+	      <entry></entry>
+
+	      <entry>Extreme</entry>
+
+	      <entry>Moderate</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+
+	    <row>
+	      <entry>&man.sendmail.8;</entry>
+
+	      <entry>NO</entry>
+
+	      <entry>YES</entry>
+	    </row>
+
+	    <row>
+	      <entry>&man.sshd.8;</entry>
+
+	      <entry>NO</entry>
+
+	      <entry>YES</entry>
+	    </row>
+
+	    <row>
+	      <entry>&man.portmap.8;</entry>
+
+	      <entry>NO</entry>
+
+	      <entry>MAYBE
+		<footnote>
+		  <para>The portmapper is enabled if the machine has
+		    been configured as an NFS client or server earlier
+		    in the installation.</para>
+		</footnote>
+	      </entry>
+	    </row>
+
+	    <row>
+	      <entry>NFS server</entry>
+
+	      <entry>NO</entry>
+
+	      <entry>YES</entry>
+	    </row>
+
+	    <row>
+	      <entry>&man.securelevel.8;</entry>
+
+	      <entry>YES
+		<footnote>
+		  <para>If you choose a security profile that sets the
+		    securelevel to <quote>Extreme</quote> or
+		    <quote>High</quote>, you must be aware of the
+		    implications.  Please read the &man.init.8;
+		    manual page and pay particular attention to the
+		    meanings of the security levels, or you may have
+		    significant trouble later!</para>
+		</footnote>
+	      </entry>
+
+	      <entry>NO</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <screen>                       User Confirmation Requested
+ Do you want to select a default security profile for this host (select
+ No for "medium" security)? 
+
+                            [ Yes ]    No</screen>
+
+      <para>Selecting &gui.no; and pressing
+	<keycap>Enter</keycap> will set the security profile to medium.</para>
+
+      <para>Selecting &gui.yes; and pressing
+	<keycap>Enter</keycap> will allow selecting a different security
+	profile.</para>
+
+      <figure id="security-profile">
+	<title>Security Profile Options</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/security" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Press <keycap>F1</keycap> to display the help.  Press
+	<keycap>Enter</keycap> to return to selection menu.</para>
+
+      <para>Use the arrow keys to choose <guimenuitem>Medium</guimenuitem>
+	unless your are sure that another level is required for your needs.
+	With &gui.ok; highlighted, press
+	<keycap>Enter</keycap>.</para>
+
+      <para>An appropriate confirmation message will display depending on
+	which security setting was chosen.</para>
+
+      <screen>                                 Message
+
+Moderate security settings have been selected.
+
+Sendmail and SSHd have been enabled, securelevels are
+disabled, and NFS server setting have been left intact.
+PLEASE NOTE that this still does not save you from having
+to properly secure your system in other ways or exercise
+due diligence in your administration, this simply picks
+a standard set of out-of-box defaults to start with.
+
+To change any of these settings later, edit /etc/rc.conf
+
+                                  [OK]</screen>
+
+      <screen>                                 Message
+
+Extreme security settings have been selected.
+
+Sendmail, SSHd, and NFS services have been disabled, and
+securelevels have been enabled.
+PLEASE NOTE that this still does not save you from having
+to properly secure your system in other ways or exercise
+due diligence in your administration, this simply picks
+a more secure set of out-of-box defaults to start with.
+
+To change any of these settings later, edit /etc/rc.conf
+
+                                  [OK]</screen>
+
+      <para>Press <keycap>Enter</keycap> to continue with the
+	post-installation configuration.</para>
+
+      <warning>
+	<para>The security profile is not a silver bullet!  Even if
+	  you use the extreme setting, you need to keep up with
+	  security issues by reading an appropriate mailing
+	  list (<xref linkend="eresources-mail">),
+	  using good passwords and passphrases, and
+	  generally adhering to good security practices.  It simply
+	  sets up the desired security to convenience ratio out of the
+	  box.</para>
+      </warning>
+
+    </sect2>
+
+    <sect2 id="console">
+      <title>System Console Settings</title>
+
+      <para>There are several options available to customize the system
+	console.</para>
+
+      <screen>                      User Confirmation Requested 
+       Would you like to customize your system console settings?
+
+                              [ Yes ]  No</screen>
+
+      <para>To view and configure the options, select
+	&gui.yes; and press
+	<keycap>Enter</keycap>.</para>
+
+      <figure id="saver-options">
+	<title>System Console Configuration Options</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/console-saver1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>A commonly used option is the screen saver.  Use the arrow keys
+	to select <guimenuitem>Saver</guimenuitem> and then press
+	<keycap>Enter</keycap>.</para>
+
+      <figure id="saver-select">
+	<title>Screen Saver Options</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/console-saver2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Select the desired screen saver using the arrow keys
+	and then press <keycap>Enter</keycap>.  The System Console
+	Configuration menu will redisplay.</para>
+
+      <para>The default time interval is 300 seconds.  To change the time
+	interval, select <guimenuitem>Saver</guimenuitem> again.  At the
+	Screen Saver Options menu, select <guimenuitem>Timeout</guimenuitem>
+	using the arrow keys and press <keycap>Enter</keycap>.  A pop-up
+	menu will appear:</para>
+
+      <figure id="saver-timeout">
+	<title>Screen Saver Timeout</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/console-saver3" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The value can be changed, then select &gui.ok;
+	and press <keycap>Enter</keycap> to return to the System Console
+	Configuration menu.</para>
+
+      <figure id="saver-exit">
+	<title>System Console Configuration Exit</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/console-saver4" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Selecting <guimenuitem>Exit</guimenuitem> and pressing
+	<keycap>Enter</keycap> will continue with the post-installation
+	configurations.</para>
+    </sect2>
+
+    <sect2 id="timezone">
+      <title>Setting the Time Zone</title>
+
+      <para>Setting the time zone for your machine will allow it to
+	automatically correct for any regional time changes and perform
+	other time zone related functions properly.</para>
+
+      <para>The example shown is for a machine located in the Eastern
+	time zone of the United States.  Your selections will vary according
+	to your geographical location.</para>
+
+      <screen>                      User Confirmation Requested 
+          Would you like to set this machine's time zone now?
+
+                            [ Yes ]   No</screen>
+
+      <para>Select &gui.yes; and press
+	<keycap>Enter</keycap> to set the time zone.</para>
+
+      <screen>                       User Confirmation Requested
+ Is this machine's CMOS clock set to UTC? If it is set to local time
+ or you don't know, please choose NO here! 
+
+                              Yes   [ No ]</screen>
+
+      <para>Select &gui.yes; 
+	or &gui.no; according to how the machine's
+	clock is configured and press <keycap>Enter</keycap>.</para>
+
+      <figure id="set-timezone-region">
+	<title>Select Your Region</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/timezone1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The appropriate region is selected using the arrow keys
+	and then pressing <keycap>Enter</keycap>.</para>
+
+      <figure id="set-timezone-country">
+	<title>Select Your Country</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/timezone2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Select the appropriate country using the arrow keys
+	and press <keycap>Enter</keycap>.</para>
+
+      <figure id="set-timezone-locality">
+	<title>Select Your Time Zone</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/timezone3" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The appropriate time zone is selected using the arrow
+	keys and pressing <keycap>Enter</keycap>.</para>
+
+      <screen>                            Confirmation 
+            Does the abbreviation 'EDT' look reasonable?
+
+                            [ Yes ]   No</screen>
+
+      <para>Confirm the abbreviation for the time zone is correct.
+	If it looks okay, press <keycap>Enter</keycap> to continue with
+	the post-installation configuration.</para>
+    </sect2>
+
+    <sect2 id="linuxcomp">
+      <title>Linux Compatibility</title>
+
+      <screen>                      User Confirmation Requested 
+          Would you like to enable Linux binary compatibility?
+
+                            [ Yes ]   No</screen>
+
+      <para>Selecting &gui.yes; and pressing
+	<keycap>Enter</keycap> will allow
+	running Linux software on FreeBSD.  The install will add
+	the appropriate packages for Linux compatibility.</para>
+
+      <para>If installing by FTP, the machine will need to be connected to
+	the Internet.  Sometimes a remote ftp site will not have all the
+	distributions like the Linux binary compatibility.  This can
+	be installed later if necessary.</para>
+    </sect2>
+
+    <sect2 id="mouse">
+      <title>Mouse Settings</title>
+
+      <para>This option will allow you to cut and paste text in the
+	console and user programs with a 3-button mouse.  If using a 2-button
+	mouse, refer to manual page, &man.moused.8;, after installation for
+	details on emulating the 3-button style.  This example depicts a
+	non-USB mouse configuration (such as a PS/2 or COM port mouse):</para>
+
+      <screen>                      User Confirmation Requested 
+         Does this system have a non-USB mouse attached to it?
+
+                            [ Yes ]    No </screen>
+
+      <para>Select &gui.yes; for a non-USB mouse or
+	&gui.no; for a USB mouse and press
+	<keycap>Enter</keycap>.</para>
+
+      <figure id="mouse-protocol">
+	<title>Select Mouse Protocol Type</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mouse1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Use the arrow keys to select <guimenuitem>Type</guimenuitem> and
+	press <keycap>Enter</keycap>.</para>
+
+      <figure id="set-mouse-protocol">
+	<title>Set Mouse Protocol</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mouse2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The mouse used in this example is a PS/2 type, so the default
+	<guimenuitem>Auto</guimenuitem> was appropriate.  To change protocol,
+	use the arrow keys to select another option.  Ensure that &gui.ok; is
+	highlighted and press <keycap>Enter</keycap> to exit this menu.</para>
+
+      <figure id="config-mouse-port">
+	<title>Configure Mouse Port</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mouse3" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Use the arrow keys to select <guimenuitem>Port</guimenuitem> and
+	press <keycap>Enter</keycap>.</para>
+
+      <figure id="set-mouse-port">
+	<title>Setting the Mouse Port</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mouse4" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>This system had a PS/2 mouse, so the default
+	<guimenuitem>PS/2</guimenuitem> was appropriate.  To change the port,
+	use the arrow keys and then press <keycap>Enter</keycap>.</para>
+
+      <figure id="test-daemon">
+	<title>Enable the Mouse Daemon</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mouse5" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Last, use the arrow keys to select
+	<guimenuitem>Enable</guimenuitem>, and press
+	<keycap>Enter</keycap> to enable and test the mouse
+	daemon.</para>
+
+
+      <figure id="test-mouse-daemon">
+	<title>Test the Mouse Daemon</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mouse6" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Move the mouse around the screen and verify the cursor
+	shown responds properly.  If it does, select
+	&gui.yes; and press <keycap>Enter</keycap>.  If
+	not, the mouse has not been configured correctly &mdash; select
+	&gui.no; and try using different configuration
+	options.</para>
+
+      <para>Select <guimenuitem>Exit</guimenuitem> with the arrow keys
+	and press <keycap>Enter</keycap> to return to continue with the
+	post-installation configuration.</para>
+    </sect2>
+
+    <sect2 id="network-services">
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>Tom</firstname>
+            <surname>Rhodes</surname>
+            <contrib>Contributed by </contrib>
+          </author>
+        </authorgroup>
+      </sect2info>
+      <title>Configure Additional Network Services</title>
+
+      <para>Configuring network services can be a daunting
+	task for new users if they lack previous
+	knowledge in this area.  Networking, including the Internet,
+	is critical to all modern operating systems including &os;;
+	as a result, it is very useful to have some understanding
+	&os;'s extensive networking capabilities.  Doing this
+	during the installation will ensure users have some
+	understanding of the various services available to them.</para>
+
+      <para>Network services are programs that accept input from
+	anywhere on the network.  Every effort is made to make sure
+	these programs will not do anything <quote>harmful</quote>.
+	Unfortunately, programmers are not perfect and through time
+	there have been cases where bugs in network services have been
+	exploited by attackers to do bad things.  It is important that
+	you only enable the network services you know that you need.  If
+	in doubt it is best if you do not enable a network service until
+	you find out that you do need it.  You can always enable it
+	later by re-running <application>sysinstall</application> or by
+	using the features provided by the
+	<filename>/etc/rc.conf</filename> file.</para>
+
+      <para>Selecting the <guimenu>Networking</guimenu> option will display
+	a menu similar to the one below:</para>
+
+      <figure id="network-configuration">
+	<title>Network Configuration Upper-level</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/net-config-menu1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The first option, <guimenuitem>Interfaces</guimenuitem>, was previously covered during
+	the <xref linkend="inst-network-dev">, thus this option can
+	safely be ignored.</para>
+
+      <para>Selecting the <guimenuitem>AMD</guimenuitem> option adds
+	support for the <acronym>BSD</acronym> automatic mount utility.
+	This is usually used in conjunction with the
+	<acronym>NFS</acronym> protocol (see below)
+	for automatically mounting remote file systems.
+	No special configuration is required here.</para>
+
+      <para>Next in line is the <guimenuitem>AMD Flags</guimenuitem>
+	option.  When selected, a menu will pop up for you
+	to enter specific <acronym>AMD</acronym> flags.
+	The menu already contains a set of default options:</para>
+
+      <screen>-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map</screen>
+
+      <para>The <option>-a</option> option sets the default mount
+	location which is specified here as
+	<filename>/.amd_mnt</filename>.  The <option>-l</option>
+	option specifies the default <filename>log</filename> file;
+	however, when <literal>syslogd</literal> is used all log
+	activity will be sent to the system log daemon.  The
+	<filename class="directory">/host</filename> directory is used
+	to mount an exported file system from a remote
+	host, while <filename class="directory">/net</filename>
+	directory is used to mount an exported file system from an
+	<acronym>IP</acronym> address.  The
+	<filename>/etc/amd.map</filename> file defines the default
+	options for <acronym>AMD</acronym> exports.</para>
+
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
+      <para>The <guimenuitem>Anon FTP</guimenuitem> option permits anonymous
+	<acronym>FTP</acronym> connections.  Select this option to
+	make this machine an anonymous <acronym>FTP</acronym> server.
+	Be aware of the security risks involved with this option.
+	Another menu will be displayed to explain the security risks
+	and configuration in depth.</para>
+
+      <para>The <guimenuitem>Gateway</guimenuitem> configuration menu will set
+	the machine up to be a gateway as explained previously.  This
+	can be used to unset the <guimenuitem>Gateway</guimenuitem> option if you accidentally
+	selected it during the installation process.</para>
+
+      <para>The <guimenuitem>Inetd</guimenuitem> option can be used to configure
+	or completely disable the &man.inetd.8; daemon as discussed
+	above.</para>
+
+      <para>The <guimenuitem>Mail</guimenuitem> option is used to configure the system's
+	default <acronym>MTA</acronym> or Mail Transfer Agent.
+	Selecting this option will bring up the following menu:</para>
+
+      <figure id="mta-selection">
+	<title>Select a default MTA</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mta-main" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Here you are offered a choice as to which
+	<acronym>MTA</acronym> to install
+	and set as the default.  An <acronym>MTA</acronym> is nothing
+	more than a mail server which delivers email to users on the
+	system or the Internet.</para>
+
+      <para>Selecting <guimenuitem>Sendmail</guimenuitem> will install
+	the popular <application>sendmail</application> server which
+	is the &os; default.  The <guimenuitem>Sendmail local</guimenuitem> option
+	will set <application>sendmail</application> to be the default
+	<acronym>MTA</acronym>, but disable its ability to receive
+	incoming email from the Internet.  The other options here,
+	<guimenuitem>Postfix</guimenuitem> and
+	<guimenuitem>Exim</guimenuitem> act similar to
+	<guimenuitem>Sendmail</guimenuitem>.  They both deliver
+	email; however, some users prefer these alternatives to the
+	<application>sendmail</application>
+	<acronym>MTA</acronym>.</para>
+
+      <para>After selecting an <acronym>MTA</acronym>, or choosing
+	not to select an MTA, the network configuration menu will appear
+	with the next option being <guimenuitem>NFS client</guimenuitem>.</para>
+
+      <para>The <guimenuitem>NFS client</guimenuitem> option will
+	configure the system to communicate with a server via
+	<acronym>NFS</acronym>.  An <acronym>NFS</acronym> server
+	makes file systems available to other machines on the
+	network via the <acronym>NFS</acronym> protocol.  If this is
+	a stand alone machine, this option can remain unselected.
+	The system may require more configuration later; see
+	<xref linkend="network-nfs"> for more
+	information about client and server configuration.</para>
+
+      <para>Below that option is the <guimenuitem>NFS server</guimenuitem>
+	option, permitting you to set the system up as an
+	<acronym>NFS</acronym> server.  This adds the required
+	information to start up the <acronym>RPC</acronym> remote
+	procedure call services.  <acronym>RPC</acronym> is used to
+	coordinate connections between hosts and programs.</para>
+
+      <para>Next in line is the <guimenuitem>Ntpdate</guimenuitem> option,
+	which deals with time synchronization.  When selected, a menu
+	like the one below shows up:</para>
+
+      <figure id="Ntpdate-config">
+	<title>Ntpdate Configuration</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/ntp-config" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>From this menu, select the server which is the closest
+	to your location.  Selecting a close one will make the time
+	synchronization more accurate as a server further from your
+	location may have more connection latency.</para>
+
+      <para>The next option is the <acronym>PCNFSD</acronym> selection.
+	This option will install the
+	<filename role="package">net/pcnfsd</filename> package from
+	the Ports Collection.  This is a useful utility which provides
+	<acronym>NFS</acronym> authentication services for systems which
+	are unable to provide their own, such as Microsoft's
+	&ms-dos; operating system.</para>
+
+      <para>Now you must scroll down a bit to see the other
+	options:</para>
+
+      <figure id="Network-configuration-cont">
+	<title>Network Configuration Lower-level</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/net-config-menu2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The &man.rpcbind.8;, &man.rpc.statd.8;, and
+	&man.rpc.lockd.8; utilities are all used for Remote Procedure
+	Calls (<acronym>RPC</acronym>).
+	The <command>rpcbind</command> utility manages communication
+	between <acronym>NFS</acronym> servers and clients, and is
+	required for <acronym>NFS</acronym> servers to operate
+	correctly.  The <application>rpc.statd</application> daemon interacts
+	with the <application>rpc.statd</application> daemon on other hosts to
+	provide status monitoring.  The reported status is usually held
+	in the <filename>/var/db/statd.status</filename> file.  The
+	next option listed here is the <guimenuitem>rpc.lockd</guimenuitem>
+	option, which, when selected, will provide file locking
+	services.  This is usually used with
+	<application>rpc.statd</application> to monitor what hosts are
+	requesting locks and how frequently they request them.
+	While these last two options are marvelous for debugging, they
+	are not required for <acronym>NFS</acronym> servers and clients
+	to operate correctly.</para>
+
+      <para>As you progress down the list the next item here is
+	<guimenuitem>Routed</guimenuitem>, which is the routing daemon.  The
+	&man.routed.8; utility manages network routing tables,
+	discovers multicast routers, and supplies a copy of the routing
+	tables to any physically connected host on the network upon
+	request.  This is mainly used for machines which act as a
+	gateway for the local network.  When selected, a menu will be
+	presented requesting the default location of the utility.
+	The default location is already defined for you and can be
+	selected with the <keycap>Enter</keycap> key.  You will then
+	be presented with yet another menu, this time asking for the
+	flags you wish to pass on to <application>routed</application>.  The
+	default is <option>-q</option> and it should already appear
+	on the screen.</para>
+
+      <para>Next in line is the <guimenuitem>Rwhod</guimenuitem> option which,
+	when selected, will start the &man.rwhod.8; daemon
+	during system initialization.  The <command>rwhod</command>
+	utility broadcasts system messages across the network
+	periodically, or collects them when in <quote>consumer</quote>
+	mode.  More information can be found in the &man.ruptime.1; and
+	&man.rwho.1; manual pages.</para>
+
+      <para>The next to the last option in the list is for the
+	&man.sshd.8; daemon.  This is the secure shell server for
+	<application>OpenSSH</application> and it is highly recommended
+	over the standard <application>telnet</application> and
+	<acronym>FTP</acronym> servers.  The <application>sshd</application>
+	server is used to create a secure connection from one host to
+	another by using encrypted connections.</para>
+
+      <para>Finally there is the <guimenuitem>TCP Extensions</guimenuitem>
+	option.  This enables the <acronym>TCP</acronym> Extensions
+	defined in <acronym>RFC</acronym>&nbsp;1323 and
+	<acronym>RFC</acronym>&nbsp;1644.  While on many hosts this can
+	speed up connections, it can also cause some connections to be
+	dropped.  It is not recommended for servers, but may be
+	beneficial for stand alone machines.</para>
+
+      <para>Now that you have configured the network services, you can
+	scroll up to the very top item which is <guimenuitem>Exit</guimenuitem>
+	and continue on to the next configuration section.</para>
+
+    </sect2>
+
+    <sect2 id="x-server">
+      <title>Configure X Server</title>
+
+      <note>
+	<para>As of &os;&nbsp;5.3-RELEASE, the X server configuration
+	  facility has been removed from
+	  <application>sysinstall</application>, you have to install
+	  and configure the X server after the installation of &os;.
+	  More information regarding the installation and the
+	  configuration of a X server can be found in <xref
+	  linkend="x11">.  You can skip this section if you are not
+	  installing a &os; version prior to 5.3-RELEASE.</para>
+      </note>
+
+      <para>In order to use a graphical user interface such as 
+	<application>KDE</application>, <application>GNOME</application>,
+	or others, the X server will need to be configured.</para>
+
+      <note>
+	<para>In order to run <application>&xfree86;</application> as a
+	  non <username>root</username> user you will need to
+	  have <filename role="package">x11/wrapper</filename> installed.
+	  This is installed by default beginning with FreeBSD 4.7.  For
+	  earlier versions this can be added
+	  from the Package Selection menu.</para>
+      </note>
+
+      <para>To see whether your video card is supported, check the
+	<ulink url="http://www.xfree86.org/">&xfree86;</ulink> web site.</para>
+
+      <screen>                      User Confirmation Requested 
+        Would you like to configure your X server at this time?
+
+                            [ Yes ]   No</screen>
+
+      <warning>
+	<para>It is necessary to know your monitor specifications and
+	  video card information.  Equipment damage can occur if settings
+	  are incorrect.  If you do not have this information, select
+	  &gui.no; and perform the configuration
+	  after installation when you have the information using 
+	  <command>sysinstall</command> (<command>/stand/sysinstall</command>
+	  in &os; versions older than 5.2), selecting
+	  <guimenuitem>Configure</guimenuitem> and then 
+	  <guimenuitem>XFree86</guimenuitem>.  Improper configuration
+	  of the X server at this time can leave the machine in a
+	  frozen state.  It is often advised to configure the X server
+	  once the installation has completed.
+	</para>
+      </warning>
+
+      <para>If you have graphics card and monitor information, select
+	&gui.yes; and press <keycap>Enter</keycap>
+	to proceed with configuring the X server.</para>
+
+      <figure id="xserver2">
+	<title>Select Configuration Method Menu</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/xf86setup" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>There are several ways to configure the X server.
+	Use the arrow keys to select one of the methods  and press
+	<keycap>Enter</keycap>.  Be sure to read all instructions
+	carefully.</para>
+
+      <para>The <application>xf86cfg</application> and 
+	<application>xf86cfg -textmode</application> methods may make the screen
+	go dark and take a few seconds to start.  Be patient.</para>
+
+
+      <para>The following will illustrate the use of the
+	<application>xf86config</application> configuration tool.  The
+	configuration choices you make will depend on the hardware in the
+	system so your choices will probably be different than those
+	shown:</para>
+
+      <screen>                                Message
+ You have configured and been running the mouse daemon. 
+ Choose "/dev/sysmouse" as the mouse port and "SysMouse" or
+ "MouseSystems" as the mouse protocol in the X configuration utility. 
+
+                                 [ OK ]
+
+                      [ Press enter to continue ]</screen>
+
+      <para>This indicates that the mouse daemon previously configured has been
+	detected.
+	Press <keycap>Enter</keycap> to continue.</para>
+
+      <para>Starting <application>xf86config</application> will display
+	a brief introduction:</para>
+
+      <screen>This program will create a basic XF86Config file, based on menu selections you
+make.
+
+The XF86Config file usually resides in /usr/X11R6/etc/X11 or /etc/X11. A sample
+XF86Config file is supplied with XFree86; it is configured for a standard
+VGA card and monitor with 640x480 resolution. This program will ask for a
+pathname when it is ready to write the file.
+
+You can either take the sample XF86Config as a base and edit it for your
+configuration, or let this program produce a base XF86Config file for your
+configuration and fine-tune it.
+
+Before continuing with this program, make sure you know what video card
+you have, and preferably also the chipset it uses and the amount of video
+memory on your video card. SuperProbe may be able to help with this.
+
+Press enter to continue, or ctrl-c to abort.</screen>
+
+      <para>Pressing <keycap>Enter</keycap> will start the mouse
+	configuration.  Be sure to follow the instructions and use
+	<quote>Mouse Systems</quote> as the mouse protocol and
+	<filename>/dev/sysmouse</filename> as the mouse port even if
+	using a PS/2 mouse is shown as an illustration.</para>
+
+      <screen>First specify a mouse protocol type. Choose one from the following list:
+
+ 1.  Microsoft compatible (2-button protocol)
+ 2.  Mouse Systems (3-button protocol) &amp; 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/X11/XF86Config</filename> as the location
+	for saving the configuration.</para>
+
+      <screen>I am going to write the XF86Config file now. Make sure you don't accidently
+overwrite a previously configured one.
+
+Shall I write it to /etc/X11/XF86Config? y</screen>
+
+      <para>If the configuration fails, you can try the configuration again
+	by selecting &gui.yes; when the following
+	message appears:</para>
+
+      <screen>          User Confirmation Requested
+The XFree86 configuration process seems to have
+failed.  Would you like to try again?
+
+             [ Yes ]         No</screen>
+
+      <para>If you have trouble configuring <application>&xfree86;</application>, select
+	&gui.no; and press <keycap>Enter</keycap>
+	and continue with the installation process.  After installation
+	you can use <command>xf86cfg -textmode</command> or
+	<command>xf86config</command> to access the command line
+	configuration utilities as <username>root</username>.  There is
+	an additional method for configuring <application>&xfree86;</application> described in
+	<xref linkend="x11">.   If you choose not to configure
+	<application>&xfree86;</application> at this time the next menu will be for package
+	selection.</para>
+
+      <para>The default setting which allows the server to be killed
+	is the hotkey sequence <keycombo action='simul'>
+	<keycap>Ctrl</keycap><keycap>Alt</keycap>
+	<keycap>Backspace</keycap></keycombo>.  This
+	can be executed if something is wrong with the server settings and
+	prevent hardware damage.</para>
+
+      <para>The default setting that allows video mode switching will
+	permit changing of the mode while running X with the hotkey
+	sequence
+	<keycombo action='simul'>
+	  <keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>+</keycap>
+	</keycombo> or
+	<keycombo action='simul'>
+	  <keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>-</keycap>
+	</keycombo>.   
+      </para>
+
+      <para>After you have <application>&xfree86;</application>
+	running, the display can be adjusted for height, width,
+	or centering by using <application>xvidtune</application>.</para>
+
+      <para>There are warnings that improper settings can
+	damage your equipment.  Heed them.  If in doubt, do not do
+	it.  Instead, use the monitor controls to adjust the display for
+	X Window.  There may be some display differences when switching
+	back to text mode, but it is better than damaging equipment.</para>
+
+      <para>Read the &man.xvidtune.1; manual page before making
+	any adjustments.</para>
+
+      <para>Following a successful <application>&xfree86;</application> configuration, it will proceed
+	to the selection of a default desktop.</para>
+    </sect2>
+
+    <sect2 id="default-desktop">
+      <title>Select Default X Desktop</title>
+
+      <note>
+	<para>As of &os;&nbsp;5.3-RELEASE, the X desktop selection
+	  facility has been removed from
+	  <application>sysinstall</application>, you have to configure
+	  the X desktop after the installation of &os;.  More
+	  information regarding the installation and the configuration
+	  of a X desktop can be found in <xref linkend="x11">.  You
+	  can skip this section if you are not installing a &os;
+	  version prior to 5.3-RELEASE.</para>
+      </note>
+
+      <para>There are a variety of window managers available.  They range
+	from very basic environments to full desktop environments with a
+	large suite of software.  Some require only minimal disk space and
+	low memory while others with more features require much more.  The
+	best way to determine which is most suitable for you is to try a few
+	different ones.  Those are available from the Ports Collection or as
+	packages and can be added after installation.</para>
+
+      <para>You can select one of the popular desktops to be installed
+	and configured as the default desktop.  This will allow you
+	to start it right after installation.</para>
+
+      <figure id="x-desktop">
+	<title>Select Default Desktop</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/desktop" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Use the arrow keys to select a desktop and press
+	<keycap>Enter</keycap>.  Installation of the selected desktop will
+	proceed.</para>
+    </sect2>
+
+    <sect2 id="packages">
+    <title>Install Packages</title>
+
+      <para>Packages are pre-compiled binaries and are a convenient
+	way to install software.</para>
+
+      <para>Installation of one package is shown for purposes of
+	illustration.  Additional packages can also be added at this
+	time if desired.  After installation
+	<command>sysinstall</command> (<command>/stand/sysinstall</command>
+	in &os; versions older than 5.2) can be used to add additional
+	packages.</para>
+
+      <screen>                     User Confirmation Requested
+ The FreeBSD package collection is a collection of hundreds of
+ ready-to-run applications, from text editors to games to WEB servers
+ and more. Would you like to browse the collection now? 
+
+                            [ Yes ]   No</screen>
+
+      <para>Selecting &gui.yes; and pressing
+	<keycap>Enter</keycap> will be
+	followed by the Package Selection screens:</para>
+
+      <figure id="package-category">
+	<title>Select Package Category</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/pkg-cat" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Only packages on the current installation media are
+	available for installation at any given time.</para>
+
+      <para>All packages available will be displayed if 
+	<guimenuitem>All</guimenuitem> is selected or you can select a
+	particular category.  Highlight your selection with the arrow
+	keys and press <keycap>Enter</keycap>.</para>
+
+      <para>A menu will display showing all the packages available for
+	the selection made:</para>
+
+      <figure id="package-select">
+	<title>Select Packages</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/pkg-sel" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The <application>bash</application> shell is shown selected.
+	Select as many as desired by highlighting the package and pressing the
+	<keycap>Space</keycap> key.  A short description of each package will
+	appear in the lower left corner of the screen.</para>
+
+      <para>Pressing the <keycap>Tab</keycap> key will toggle between the last
+	selected package, &gui.ok;, and &gui.cancel;.</para>
+
+      <para>When you have finished marking the packages for installation,
+	press <keycap>Tab</keycap> once to toggle to the &gui.ok; and press
+	<keycap>Enter</keycap> to return to the Package Selection menu.</para>
+
+      <para>The left and right arrow keys will also toggle between &gui.ok;
+	and &gui.cancel;.  This method can also be used to select &gui.ok; and
+	press <keycap>Enter</keycap> to return to the Package Selection
+	menu.</para>
+
+      <figure id="package-install">
+	<title>Install Packages</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/pkg-install" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Use the <keycap>Tab</keycap> and arrow keys to select <guibutton>[&nbsp;Install&nbsp;]</guibutton>
+	and press <keycap>Enter</keycap>.  You will then need to confirm
+	that you want to install the packages:</para>
+
+      <figure id="package-install-confirm">
+	<title>Confirm Package Installation</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/pkg-confirm" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Selecting &gui.ok; and pressing <keycap>Enter</keycap> will start
+	the package installation.  Installing messages will appear until
+	completed.  Make note if there are any error messages.</para>
+
+      <para>The final configuration continues after packages are
+	installed.  If you end up not selecting any packages, and wish
+	to return to the final configuration, select
+	<guibutton>Install</guibutton> anyways.</para>
+    </sect2>
+
+    <sect2 id="addusers">
+      <title>Add Users/Groups</title>
+
+      <para>You should add at least one user during the installation so
+	that you can use the system without being logged in as
+	<username>root</username>.  The root partition is generally small
+	and running applications as <username>root</username> can quickly
+	fill it.  A bigger danger is noted below:</para>
+
+      <screen>                     User Confirmation Requested
+ Would you like to add any initial user accounts to the system? Adding
+ at least one account for yourself at this stage is suggested since
+ working as the "root" user is dangerous (it is easy to do things which
+ adversely affect the entire system). 
+
+                            [ Yes ]   No</screen>
+
+      <para>Select &gui.yes; and press
+	<keycap>Enter</keycap> to continue with adding a user.</para>
+
+      <figure id="add-user2">
+	<title>Select User</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/adduser1" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Select <guimenuitem>User</guimenuitem> with the arrow keys
+	and press <keycap>Enter</keycap>.</para>
+
+      <figure id="add-user3">
+	<title>Add User Information</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/adduser2" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>The following descriptions will appear in the lower part of
+	the screen as the items are selected with <keycap>Tab</keycap>
+	to assist with entering the required information:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Login ID</term>
+
+	  <listitem>
+	    <para>The login name of the new user (mandatory).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>UID</term>
+	
+	  <listitem>
+	    <para>The numerical ID for this user (leave blank for
+	      automatic choice).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Group</term>
+
+	  <listitem>
+	    <para>The login group name for this user (leave blank for
+	      automatic choice).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Password</term>
+
+	  <listitem>
+	    <para>The password for this user (enter this field with
+	      care!).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Full name</term>
+
+	  <listitem>
+	    <para>The user's full name (comment).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Member groups</term>
+
+	  <listitem>
+	    <para>The groups this user belongs to (i.e. gets access
+	      rights for).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Home directory</term>
+
+	  <listitem>
+	    <para>The user's home directory (leave blank for
+	      default).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Login shell</term>
+	  <listitem>
+	    <para>The user's login shell (leave blank for
+	      default, e.g. <filename>/bin/sh</filename>).</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>The login shell was changed from <filename>/bin/sh</filename> to
+	<filename>/usr/local/bin/bash</filename> to use the
+	<application>bash</application> shell that was previously installed as
+	a package.  Do not try to use a shell that does not exist or you will
+	not be able to login.  The most common shell used in the
+	BSD-world is the C shell, which can be indicated as
+	<filename>/bin/tcsh</filename>.</para>
+
+      <para>The user was also added to the <groupname>wheel</groupname> group
+	to be able to become a superuser with <username>root</username>
+	privileges.</para>
+
+      <para>When you are satisfied, press &gui.ok; and
+	the User and Group Management menu will redisplay:</para>
+
+      <figure id="add-user4">
+	<title>Exit User and Group Management</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/adduser3" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Groups can also be added at this time if specific needs
+	are known.  Otherwise, this may be accessed through using
+	<command>sysinstall</command> (<command>/stand/sysinstall</command>
+	in &os; versions older than 5.2) after installation is
+	completed.</para>
+
+      <para>When you are finished adding users, select 
+	<guimenuitem>Exit</guimenuitem> with the arrow keys and press
+	<keycap>Enter</keycap> to continue the installation.</para>
+    </sect2>
+
+    <sect2 id="rootpass">
+      <title>Set the <username>root</username> Password</title>
+
+      <screen>                        Message
+ Now you must set the system manager's password.  
+ This is the password you'll use to log in as "root". 
+
+                         [ OK ] 
+
+               [ Press enter to continue ]</screen>
+
+      <para>Press <keycap>Enter</keycap> to set the <username>root</username>
+	password.</para>
+
+      <para>The password will need to be typed in twice correctly.  Needless to
+	say, make sure you have a way of finding the password if you
+	forget.  Notice that the password you type in is not echoed, nor
+	are asterisks displayed.</para>
+
+      <screen>Changing local password for root. 
+New password : 
+Retype new password :</screen>
+
+      <para>The installation will continue after the password is
+	successfully entered.</para>
+    </sect2>
+
+    <sect2 id="exit-inst">
+      <title>Exiting Install</title>
+
+      <para>If you need to configure additional network devices or
+	any other configuration, you can do it at this point or
+	after installation with <command>sysinstall</command>
+	(<command>/stand/sysinstall</command> in &os; versions older
+	than 5.2).</para>
+
+      <screen>                     User Confirmation Requested
+ Visit the general configuration menu for a chance to set any last
+ options? 
+
+                              Yes   [ No ]</screen>
+
+      <para>Select &gui.no; with the arrow keys
+	and press <keycap>Enter</keycap> to return to the Main
+	Installation Menu.</para>
+
+      <figure id="final-main">
+	<title>Exit Install</title>
+
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="install/mainexit" format="PNG">
+	  </imageobject>
+	</mediaobject>
+      </figure>
+
+      <para>Select <guibutton>[X Exit Install]</guibutton> with the arrow
+	keys and press <keycap>Enter</keycap>.  You will be asked to
+	confirm exiting the installation:</para>
+
+      <screen>                     User Confirmation Requested
+ Are you sure you wish to exit? The system will reboot (be sure to  
+ remove any floppies from the drives). 
+
+                            [ Yes ]   No</screen>
+
+      <para>Select &gui.yes; and remove the floppy if
+	booting from the floppy.  The CDROM drive is locked until the machine
+	starts to reboot.  The CDROM drive is then unlocked and the disk can
+	be removed from drive (quickly).</para>
+
+      <para>The system will reboot so watch for any error messages that
+	may appear.</para>
+    </sect2>
+
+    <sect2 id="freebsdboot">
+      <title>FreeBSD Bootup</title>
+
+      <sect3 id="freebsdboot-i386">
+        <title>FreeBSD Bootup on the &i386;</title>
+
+      <para>If everything went well, you will see messages scroll
+	off the screen and you will arrive at a login prompt.  You can view
+	the content of the messages by pressing <keycap>Scroll-Lock</keycap>
+	and using <keycap>PgUp</keycap> and <keycap>PgDn</keycap>.
+	Pressing <keycap>Scroll-Lock</keycap> again will return
+	to the prompt.</para>
+
+      <para>The entire message may not display (buffer limitation) but
+	it can be viewed from the command line after logging in by typing
+	<command>dmesg</command> at the prompt.</para>
+
+      <para>Login using the username/password you set during installation
+	(<username>rpratt</username>, in this example).  Avoid logging in as
+	<username>root</username> except when necessary.</para>
+
+      <para>Typical boot messages (version information omitted):</para>
+
+<screen>Copyright (c) 1992-2002 The FreeBSD Project. 
+Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
+        The Regents of the University of California. All rights reserved. 
+
+Timecounter "i8254"  frequency 1193182 Hz
+CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU)
+  Origin = "AuthenticAMD"  Id = 0x580  Stepping = 0
+  Features=0x8001bf&lt;FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX&gt; 
+  AMD Features=0x80000800&lt;SYSCALL,3DNow!&gt; 
+real memory  = 268435456 (262144K bytes) 
+config&gt; di sn0 
+config&gt; di lnc0 
+config&gt; di le0 
+config&gt; di ie0 
+config&gt; di fe0 
+config&gt; di cs0 
+config&gt; di bt0  
+config&gt; di aic0 
+config&gt; di aha0 
+config&gt; di adv0 
+config&gt; q 
+avail memory = 256311296 (250304K bytes)
+Preloaded elf kernel "kernel" at 0xc0491000. 
+Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c. 
+md0: Malloc disk 
+Using $PIR table, 4 entries at 0xc00fde60
+npx0: &lt;math processor&gt; on motherboard 
+npx0: INT 16 interface 
+pcib0: &lt;Host to PCI bridge&gt; on motherboard 
+pci0: &lt;PCI bus&gt; on pcib0 
+pcib1: &lt;VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge&gt; at device 1.0 on pci0 
+pci1: &lt;PCI bus&gt; on pcib1 
+pci1: &lt;Matrox MGA G200 AGP graphics accelerator&gt; at 0.0 irq 11 
+isab0: &lt;VIA 82C586 PCI-ISA bridge&gt; at device 7.0 on pci0 
+isa0: &lt;ISA bus&gt; on isab0 
+atapci0: &lt;VIA 82C586 ATA33 controller&gt; port 0xe000-0xe00f at device 7.1 on pci0 
+ata0: at 0x1f0 irq 14 on atapci0 
+ata1: at 0x170 irq 15 on atapci0 
+uhci0: &lt;VIA 83C572 USB controller&gt; port 0xe400-0xe41f irq 10 at device 7.2 on pci0 
+usb0: &lt;VIA 83C572 USB controller&gt; on uhci0 
+usb0: USB revision 1.0 
+uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1 
+uhub0: 2 ports with 2 removable, self powered 
+chip1: &lt;VIA 82C586B ACPI interface&gt; at device 7.3 on pci0 
+ed0: &lt;NE2000 PCI Ethernet (RealTek 8029)&gt; port 0xe800-0xe81f irq 9 at
+device 10.0 on pci0 
+ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit) 
+isa0: too many dependant configs (8) 
+isa0: unexpected small tag 14 
+fdc0: &lt;NEC 72065B or clone&gt; at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0
+fdc0: FIFO enabled, 8 bytes threshold 
+fd0: &lt;1440-KB 3.5" drive&gt; on fdc0 drive 0 
+atkbdc0: &lt;keyboard controller (i8042)&gt; at port 0x60-0x64 on isa0 
+atkbd0: &lt;AT Keyboard&gt; flags 0x1 irq 1 on atkbdc0 
+kbd0 at atkbd0 
+psm0: &lt;PS/2 Mouse&gt; irq 12 on atkbdc0 
+psm0: model Generic PS/2 mouse, device ID 0 
+vga0: &lt;Generic ISA VGA&gt; at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0
+sc0: &lt;System console&gt; at flags 0x1 on isa0 
+sc0: VGA &lt;16 virtual consoles, flags=0x300&gt; 
+sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 
+sio0: type 16550A 
+sio1 at port 0x2f8-0x2ff irq 3 on isa0 
+sio1: type 16550A 
+ppc0: &lt;Parallel port&gt; at port 0x378-0x37f irq 7 on isa0 
+ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode 
+ppc0: FIFO with 16/16/15 bytes threshold 
+ppbus0: IEEE1284 device found /NIBBLE
+Probing for PnP devices on ppbus0: 
+plip0: &lt;PLIP network interface&gt; on ppbus0 
+lpt0: &lt;Printer&gt; on ppbus0 
+lpt0: Interrupt-driven port 
+ppi0: &lt;Parallel I/O&gt; on ppbus0
+ad0: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata0-master using UDMA33 
+ad2: 8063MB &lt;IBM-DHEA-38451&gt; [16383/16/63] at ata1-master using UDMA33 
+acd0: CDROM &lt;DELTA OTC-H101/ST3 F/W by OIPD&gt; at ata0-slave using PIO4 
+Mounting root from ufs:/dev/ad0s1a 
+swapon: adding /dev/ad0s1b as swap device 
+Automatic boot in progress... 
+/dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS 
+/dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation)
+/dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS 
+/dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation)
+/dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS
+/dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation)
+/dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS 
+/dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation)
+Doing initial network setup: hostname. 
+ed0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
+        inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
+        inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1
+        ether 52:54:05:de:73:1b
+lo0: flags=8049&lt;UP,LOOPBACK,RUNNING,MULTICAST&gt; mtu 16384 
+        inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8 
+        inet6 ::1 prefixlen 128 
+        inet 127.0.0.1 netmask 0xff000000 
+Additional routing options: IP gateway=YES TCP keepalive=YES
+routing daemons:. 
+additional daemons: syslogd. 
+Doing additional network setup:. 
+Starting final network daemons: creating ssh RSA host key 
+Generating public/private rsa1 key pair.
+Your identification has been saved in /etc/ssh/ssh_host_key. 
+Your public key has been saved in /etc/ssh/ssh_host_key.pub. 
+The key fingerprint is: 
+cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com
+ creating ssh DSA host key 
+Generating public/private dsa key pair.
+Your identification has been saved in /etc/ssh/ssh_host_dsa_key. 
+Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. 
+The key fingerprint is: 
+f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com.
+setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib
+/usr/local/lib 
+a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout 
+starting standard daemons: inetd cron sshd usbd sendmail.
+Initial rc.i386 initialization:. 
+rc.i386 configuring syscons: blank_time screensaver moused. 
+Additional ABI support: linux. 
+Local package initialization:. 
+Additional TCP options:. 
+
+FreeBSD/i386 (k6-2.example.com) (ttyv0)
+
+login: rpratt 
+Password:</screen>
+
+      <para>Generating the RSA and DSA keys may take some time on slower
+	machines.  This happens only on the initial boot-up of a new
+	installation.  Subsequent boots will be faster.</para>
+
+      <para>If the X server has been configured and a Default Desktop
+	chosen, it can be started by typing <command>startx</command> at
+	the command line.</para>
+
+      </sect3>
+
+      <sect3>
+        <title>Bootup of FreeBSD on the Alpha</title>
+
+	<indexterm><primary>Alpha</primary></indexterm>
+
+        <para>Once the install procedure has finished, you will be
+          able to start FreeBSD by typing something like this to the
+          SRM prompt:</para>
+
+	<screen>&gt;&gt;&gt;<userinput>BOOT DKC0</userinput></screen>
+
+	<para>This instructs the firmware to boot the specified
+	  disk.  To make FreeBSD boot automatically in the future, use
+	  these commands:</para>
+
+	<screen><prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOT_OSFLAGS A</userinput>
+<prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOT_FILE ''</userinput>
+<prompt>&gt;&gt;&gt;</prompt> <userinput>SET BOOTDEF_DEV DKC0</userinput>
+<prompt>&gt;&gt;&gt;</prompt> <userinput>SET AUTO_ACTION BOOT</userinput></screen>
+
+	<para>The boot messages will be similar (but not identical) to
+	those produced by FreeBSD booting on the &i386;.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="shutdown">
+      <title>FreeBSD Shutdown</title>
+
+      <para>It is important to properly shutdown the operating
+	system.  Do not just turn off power.  First, become a superuser by
+	typing <command>su</command> at the command line and entering the
+	<username>root</username> password.  This will work only if the user
+	is a member of the <groupname>wheel</groupname> group.
+	Otherwise, login as <username>root</username> and use
+	<command>shutdown -h now</command>.</para>
+
+      <screen>The operating system has halted. 
+Please press any key to reboot.</screen>
+
+      <para>It is safe to turn off the power after the shutdown command
+	has been issued and the message <quote>Please press any key to reboot</quote>
+	appears.  If any key is pressed instead of turning off the power
+	switch, the system will reboot.</para>
+
+      <para>You could also use the
+        <keycombo action="simul">
+	  <keycap>Ctrl</keycap>
+	  <keycap>Alt</keycap>
+	  <keycap>Del</keycap>
+	</keycombo>
+	key combination to reboot the system, however this is not recommended
+	during normal operation.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-supported-hardware">
+    <title>Supported Hardware</title>
+
+    <indexterm><primary>hardware</primary></indexterm>
+    <para>FreeBSD currently runs on a wide variety of ISA, VLB, EISA, and PCI
+      bus-based PCs with Intel, AMD, Cyrix, or NexGen <quote>x86</quote>
+      processors, as well as a number of machines based on the Compaq Alpha
+      processor.  Support for generic IDE or ESDI drive configurations,
+      various SCSI controllers, PCMCIA cards, USB devices, and network and
+      serial cards is also provided.  FreeBSD also supports IBM's microchannel
+      (MCA) bus.</para>
+
+    <para>A list of supported hardware is provided with each FreeBSD release
+      in the FreeBSD Hardware Notes.  This document can usually be found in a
+      file named <filename>HARDWARE.TXT</filename>, in the top-level directory
+      of a CDROM or FTP distribution or in
+      <application>sysinstall</application>'s documentation menu.  It lists,
+      for a given architecture, what hardware devices are known to be
+      supported by each release of FreeBSD.  Copies of the supported
+      hardware list for various releases and architectures can also be
+      found on the <ulink
+      url="http://www.FreeBSD.org/releases/index.html">Release
+      Information</ulink> page of the FreeBSD Web site.</para>
+  </sect1>
+
+  <sect1 id="install-trouble">
+    <title>Troubleshooting</title>
+
+    <indexterm>
+      <primary>installation</primary>
+      <secondary>troubleshooting</secondary>
+    </indexterm>
+    <para>The following section covers basic installation troubleshooting,
+      such as common problems people have reported.  There are also a few
+      questions and answers for people wishing to dual-boot FreeBSD with
+      &ms-dos;.</para>
+
+    <sect2>
+      <title>What to Do If Something Goes Wrong</title>
+
+      <para>Due to various limitations of the PC architecture, it is
+        impossible for probing to be 100% reliable, however, there are a
+        few things you can do if it fails.</para>
+
+      <para>Check the Hardware Notes document for your version of
+        FreeBSD to make sure your hardware is
+        supported.</para>
+
+      <para>If your hardware is supported and you still experience
+        lock-ups or other problems, reset your computer, and when the
+        visual kernel configuration option is given, choose it.  This will
+        allow you to go through your hardware and supply information to the
+        system about it.  The kernel on the boot disks is configured
+        assuming that most hardware devices are in their factory default
+        configuration in terms of IRQs, IO addresses, and DMA channels.  If
+        your hardware has been reconfigured, you will most likely need to
+        use the configuration editor to tell FreeBSD where to find
+        things.</para>
+
+      <para>It is also possible that a probe for a device not present will
+        cause a later probe for another device that is present to fail.  In
+        that case, the probes for the conflicting driver(s) should be
+        disabled.</para>
+
+      <note>
+        <para>Some installation problems can be avoided or alleviated
+          by updating the firmware on various hardware components, most notably
+          the motherboard.  The motherboard firmware may also be referred to
+          as <acronym>BIOS</acronym> and most of the motherboard or computer
+          manufactures have a website where the upgrades and upgrade information
+          may be located.</para>
+
+        <para>Most manufacturers strongly advise against upgrading the motherboard
+          <acronym>BIOS</acronym> unless there is a good reason for doing so, which
+          could possibly be a critical update of sorts.  The upgrade process
+          <emphasis>can</emphasis> go wrong, causing permanent damage to the
+          <acronym>BIOS</acronym> chip.</para>
+        </note>
+
+      <warning>
+        <para>Do not disable any drivers you will need during the
+          installation, such as your screen (<devicename>sc0</devicename>).
+	  If the installation wedges or fails mysteriously after leaving
+	  the configuration editor, you have probably removed or changed
+	  something you should not have.  Reboot and try again.</para>
+      </warning>
+
+      <para>In configuration mode, you can:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>List the device drivers installed in the kernel.</para>
+        </listitem>
+
+        <listitem>
+          <para>Disable device drivers for hardware that is not present in
+	    your system.</para>
+        </listitem>
+
+        <listitem>
+          <para>Change IRQs, DRQs, and IO port addresses used by a device
+	    driver.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>After adjusting the kernel to match your hardware
+        configuration, type <command>Q</command> to boot with the new
+        settings.  Once the installation has completed, any changes you
+        made in the configuration mode will be permanent so you do not have
+        to reconfigure every time you boot.  It is still highly likely that
+        you will eventually want to build a <link
+        linkend="kernelconfig">custom kernel</link>.</para>
+    </sect2>
+    
+    <sect2>
+      <title>Dealing with Existing &ms-dos; Partitions</title>
+
+      <indexterm><primary>DOS</primary></indexterm>
+      <para>Many users wish to install &os; on <acronym>PC</acronym>s inhabited by
+	&microsoft; based operating systems.  For those instances, &os; has a
+	utility known as <application>FIPS</application>.  This utility can be found
+	in the <filename>tools</filename> directory on the install CD-ROM, or downloaded
+	from one of various <link linkend="mirrors">&os; mirrors</link>.</para>
+
+      <para>The <application>FIPS</application> utility allows you to split an
+	existing &ms-dos; partition into two pieces, preserving the original
+	partition and allowing you to install onto the second free piece.
+	You first need to defragment your &ms-dos; partition using the &windows;
+	<application>Disk Defragmenter</application> utility (go into Explorer, right-click on
+	the hard drive, and choose to defrag your hard drive), or use
+	<application>Norton Disk Tools</application>.  Now you can run the
+	<application>FIPS</application> utility.  It will prompt you for the rest of
+	the information, just follow the on screen instructions.  Afterwards, you can
+	reboot and install &os; on the new free slice.  See the <guimenuitem>Distributions</guimenuitem> menu
+	for an estimate of how much free space you will need for the kind of
+	installation you want.</para>
+
+      <para>There is also a very useful product from PowerQuest
+	(<ulink url="http://www.powerquest.com/">http://www.powerquest.com</ulink>) called
+	<application>&partitionmagic;</application>.  This application has far more
+	functionality than <application>FIPS</application>, and is highly recommended
+	if you plan to add/remove operating systems often.  It does cost money, so if you
+	plan to install &os; and keep it installed, <application>FIPS</application>
+	will probably be fine for you.</para>
+    </sect2>
+
+    <sect2>
+      <title>Using &ms-dos; and &windows; File Systems</title>
+
+      <para>At this time, &os; does not support file systems compressed with the
+	<application>Double Space&trade;</application> application.  Therefore the file
+	system will need to be uncompressed before &os; can access the data.  This
+	can be done by running the <application>Compression Agent</application>
+	located in the <guimenuitem>Start</guimenuitem>&gt; <guimenuitem>Programs</guimenuitem> &gt;
+	<guimenuitem>System Tools</guimenuitem> menu.</para>
+
+      <para>&os; can support &ms-dos; based file systems.  This requires you use
+	the &man.mount.msdos.8; command (in &os; 5.X, the command is &man.mount.msdosfs.8;)
+	with the required parameters.  The utilities most common usage is:</para>
+
+      <screen>&prompt.root; <userinput>mount_msdos /dev/ad0s1 /mnt</userinput></screen>
+
+      <para>In this example, the &ms-dos; file system is located on the first partition of
+	the primary hard disk.  Your situation may be different, check the output from
+	the <command>dmesg</command>, and <command>mount</command> commands.  They should
+	produce enough information to give an idea of the partition layout.</para>
+
+      <note><para>Extended &ms-dos; file systems are usually mapped after the &os;
+	partitions.  In other words, the slice number may be higher than the ones
+	&os; is using.  For instance, the first &ms-dos; partition may be
+	<filename>/dev/ad0s1</filename>, the &os; partition may be
+	<filename>/dev/ad0s2</filename>, with the extended &ms-dos; partition being
+	located on <filename>/dev/ad0s3</filename>.  To some, this can be confusing
+	at first.</para></note>
+
+      <para>NTFS partitions can also be mounted in a similar manner
+	using the &man.mount.ntfs.8; command.</para>
+    </sect2>
+
+    <sect2>
+      <title>Alpha User's Questions and Answers</title>
+
+      <indexterm><primary>Alpha</primary></indexterm>
+
+      <para>This section answers some commonly asked questions about
+        installing FreeBSD on Alpha systems.</para>
+
+      <qandaset>
+	<qandaentry>
+	  <question>
+	    <para>Can I boot from the ARC or Alpha BIOS Console?</para>
+	  </question>
+
+	  <indexterm><primary>ARC</primary></indexterm>
+	  <indexterm><primary>Alpha BIOS</primary></indexterm>
+	  <indexterm><primary>SRM</primary></indexterm>
+
+	  <answer>
+	    <para>No.  &os;, like Compaq Tru64 and VMS, will only boot
+	    from the SRM console.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>Help, I have no space!  Do I need to delete
+	    everything first?</para>
+	  </question>
+
+	  <answer>
+	    <para>Unfortunately, yes.</para>
+	  </answer>
+	</qandaentry>
+
+	<qandaentry>
+	  <question>
+	    <para>Can I mount my Compaq Tru64 or VMS filesystems?</para>
+	  </question>
+
+	  <answer>
+	    <para>No, not at this time.</para>
+	  </answer>
+	</qandaentry>
+      </qandaset>
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-advanced">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Valentino</firstname>
+	  <surname>Vaschetto</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+	<!-- May 2001 -->
+      </authorgroup>
+    </sect1info>
+
+    <title>Advanced Installation Guide</title>
+
+    <para>This section describes how to install FreeBSD in exceptional
+       cases.</para>
+
+    <sect2 id="headless-install">
+      <title>Installing FreeBSD on a System without a Monitor or
+        Keyboard</title>
+
+      <indexterm>
+        <primary>installation</primary>
+        <secondary>headless (serial console)</secondary>
+      </indexterm>
+      <indexterm><primary>serial console</primary></indexterm>
+      <para>This type of installation is called a <quote>headless
+	install</quote>, because the machine that you are trying to install
+	FreeBSD on either does not have a monitor attached to it, or does not
+	even have a VGA output.  How is this possible you ask? Using a
+        serial console.  A serial console is basically using another
+        machine to act as the main display and keyboard for a
+        system.  To do this, just follow the steps to create
+        installation floppies, explained in <xref
+        linkend="install-floppies">.</para>
+
+      <para>To modify these floppies to boot into a serial console, follow
+	these steps:</para>
+
+      <procedure>
+	<step>
+	  <title>Enabling the Boot Floppies to Boot into a Serial Console</title>
+  	    <indexterm>
+	      <primary><command>mount</command></primary>
+	    </indexterm>
+	    <para>If you were to boot into the floppies that you just
+	      made, FreeBSD would boot into its normal install mode.  We
+	      want FreeBSD to boot into a serial console for our
+	      install.  To do this, you have to mount the
+	      <filename>kern.flp</filename> floppy onto your FreeBSD
+	      system using the &man.mount.8; command.</para>
+
+            <screen>&prompt.root; <userinput>mount /dev/fd0 /mnt</userinput></screen>
+
+	    <para>Now that you have the floppy mounted, you must
+	      change into the <filename class="directory">/mnt</filename> directory:</para>
+
+	    <screen>&prompt.root; <userinput>cd /mnt</userinput></screen>
+
+	    <para>Here is where you must set the floppy to boot into a
+	      serial console.  You have to make a file called
+	      <filename>boot.config</filename> containing 
+	      <literal>/boot/loader -h</literal>.  All this does is pass a flag to the bootloader to
+	      boot into a serial console.</para>
+
+	    <screen>&prompt.root; <userinput>echo "/boot/loader -h" &gt; boot.config</userinput></screen>
+
+	    <para>Now that you have your floppy configured correctly,
+	      you must unmount the floppy using the &man.umount.8;
+	      command:</para>
+
+            <screen>&prompt.root; <userinput>cd /</userinput>
+&prompt.root; <userinput>umount /mnt</userinput></screen>
+
+	    <para>Now you can remove the floppy from the floppy
+	      drive.</para>
+	  </step>
+
+	  <step>
+	    <title>Connecting Your Null-modem Cable</title>
+
+  	    <indexterm><primary>null-modem cable</primary></indexterm>
+	    <para>You now need to connect a
+	      <link linkend="term-cables-null">null-modem cable</link> between
+	      the two machines.  Just connect the cable to the serial
+	      ports of the 2 machines.  <emphasis>A normal serial cable
+	      will not work here</emphasis>, you need a null-modem
+	      cable because it has some of the wires inside crossed
+	      over.</para>
+	  </step>
+
+	  <step>
+	    <title>Booting Up for the Install</title>
+
+	    <para>It is now time to go ahead and start the install.  Put
+	      the <filename>kern.flp</filename> floppy in the floppy
+	      drive of the machine you are doing the headless install
+	      on, and power on the machine.</para>
+	  </step>
+
+	  <step>
+	    <title>Connecting to Your Headless Machine</title>
+	    <indexterm>
+	      <primary><command>cu</command></primary>
+	    </indexterm>
+	    <para>Now you have to connect to that machine with
+	      &man.cu.1;:</para> 
+
+	    <screen>&prompt.root; <userinput>cu -l /dev/cuaa0</userinput></screen>
+	  </step>
+      </procedure>
+
+      <para>That's it! You should now be able to control the headless machine
+	through your <command>cu</command> session.  It will ask you to
+	put in the <filename>mfsroot.flp</filename>, and then it will come up
+	with a selection of what kind of terminal to use.  Select the
+	FreeBSD color console and proceed with your install!</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="install-diff-media">
+    <title>Preparing Your Own Installation Media</title>
+
+    <note>
+      <para>To prevent repetition, <quote>FreeBSD disc</quote> in this context
+	means a FreeBSD CDROM or DVD that you have purchased or produced
+	yourself.</para>
+    </note>
+
+    <para>There may be some situations in which you need to create your own
+      FreeBSD installation media and/or source.  This might be physical media,
+      such as a tape, or a source that <application>sysinstall</application>
+      can use to retrieve the files, such as a local FTP site, or an &ms-dos;
+      partition.</para>
+
+    <para>For example:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>You have many machines connected to your local network, and one
+	  FreeBSD disc.  You want to create a local FTP site using the
+	  contents of the FreeBSD disc, 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 disc, and FreeBSD does not recognize your CD/DVD
+	  drive, but &ms-dos;/&windows; does.  You want to copy the FreeBSD
+	  installation files to a DOS partition on the same computer, and
+	  then install FreeBSD using those files.</para>
+      </listitem>
+
+      <listitem>
+	<para>The computer you want to install on does not have a CD/DVD
+	  drive or a network card, but you can connect a
+	  <quote>Laplink-style</quote> serial or parallel cable to a computer
+	  that does.</para>
+      </listitem>
+
+      <listitem>
+	<para>You want to create a tape that can be used to install
+	  FreeBSD.</para>
+      </listitem>
+    </itemizedlist>
+
+    <sect2 id="install-cdrom">
+      <title>Creating an Installation CDROM</title>
+
+      <para>As part of each release, the FreeBSD project makes available two
+	CDROM images (<quote>ISO images</quote>).  These images can be written
+	(<quote>burned</quote>) to CDs if you have a CD writer, and then used
+	to install FreeBSD.  If you have a CD writer, and bandwidth is cheap,
+	then this is the easiest way to install FreeBSD.</para>
+
+      <procedure>
+	<step>
+	  <title>Download the Correct ISO Images</title>
+
+	  <para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-<replaceable>arch</replaceable>/<replaceable>version</replaceable></filename> or the closest mirror.  
+	    Substitute <replaceable>arch</replaceable> and 
+	    <replaceable>version</replaceable> as appropriate.</para>
+
+	  <para>That directory will normally contain the following images:</para>
+
+	  <table frame="none">
+	    <title>FreeBSD 4.<replaceable>X</replaceable> 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>-RELEASE-<replaceable>arch</replaceable>-miniinst.iso</filename></entry>
+		  
+		  <entry>Everything you need to install FreeBSD.</entry>
+		</row>
+
+		<row>
+		  <entry><filename><replaceable>version</replaceable>-RELEASE-<replaceable>arch</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>-RELEASE-<replaceable>arch</replaceable>-disc2.iso</filename></entry>
+
+		  <entry>A <quote>live filesystem</quote>, which is used in
+		    conjunction with the <quote>Repair</quote> facility in
+		    <application>sysinstall</application>.  A copy of the
+		    FreeBSD CVS tree.  As many additional third party packages
+		    as would fit on the disc.</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </table>
+
+	  <table frame="none">
+	    <title>FreeBSD 5.<replaceable>X</replaceable> 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>-RELEASE-<replaceable>arch</replaceable>-bootonly.iso</filename></entry>
+
+		  <entry>Everything you need to boot into a FreeBSD
+		    kernel and start the installation interface.
+		    The installable files have to be pulled over FTP
+		    or some other supported source.</entry>
+		</row>
+
+		<row>
+		  <entry><filename><replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-miniinst.iso</filename></entry>
+		  
+		  <entry>Everything you need to install FreeBSD.</entry>
+		</row>
+
+		<row>
+		  <entry><filename><replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc1.iso</filename></entry>
+
+		  <entry>Everything you need to install &os; and a
+		    <quote>live filesystem</quote>, which is used in
+		    conjunction with the <quote>Repair</quote> facility
+		    in <application>sysinstall</application>.</entry>
+		</row>
+
+		<row>
+		  <entry><filename><replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc2.iso</filename></entry>
+
+		  <entry>&os; documentation and as many third party packages as
+		    would fit on the disc.</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </table>
+
+	  <para>You <emphasis>must</emphasis> download one of either the miniinst
+	    ISO image, or the image of disc one.  Do not download both of them,
+	    since the disc one image contains everything that the miniinst ISO
+	    image contains.</para>
+
+	  <note>
+	    <para>The miniinst ISO image is only available for releases prior
+	      to 5.4-RELEASE.</para>
+	  </note>
+
+	  <para>Use the miniinst 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 to install a &os;
+	    release and want
+	    a reasonable selection of third party packages on the disc
+	    as well.</para>
+
+	  <para>The additional disc images are useful, but not essential,
+	    especially if you have high-speed access to the Internet.</para>
+	</step>
+
+	<step>
+	  <title>Write the CDs</title>
+
+	  <para>You must then write the CD images to disc.  If you will be
+	    doing this on another FreeBSD system then see 
+	    <xref linkend="creating-cds"> for more information (in 
+	    particular, <xref linkend="burncd"> and 
+	    <xref linkend="cdrecord">).</para>
+
+	  <para>If you will be doing this on another platform then you will
+	    need to use whatever utilities exist to control your CD writer on
+	    that platform.  The images provided are in the standard ISO format,
+	    which many CD writing applications support.</para>
+	</step>
+      </procedure>
+
+      <note><para>If you are interested in building a customized
+        release of FreeBSD, please see the <ulink
+        url="&url.articles.releng;">Release Engineering
+        Article</ulink>.</para></note>
+
+    </sect2>
+
+    <sect2 id="install-ftp">
+      <title>Creating a Local FTP Site with a FreeBSD Disc</title>
+	
+      <indexterm>
+	<primary>installation</primary>
+	<secondary>network</secondary>
+	<tertiary>FTP</tertiary>
+      </indexterm>
+
+      <para>FreeBSD discs 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>
+
+      <note>
+	<para>If the boot media (floppy disks, usually) for your FTP
+	  clients is not precisely the same version as that provided
+	  by the local FTP site, then <application>sysinstall</application> will not let you
+	  complete the installation.  If the versions are not similar and
+	  you want to override this, you must go into the <guimenu>Options</guimenu> menu
+	  and change distribution name to
+	  <guimenuitem>any</guimenuitem>.</para>
+      </note>
+
+      <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>bsdlabel</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>bsdlabel -w -r fd0.1440 floppy3</userinput>
+&prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0</userinput></screen>
+
+	<note>
+	  <para>Use <literal>fd0.1200</literal> and
+	    <literal>floppy5</literal> for 5.25" 1.2&nbsp;MB disks.</para>
+	</note>
+
+	<para>Then you can mount and write to them like any other
+	  filesystem.</para>
+
+	<para>After you have formatted the floppies, you will need to copy
+	  the files to them.  The distribution files are split into chunks
+	  conveniently sized so that five of them will fit on a conventional
+	  1.44&nbsp;MB floppy.  Go through all your floppies, packing as many
+	  files as will fit on each one, until you have all of the
+	  distributions you want packed up in this fashion.  Each
+	  distribution should go into a subdirectory on the floppy, e.g.:
+	  <filename>a:\bin\bin.aa</filename>,
+	  <filename>a:\bin\bin.ab</filename>, and so on.</para>
+
+	<para>Once you come to the Media screen during the install
+	  process, select <guimenuitem>Floppy</guimenuitem> and you
+	  will be prompted for the rest.</para>
+      </sect2>
+
+      <sect2 id="install-msdos">
+        <title>Installing from an &ms-dos; Partition</title>
+
+	<indexterm>
+	  <primary>installation</primary>
+	  <secondary>from MS-DOS</secondary>
+	</indexterm>
+	<para>To prepare for an installation from an &ms-dos; partition,
+	  copy the files from the distribution into a directory
+          called <filename>freebsd</filename> in the root directory of the
+	  partition.  For example, <filename>c:\freebsd</filename>.  The
+	  directory structure of the CDROM or FTP site must be partially
+	  reproduced within this directory, so we suggest using the DOS
+	  <command>xcopy</command> command if you are copying it from a CD.
+	  For example, to prepare for a minimal installation of
+	  FreeBSD:</para>
+
+	<screen><prompt>C:\&gt;</prompt> <userinput>md c:\freebsd</userinput>
+<prompt>C:\&gt;</prompt> <userinput>xcopy e:\bin c:\freebsd\bin\ /s</userinput>
+<prompt>C:\&gt;</prompt> <userinput>xcopy e:\manpages c:\freebsd\manpages\ /s</userinput></screen>
+
+	<para>Assuming that <devicename>C:</devicename> is where you have
+	  free space and <devicename>E:</devicename> is where your CDROM
+	  is mounted.</para>
+	
+	<para>If you do not have a CDROM drive, you can download the
+	  distribution from <ulink
+	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">ftp.FreeBSD.org</ulink>.
+	  Each distribution is in its own directory; for example, the
+	  <emphasis>base</emphasis> distribution can be found in the <ulink
+	  url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/base/">&rel.current;/base/</ulink>
+	  directory.</para>
+
+	<para>For as many distributions you wish to install from an &ms-dos;
+	  partition (and you have the free space for), install each one
+	  under <filename>c:\freebsd</filename> &mdash; the
+	  <literal>BIN</literal> distribution is the only one required for
+	  a minimum installation.</para>
+      </sect2>
+
+      <sect2>
+        <title>Creating an Installation Tape</title>
+
+	<indexterm>
+	  <primary>installation</primary>
+	  <secondary>from QIC/SCSI Tape</secondary>
+	</indexterm>
+	<para>Installing from tape is probably the easiest method, short
+	  of an online FTP install or CDROM install.  The installation
+	  program expects the files to be simply tarred onto the tape.
+	  After getting all of the distribution files you are interested
+	  in, simply tar them onto the tape:</para>
+
+	<screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput>
+&prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen>
+
+	<para>When you perform the installation, you should make
+	  sure that you leave enough room in some temporary directory
+	  (which you will be allowed to choose) to accommodate the
+	  <emphasis>full</emphasis> contents of the tape you have created.
+	  Due to the non-random access nature of tapes, this method of
+	  installation requires quite a bit of temporary storage.</para>
+
+	<note>
+	  <para>When starting the installation, the tape must be in the
+	    drive <emphasis>before</emphasis> booting from the boot
+	    floppy.  The installation probe may otherwise fail to find
+	    it.</para>
+	</note>
+      </sect2>
+
+      <sect2>
+        <title>Before Installing over a Network</title>
+
+	<indexterm>
+	  <primary>installation</primary>
+	  <secondary>network</secondary>
+	  <tertiary>serial (SLIP or PPP)</tertiary>
+	</indexterm>
+	<indexterm>
+	  <primary>installation</primary>
+	  <secondary>network</secondary>
+	  <tertiary>parallel (PLIP)</tertiary>
+	</indexterm>
+	<indexterm>
+	  <primary>installation</primary>
+	  <secondary>network</secondary>
+	  <tertiary>Ethernet</tertiary>
+	</indexterm>
+	<para>There are three types of network installations available.
+	  Serial port (SLIP or PPP), Parallel port (PLIP (laplink cable)),
+	  or Ethernet (a standard Ethernet controller (includes some
+	  PCMCIA)).</para>
+
+	<para>The SLIP support is rather primitive, and limited primarily
+	  to hard-wired links, such as a serial cable running between a
+	  laptop computer and another computer.  The link should be
+	  hard-wired as the SLIP installation does not currently offer a
+	  dialing capability; that facility is provided with the PPP
+	  utility, which should be used in preference to SLIP whenever
+	  possible.</para>
+
+	<para>If you are using a modem, then PPP is almost certainly
+	  your only choice.  Make sure that you have your service
+	  provider's information handy as you will need to know it fairly
+	  early in the installation process.</para>  
+
+	<para>If you use PAP or CHAP to connect your ISP (in other words, if
+	  you can connect to the ISP in &windows; without using a script), then
+	  all you will need to do is type in <command>dial</command> at the
+	  <application>ppp</application> prompt.  Otherwise, you will need to
+	  know how to dial your ISP using the <quote>AT commands</quote>
+	  specific to your modem, as the PPP dialer provides only a very
+	  simple terminal emulator.  Please refer to the user-ppp <link
+	  linkend="userppp">handbook</link> and <ulink
+	  url="&url.books.faq;/ppp.html">FAQ</ulink> entries for further information.
+	  If you have problems, logging can be directed to the screen using
+	  the command <command>set log local ...</command>.</para>
+
+	<para>If a hard-wired connection to another FreeBSD (2.0-R or
+	  later) machine is available, you might also consider installing
+	  over a <quote>laplink</quote> parallel port cable.  The data rate
+	  over the parallel port is much higher than what is typically
+	  possible over a serial line (up to 50&nbsp;kbytes/sec), thus resulting
+	  in a quicker installation.</para>
+
+	<para>Finally, for the fastest possible network installation, an
+	  Ethernet adapter is always a good choice!  FreeBSD supports most
+	  common PC Ethernet cards; a table of supported cards (and their
+	  required settings) is provided in the Hardware Notes for each
+	  release of FreeBSD.  If you are using one of the supported PCMCIA
+	  Ethernet cards, also be sure that it is plugged in
+	  <emphasis>before</emphasis> the laptop is powered on!  FreeBSD does
+	  not, unfortunately, currently support hot insertion of PCMCIA cards
+	  during installation.</para>
+
+	<para>You will also need to know your IP address on the network,
+	  the netmask value for your address class, and the name of your
+	  machine.  If you are installing over a PPP connection and do not
+	  have a static IP, fear not, the IP address can be dynamically
+	  assigned by your ISP.  Your system administrator can tell you
+	  which values to use for your particular network setup.  If you
+	  will be referring to other hosts by name rather than IP address,
+	  you will also need a name server and possibly the address of a
+	  gateway (if you are using PPP, it is your provider's IP address)
+	  to use in talking to it.  If you want to install by FTP via a
+	  HTTP proxy, you will also need the proxy's address.
+	  If you do not know the answers to all or most of these questions,
+	  then you should really probably talk to your system administrator
+	  or ISP <emphasis>before</emphasis> trying this type of
+	  installation.</para>
+
+	<sect3>
+	  <title>Before Installing via NFS</title>
+
+	  <indexterm>
+	    <primary>installation</primary>
+	    <secondary>network</secondary>
+	    <tertiary>NFS</tertiary>
+	  </indexterm>
+	  <para>The NFS installation is fairly straight-forward.  Simply
+	    copy the FreeBSD distribution files you want onto an NFS server
+	    and then point the NFS media selection at it.</para>
+
+	  <para>If this server supports only <quote>privileged port</quote>
+	    (as is generally the default for Sun workstations), you will
+	    need to set the option <literal>NFS Secure</literal> in the
+	    <guimenu>Options</guimenu> menu before installation can proceed.</para>
+
+	  <para>If you have a poor quality Ethernet card which suffers
+	    from very slow transfer rates, you may also wish to toggle the
+	    <literal>NFS Slow</literal> flag.</para>
+
+	  <para>In order for NFS installation to work, the server must
+	    support subdir mounts, for example, if your FreeBSD&nbsp;&rel.current; distribution
+	    directory lives on:
+	    <filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, then
+	    <hostid>ziggy</hostid> will have to allow the direct mounting
+	    of <filename>/usr/archive/stuff/FreeBSD</filename>, not just
+	    <filename>/usr</filename> or
+	    <filename>/usr/archive/stuff</filename>.</para>
+
+	  <para>In FreeBSD's <filename>/etc/exports</filename> file, this
+	    is controlled by the <option>-alldirs</option> options.  Other NFS
+	    servers may have different conventions.  If you are getting
+	    <errorname>permission denied</errorname> messages from the
+	    server, then it is likely that you do not have this enabled
+	    properly.</para>
+	</sect3>
+
+      </sect2>
+  </sect1>
+</chapter>
+
+<!-- 
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir1.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir1.dot
new file mode 100644
index 0000000000..f259e8377d
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir1.dot
@@ -0,0 +1,7 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/";
+	root -> "A2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir2.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir2.dot
new file mode 100644
index 0000000000..b846c82399
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir2.dot
@@ -0,0 +1,8 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/" -> "B1/";
+	"A1/" -> "B2/";
+	root -> "A2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir3.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir3.dot
new file mode 100644
index 0000000000..178a3a91bb
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir3.dot
@@ -0,0 +1,8 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/";
+	root -> "A2/" -> "B1/";
+	"A2/" -> "B2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir4.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir4.dot
new file mode 100644
index 0000000000..82d12b421a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir4.dot
@@ -0,0 +1,9 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/";
+	root -> "A2/" -> "B1/" -> "C1/";
+	"B1/" -> "C2/";
+	"A2/" -> "B2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/install/example-dir5.dot b/pl_PL.ISO8859-2/books/handbook/install/example-dir5.dot
new file mode 100644
index 0000000000..f5aa6e01dc
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/install/example-dir5.dot
@@ -0,0 +1,9 @@
+// $FreeBSD$
+
+digraph directory {
+	root [label="Root\n/"];
+	root -> "A1/" -> "C1/";
+	"A1/" -> "C2/";
+	root -> "A2/" -> "B1/";
+	"A2/" -> "B2/";
+}
diff --git a/pl_PL.ISO8859-2/books/handbook/introduction/Makefile b/pl_PL.ISO8859-2/books/handbook/introduction/Makefile
new file mode 100644
index 0000000000..4c22f7ce8a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/introduction/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	introduction/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/introduction/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/introduction/chapter.sgml
new file mode 100644
index 0000000000..96f5d4db86
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/introduction/chapter.sgml
@@ -0,0 +1,971 @@
+<!--
+     The FreeBSD Polish Documentation Project
+
+     $FreeBSD$
+     Original revision: 1.114
+-->
+
+<chapter id="introduction">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+        <firstname>Jim</firstname>
+	<surname>Mock</surname>
+        <contrib>Rozdzia³ zreorganizowa³ i czê¶ciowo
+          napisa³ od nowa </contrib>
+      </author>
+    </authorgroup>
+
+    <authorgroup>
+      <author>
+        <firstname>Cezary</firstname>
+        <surname>Morga</surname>
+        <contrib>T³umaczy³ </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Wprowadzenie</title>
+
+  <sect1 id="introduction-synopsis">
+    <title>Strzeszczenie</title>
+
+    <para>Dziêkujemy za zainteresowanie FreeBSD! W niniejszym rozdziale
+      opisane zostan± ró¿ne aspekty Projektu FreeBSD, takie jak jego historia,
+      obrany cel, czy model rozwoju.</para>
+
+    <para>Czytaj±c ten rozdzia³ poznamy:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Zale¿no¶ci istniej±ce miêdzy FreeBSD i innymi systemami operacyjnymi.</para>
+      </listitem>
+      <listitem>
+        <para>Historiê Projektu FreeBSD.</para>
+      </listitem>
+      <listitem>
+        <para>Cele stawiane przed Projektem FreeBSD.</para>
+      </listitem>
+      <listitem>
+        <para>Podstawowe zagadnienia zwi±zane z modelem rozwoju otwartego oprogramowania
+          (ang. open source) FreeBSD.</para>
+      </listitem>
+      <listitem>
+        <para>I oczywi¶cie, dowiemy siê sk±d pochodzi nazwa <quote>FreeBSD</quote>.</para>
+      </listitem>
+    </itemizedlist>
+
+  </sect1>
+
+  <sect1 id="nutshell">
+    <title>Witamy w ¶wiecie FreeBSD!</title>
+    <indexterm><primary>4.4BSD-Lite</primary></indexterm> 
+
+    <para>FreeBSD jest systemem operacyjnym bazuj±cym na 4.4BSD-Lite, a
+      przeznaczonym dla komputerów pracuj±cych na platformach Intela (x86 i
+      &itanium;), AMD64, <trademark>Alpha</trademark> oraz Sun &ultrasparc;.
+      Przygotowywane s± równie¿ wersje dla innych platform. Wiêcej informacji
+      dostêpnych jest w <link linkend="history">historii FreeBSD</link> b±d¼
+      w nocie o <link linkend="relnotes">aktualnym wydaniu</link>. Je¶li chcia³by¶
+      wspomóc rozwój Projektu (np. kod ¼ród³owy, sprzêt, nieoznakowane banknoty)
+      przeczytaj artyku³ o <ulink
+	url="&url.articles.contributing;/index.html">wspó³pracy z Projektem
+        FreeBSD</ulink> (ang.).</para>
+
+    <sect2 id="os-overview">
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>Aleksander</firstname>
+            <surname>Fafu³a</surname>
+            <contrib>T³umaczy³ </contrib>
+          </author>
+        </authorgroup>
+        <authorgroup>
+          <author>
+            <firstname>Cezary</firstname>
+            <surname>Morga</surname>
+            <contrib>Przek³ad uzupe³ni³ </contrib>
+          </author>
+        </authorgroup>
+      </sect2info>
+
+      <title>Co potrafi FreeBSD?</title>
+
+      <para>FreeBSD posiada mnóstwo zalet. Oto niektóre z nich:</para>
+
+      <itemizedlist>
+        <indexterm><primary>wielozadaniowo¶æ z wyw³aszczaniem</primary></indexterm>
+	<listitem>
+          <para><emphasis>Wielozadaniowo¶æ z wyw³aszczaniem</emphasis>, wraz z
+            dynamiczn± regulacj± priorytetów, by zapewniæ sprawne i bezkonfliktowe
+            wspó³dzielenie zasobów komputera przez aplikacje oraz u¿ytkowników,
+            nawet w sytuacjach najwiêkszego obci±¿enia systemu.</para>
+	</listitem>
+
+        <indexterm><primary>wielou¿ytkownikowo¶æ</primary></indexterm>
+	<listitem>
+          <para><emphasis>Wielou¿ytkownikowo¶æ</emphasis> pozwalaj±ca na
+            jednoczesne wykorzystanie komputera z systemem FreeBSD przez
+            wielu u¿ytkowników. Oznacza to, np. prawid³owe dzielenie dostêpu
+            do urz±dzeñ zewnêtrznych jak np. do drukarki, pomiêdzy wszystkich
+            u¿ytkowników lokalnych jak i sieciowych. Ograniczenia dostêpu do
+            zasobów mog± byæ definiowane dla konkretnych u¿ytkowników b±d¼ grup
+            u¿ytkowników, co z kolei pozwala na zabezpieczenie krytycznych
+            zasobów systemowych przed nadu¿yciami.</para>
+	</listitem>
+      
+        <indexterm><primary>sieci TCP/IP</primary></indexterm>
+	<listitem>
+          <para>Pe³na obs³uga <emphasis>sieci TCP/IP</emphasis>, oraz innych
+            sieciowych standardów jak SLIP, PPP, NFS, DHCP czy NIS. Oznacza
+            to, ¿e twój system FreeBSD mo¿e bez problemów wspó³pracowaæ z
+            dowolnymi innymi systemami operacyjnymi, jak równie¿ pracowaæ w
+            roli serwera w przedsiêbiorstwie, dostarczaj±c niezbêdnych funkcji
+            jak np. NFS (zdalny dostêp do plików) wraz z obs³ug± emaila, b±d¼
+            pozwoli na umieszczenie internetowej wizytówki twojej organizacji
+            na stronie WWW czy dokumentów na serwerze FTP. Mo¿e równie¿ realizowaæ
+            przekierowywanie (ruting) pakietów, a tak¿e pe³niæ rolê zapory
+            ogniowej (firewall).</para>
+	</listitem>
+
+        <indexterm><primary>ochrona pamiêci</primary></indexterm>      
+	<listitem>
+          <para><emphasis>Ochrona pamiêci</emphasis> gwarantuje, ¿e programy
+            (b±d¼ u¿ytkownicy) nie mog± ingerowaæ w pracê innych aplikacji.
+            Innymi s³owy, awaria danego programu w ¿aden sposób nie wp³ywa
+            na dzia³anie pozosta³ych.</para>
+	</listitem>
+      
+	<listitem>
+          <para>FreeBSD jest <emphasis>32-bitowym</emphasis> systemem operacyjnym
+            (64-bitowym na platformach Alpha, &itanium;, AMD64 i &ultrasparc;)
+            i w³a¶nie jako taki projektowany by³ od pocz±tku.</para>
+	</listitem>
+
+	<indexterm>
+    <primary>System okien X</primary>
+    <seealso>XFree86</seealso>
+  </indexterm>
+
+	<listitem>
+          <para>Obecnie standardowy <emphasis>System okien X</emphasis>
+            (X11R6; X Window System) dostarcza interfejsu graficznego (GUI)
+            w cenie zwyk³ej karty VGA i monitora. Ponadto dostêpny jest z
+            pe³nym kodem ¼ród³owym.</para>
+	</listitem>
+
+	<indexterm>
+          <primary>kompatybilno¶æ binarna</primary>
+	  <secondary>Linux</secondary>
+	</indexterm>
+	<indexterm>
+          <primary>kompatybilno¶æ binarna</primary>
+	  <secondary>SCO</secondary>
+	</indexterm>
+	<indexterm>
+          <primary>kompatybilno¶æ binarna</primary>
+	  <secondary>SVR4</secondary>
+	</indexterm>
+	<indexterm>
+          <primary>kompatybilno¶æ binarna</primary>
+	  <secondary>BSD/OS</secondary>
+	</indexterm>
+	<indexterm>
+          <primary>kompatybilno¶æ binarna</primary>
+	  <secondary>NetBSD</secondary>
+	</indexterm>
+	<listitem>
+          <para><emphasis>Kompatybilno¶æ binarn±</emphasis> z wieloma systemami
+            typu &unix;. FreeBSD posiada mo¿liwo¶æ uruchamiania programów
+            skompilowanych dla Linuksa, SCO, SVR4, BSDI i NetBSD.</para>
+	</listitem>
+	
+	<listitem>
+          <para>Tysi±ce aplikacji <emphasis>gotowych do pracy</emphasis>,
+            dostêpnych z kolekcji <emphasis>portów</emphasis> i
+            <emphasis>pakietów</emphasis> FreeBSD. Czemu szukaæ
+            w sieci, skoro wszystko mo¿na znale¼æ w³a¶nie tutaj?</para>
+	</listitem>
+      
+	<listitem>
+          <para>Tysi±ce dodatkowych i
+            <emphasis>³atwych do przeniesienia</emphasis> programów dostêpnych
+            w Internecie. FreeBSD jest kompatybilny z wieloma popularnymi,
+            nawet komercyjnymi systemami typu &unix; i tym samym wiêkszo¶æ
+            programów wymaga zaledwie kilku, je¶li w ogóle, zmian w kodzie
+            aby poprawnie skompilowaæ i uruchomiæ.</para>
+	</listitem>
+      
+	<indexterm><primary>pamiêæ wirtualna</primary></indexterm>
+	<listitem>
+          <para>Stronicowana <emphasis>pamiêæ wirtualna</emphasis> oraz
+            wspó³dzielona pamiêæ podrêczna <quote>VM/buffer cache</quote>
+            zaprojektowane by efektywnie zaspokajaæ potrzeby aplikacji z
+            du¿ym apetytem na pamiêæ, przy jednoczesnym zapewnieniu ci±g³ej
+            interakcji systemu z u¿ytkownikami.</para>
+	</listitem>
+      
+        <indexterm>
+	  <primary>Symmetric Multi-Processing (SMP)</primary>
+	</indexterm>
+	<listitem>
+          <para>Wsparcie dla technologii <emphasis>SMP</emphasis>, dla maszyn
+            z wieloma procesorami.</para>
+	</listitem>
+
+	<indexterm>
+	  <primary>kompilatory</primary>
+	  <secondary>C</secondary>
+	</indexterm>
+	<indexterm>
+          <primary>kompilatory</primary>
+	  <secondary>C++</secondary>
+	</indexterm>
+	<indexterm>
+          <primary>kompilatory</primary>
+	  <secondary>FORTRAN</secondary>
+	</indexterm>
+	<listitem>
+          <para>Kompletne ¶rodowiska programistyczne dla jêzyków <emphasis>C</emphasis>,
+            <emphasis>C++</emphasis> i <emphasis>Fortran</emphasis>. FreeBSD posiada
+            równie¿ wiele dodatkowych ¶rodowisk dla innych jêzyków programowania
+            dostêpnych w kolekcji portów i pakietów.</para>
+	</listitem>
+
+	<indexterm><primary>kod ¼ród³owy</primary></indexterm>
+	<listitem>
+          <para>Dostêpno¶æ <emphasis>kodu ¼ród³owego</emphasis> dla ca³ego
+            systemu oznacza, i¿ to w³a¶nie ty posiadasz najwiêksz± kontrolê
+            nad swoim ¶rodowiskiem pracy. Czemu zamykaæ siê w krêgu
+            rozwi±zañ w³asno¶ciowych i byæ skazanym na ³askê dostarczyciela
+            systemu, kiedy mo¿na mieæ prawdziwie otwarty system?</para>
+	</listitem>
+      
+	<listitem>
+          <para>Obszern± <emphasis>dokumentacjê</emphasis> dostêpn±
+            w Internecie..</para>
+	</listitem>
+      
+	<listitem>
+          <para><emphasis>I wiele wiêcej!</emphasis></para>
+	</listitem>
+      </itemizedlist>
+    
+      <indexterm><primary>4.4BSD-Lite</primary></indexterm>
+      <indexterm>
+        <primary>Computer Systems Research Group (CSRG)</primary>
+      </indexterm>
+      <indexterm><primary>Uniwersytet Kalifornijski w Berkeley</primary></indexterm>
+      <para>FreeBSD jest oparty na systemie 4.4BSD-Lite pochodz±cym
+        z Computer Systems Research Group (CSRG) z Uniwersytetu
+        Kalifornijskiego w Berkeley. Podtrzymuje dostojn± tradycjê
+        trendu rozwojowego systemów BSD. Oprócz doskona³ej pracy
+        wykonanej przez CSRG równie¿ programi¶ci z Projektu FreeBSD
+        spêdzili dodatkowe tysi±ce godzin, aby udoskonaliæ go i
+        przygotowaæ na trudne, ¿yciowe sytuacje. W czasie gdy wielu
+        z komercyjnych gigantów bran¿y komputerów PC stara siê
+        wyposa¿yæ swoje systemy operacyjne w podobne cechy, by
+        osi±gn±æ takie same wyniki i poziom niezawodno¶ci, FreeBSD
+        oferuje to ju¿ <emphasis>teraz</emphasis>!</para>
+
+      <para>Liczba aplikacji z którymi mo¿e wspó³pracowaæ FreeBSD
+        jest ograniczona jedynie przez nasz± wyobra¼niê. Od projektów
+        programistycznych, poprzez automatyzacjê produkcji w fabrykach,
+        kontrolê stanu magazynów, po regulacjê azymutu anteny satelitarnej;
+        je¶li jest to mo¿liwe w komercyjnych systemach UNIX jest to wiêcej
+        ni¿ prawdopodobne, ¿e mo¿esz to zrobiæ równie¿ we FreeBSD! On sam
+        korzysta z dos³ownie tysiêcy doskonale dopracowanych aplikacji,
+        nierzadko pochodz±cych z komercyjnych centrów projektowych b±d¼
+        laboratoriów uniwersyteckich, dostêpnych niemal¿e b±d¼ ca³kowicie
+        za darmo. Dostêpne jest równie¿ oprogramowanie komercyjne, którego
+        liczba ro¶nie równie szybko, jak oprogramowania bezp³atnego.</para>
+
+      <para>Jako, ¿e kod ¼ród³owy FreeBSD jest publicznie dostêpny,
+        system mo¿e zostaæ dostosowany do wielu specjalistycznych
+        projektów oraz zastosowañ, co jest niemo¿liwe w przypadku
+        wielu systemów komercyjnych. Oto krótka lista aplikacji,
+        z którymi najczê¶ciej u¿ywany jest FreeBSD:</para>
+    
+      <itemizedlist>
+	<listitem>
+          <para><emphasis>Us³ugi internetowe:</emphasis> doskona³a obs³uga
+            TCP/IP wbudowana we FreeBSD, czyni go idealn± platform± dla
+            szeregu us³ug internetowych, na przyk³ad:</para>
+
+	  <itemizedlist>
+            <indexterm><primary>serwery FTP</primary></indexterm>
+	    <listitem>
+              <para>Serwery FTP</para>
+	    </listitem>
+	  
+	    <indexterm><primary>serwery WWW</primary></indexterm>
+	    <listitem>
+              <para>Serwery witryn WWW (standardowe b±d¼ zabezpieczone
+                [SSL])</para>
+	    </listitem>
+
+	    <indexterm><primary>zapora ogniowa</primary></indexterm>
+	    <indexterm><primary>NAT</primary></indexterm>
+	    <listitem>
+              <para>Zapory ogniowe i bramy NAT (<quote>maskarada
+                  IP</quote>)</para>
+	    </listitem>
+	  
+	    <indexterm>
+	      <primary>poczta elektroniczna</primary>
+	      <see>email</see>
+	    </indexterm>
+	    <indexterm>
+	      <primary>email</primary>
+	    </indexterm>
+	    <listitem>
+              <para>Serwery poczty elektronicznej</para>
+	    </listitem>
+	  
+	    <indexterm><primary>USENET</primary></indexterm>
+	    <listitem>
+              <para>USerwery USENET b±d¼ systemy Forum</para>
+	    </listitem>
+	  
+	    <listitem>
+              <para>I wiêcej...</para>
+	    </listitem>
+	  </itemizedlist>
+
+          <para>Wraz z FreeBSD mo¿esz zacz±æ ¶wiadczyæ us³ugi
+            internetowe ju¿ na niedrogim komputerze PC klasy 386
+            i rozwijaæ bazê sprzêtow± swojego przedsiêbiorstwa a¿ do
+            cztero-procesorowego Xeona z macierz± RAID.</para>
+	</listitem>
+      
+	<listitem>
+          <para><emphasis>Edukacja:</emphasis>  jeste¶ studentem
+            informatyki b±d¼ pokrewnej dziedziny techniki? Nie ma
+            lepszego sposobu na poznanie systemu operacyjnego,
+            architektury komputerów oraz zagadnieñ sieciowych ni¿
+            poprzez do¶wiadczenie, które daje praca z FreeBSD. Du¿a
+            liczba darmowych programów typu CAD, matematycznych czy
+            graficznych bêdzie wysoce u¿yteczna dla tych, których
+            g³ównym zainteresowaniem w komputerach jest aby zmusiæ je do pracy
+            <emphasis>za nas</emphasis>!</para>
+	</listitem>
+      
+	<listitem>
+          <para><emphasis>Badania:</emphasis>  oferuj±c dostêp do kodu
+            ¼ród³owego ca³ego systemu, FreeBSD stanowi doskona³± platformê
+            dla prowadzenia badañ nad systemami operacyjnymi oraz innymi
+            dziedzinami nauk komputerowych. Idea otwartego ¼ród³a wspomaga
+            tak¿e ca³e grupy wspó³pracuj±ce zdalnie nad ró¿nymi zadaniami,
+            pomagaj±c zapomnieæ im o problemach zwi±zanych ze specjalnymi
+            warunkami licencyjnymi oraz ograniczeniami.</para>
+	</listitem>
+      
+	<indexterm><primary>ruter</primary></indexterm>
+	<indexterm><primary>Serwer DNS</primary></indexterm>
+	<listitem>
+          <para><emphasis>Sieæ:</emphasis>  potrzebujesz nowego rutera?
+            Serwera nazw (DNS)? Zapory ogniowej (firewalla), by wystrzec
+            siê niepowo³anych u¿ytkowników w swojej sieci wewnêtrznej?
+            FreeBSD mo¿e w ³atwy sposób zamieniæ bezu¿ytecznego 486 lub
+            nawet 386, stoj±cego w k±cie, w zaawansowany router z
+            wyszukanymi opcjami filtrowania pakietów.</para>
+	</listitem>
+      
+	<indexterm>
+	  <primary>System okien X</primary>
+	  <secondary>XFree86</secondary>
+	</indexterm>
+	<indexterm>
+	  <primary>System okien X</primary>
+	  <secondary>Akceleracja X-ów</secondary>
+	</indexterm>
+	<listitem>
+          <para><emphasis>¦rodowisko graficzne:</emphasis> FreeBSD stanowi
+            dobre rozwi±zanie dla niedrogiego terminala graficznego. W tym
+            celu mo¿na wykorzystaæ dostêpny serwer X11, b±d¼ jeden z doskona³ych
+            komercyjnych serwerów <ulink
+	    url="http://www.xig.com">Xi Graphics</ulink>. W przeciwieñstwie do
+            typowych terminali graficznych, FreeBSD pozwala na uruchamianie
+            wielu aplikacji lokalnie je¶li zajdzie taka potrzeba, odci±¿aj±c
+            tym samym g³ówny serwer. FreeBSD mo¿e byæ równie¿ uruchamiany w
+            systemach <quote>bezydskowych</quote> zmniejszaj±c tym samym cenê
+            komputerów s³u¿±cych za terminale.</para>
+	</listitem>
+      
+	<indexterm><primary>Kolekcja kompilatorów GNU</primary></indexterm>
+	<listitem>
+          <para><emphasis>Programowanie:</emphasis>  system FreeBSD zaopatrzony
+            jest w pe³en zestaw narzêdzi programistycznych, w³±czaj±c w to
+            s³awny kompilator oraz debugger GNU C/C++.</para>
+	</listitem>
+      </itemizedlist>
+    
+      <para>FreeBSD jest dostêpny zarówno w postaci kodu ¼ród³owego jak i
+        skompilowanych binariów dostêpnych na p³ytach CDROM, DVD i poprzez
+        anonimowy serwer FTP. <xref linkend="mirrors"> zawiera wiêcej informacji
+        nt. sposobów uzyskania FreeBSD.</para>
+    </sect2>
+
+    <sect2>
+      <title>Kto u¿ywa FreeBSD?</title>
+
+      <indexterm>
+	<primary>u¿ytkownicy</primary>
+	<secondary>du¿e witryny WWW pracuj±ce na FreeBSD</secondary>
+      </indexterm>
+
+      <para>FreeBSD zasila niektóre z najwiêkszych witryn w Internecie,
+        m.in:</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>i wiele wiêcej.</para>
+    </sect2>
+
+  </sect1>
+  
+  <sect1 id="history">
+    <title>O Projekcie FreeBSD</title>
+
+    <para>Niniejszy podrozdzia³ zawiera podstawowe informacje o projekcie,
+      m.in. krótk± historiê, cele stawiane przed projektem i stosowany
+      model rozwoju.</para>
+
+    <sect2 id="intro-history">
+      <sect2info role="firstperson">
+	<authorgroup>
+	  <author>
+	    <firstname>Jordan</firstname>
+	    <surname>Hubbard</surname>
+	    <contrib>Napisa³ </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Krótka historia 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>Genezy projektu FreeBSD nale¿y doszukiwaæ siê w pierwszej
+        po³owie roku 1993. Wyrós³ on czê¶ciowo z <quote>Nieoficjalnego
+        zestawu ³at dla 386BSD</quote> (patchkit). Stworzony zosta³ przez
+        trzech ostatnich koordynatorów zestawu: Nate'a Williamsa, Roda
+        Grimesa i mnie.</para>
+    
+      <indexterm><primary>386BSD</primary></indexterm>
+      <para>Naszym pierwotnym celem by³o przygotowanie migawki z rozwoju
+        386BSD, wprowadzaj±cej szereg poprawek, których mechanizm zestawu
+        ³at nie by³ w stanie zrealizowaæ. Niektórzy z czytaj±cych mog±
+        pamiêtaæ wczesn± nazwê projektu <quote>386BSD 0.5</quote> b±d¼
+        <quote>386BSD Interim</quote>.</para>
+    
+      <indexterm><primary>Jolitz, Bill</primary></indexterm>
+      <para>386BSD by³ systemem operacyjnym Billa Jolitza, cierpi±cym w
+        tym okresie z powodu przesz³o rocznego zastoju. W wyniku puchniêcia
+        zestawu ³at z dnia na dzieñ coraz bardziej, jednomy¶lnie postanowili¶my
+        spróbowaæ naprawiæ sytuacjê. Zdecydowali¶my siê wspomóc Billa
+        dostarczaj±c owej <quote>porz±dkuj±cej</quote> migawki. Niestety
+        plan spali³ na panewce gdy Bill Jolitz nagle zdecydowa³ cofn±æ swoje
+        poparcie dla projektu, nie informuj±c co zamierza wprowadziæ
+        w jego miejsce.</para>
+
+      <indexterm><primary>Greenman, David</primary></indexterm>
+      <indexterm><primary>Walnut Creek CDROM</primary></indexterm>
+      <para>Szybko stwierdzili¶my, ¿e rozpoczête zadanie jest warte ¶wieczki
+        nawet bez wsparcia Billa. Tym samym przyjêli¶my nazwê
+        <quote>FreeBSD</quote> ukut± przez Davida Greenmana. Cele
+        projektu zosta³y wstêpnie okre¶lone po rozmowach z ówczesnymi
+        u¿ytkownikami systemu. Gdy sta³o siê jasne, ¿e projekt zmierza
+        w kierunku stania siê rzeczywisto¶ci±, skontaktowa³em siê z
+        firm± Walnut Creek CDROM w celu usprawnienia metod dystrybucji
+        FreeBSD, szczególnie z my¶l± o tych nieszczê¶nikach, którzy mieli
+        utrudniony dostêp do Internetu. Walnut Creek CDROM nie tylko wspar³
+        pomys³ dystrybucji FreeBSD na p³ytach CD, ale równie¿ wyszed³ nam
+        na przeciw oferuj±c projektowi maszynê do pracy i szybkie ³±cze
+        z Internetem. Jest ma³o prawdopodobne, ¿e projekt zaszed³ by a¿
+        tak daleko bez niespotykanej wrêcz wiary Walnut Creek CDROM w
+        kompletnie ma³o znany projekt, którym w owym czasie by³
+        FreeBSD.</para>
+
+      <indexterm><primary>4.3BSD-Lite</primary></indexterm>
+      <indexterm><primary>Net/2</primary></indexterm>
+      <indexterm><primary>Uniwersytet Kalifornijski w Berkeley</primary></indexterm>
+      <indexterm><primary>386BSD</primary></indexterm>
+      <indexterm><primary>Free Software Foundation</primary></indexterm>
+      <para>Pierwsz± wersj± rozprowadzan± na p³ytach CD (a tak¿e w
+        Internecie) by³ FreeBSD&nbsp;1.0, wydany w grudniu 1993 r.
+        Oparty by³ on bezpo¶rednio na 4.3BSD-Lite (<quote>Net/2</quote>)
+        z Uniwersytetu Kalifornijskiego w Berkeley. Zawiera³ równie¿ wiele
+        dodatkowych aplikacji pochodoz±cych z 386BSD oraz Free Software
+        Foundation. Mo¿na przyj±æ, i¿ osi±gna³ on ca³kiem rozs±dny sukces
+        jak na pierwsz± wersjê. Nastêpuj±ce po nim wydanie FreeBSD&nbsp;1.1
+        w maju 1994 r. by³o pe³nym sukcesem.</para>
+
+      <indexterm><primary>Novell</primary></indexterm>
+      <indexterm><primary>Uniwersytet Kalifornijski w Berkeley</primary></indexterm>
+      <indexterm><primary>Net/2</primary></indexterm>
+      <indexterm><primary>AT&amp;T</primary></indexterm>
+      <para>Mniej wiêcej w tym w³a¶nie czasie czarne chmury niespodzianie
+        pojawi³y siê nad horyzontem. Powodem tego by³a ugoda w
+        przeci±gaj±cym siê procesie pomiêdzy Novellem i Uniwersytetem
+        w Berkeley odno¶nie legalno¶ci kalifornijskiego Net/2. Jednym z
+        warunków ugody by³o ustêpstwo Berkeley stwierdzaj±ce, i¿ znaczne
+        czê¶ci kodu Net/2 zosta³y <quote>powielone</quote> z kodu systemu &unix;,
+        bêd±cego w³asno¶ci± Novella, który z kolei naby³ go wcze¶niej od AT&amp;T.
+        W zamian Berkley uzyska³o <quote>b³ogos³awieñstwo</quote> Novella w
+        pracach nad 4.4BSD-Lite i zapewnienie, ¿e gdy siê w koñcu pojawi nie
+        bêdzie okre¶lane jako kopia kodu Novella. Ponadto wszyscy u¿ytkownicy
+        Net/2 mieli byæ gor±co zachêciani do aktualizacji systemu. Ugoda ta
+        dotyczy³a równie¿ FreeBSD, bowiem projekt mia³ wstrzymaæ dystrybucjê
+        swoich produktów bazuj±cych na Net/2 do koñca lipca 1994 r. Zgodnie
+        z warunkami porozumienia, pozwolono projektowi na jedno ostatnie
+        wydanie przed tym terminem. By³o to FreeBSD&nbsp;1.1.5.1.</para>
+
+      <para>Rozpoczê³a siê ¿mudna praca nad ponownym stworzeniem FreeBSD
+        z czê¶ci ca³kowicie nowego i raczej niekompletnego 4.4BSD-Lite.
+        Wydanie <quote>Lite</quote> by³o w rzeczy samej <quote>lekkie</quote>;
+        czê¶ciowo w wyniku usuniêcia przez CSRG Uniwersytetu w Berkeley
+        wielkich partii kodu (z uwagi na pewne wymogi prawne), które odpowiada³y
+        za przygotowanie samodzielnie uruchamiajacego siê systemu, oraz z faktu,
+        ¿e wersja 4.4 nie byla jeszcze gotowa na platformê Intela. Prace potrwa³y
+        do listopada 1994 r., kiedy to wydany zosta³ FreeBSD&nbsp;2.0, rozprowadzany
+        zarówno przez sieæ jak i na p³ytach CD (w pó¼nym grudniu). Pomimo kilku
+        niedoci±gniêæ wydanie osi±gne³o znacz±cy sukces. Przy czym ju¿ w
+        styczniu 1995 r. zosta³o zast±pione stabilniejszym i ³atwiejszym w
+        instalacji FreeBSD&nbsp;2.0.5.</para>
+
+      <para>FreeBSD&nbsp;2.1.5 wydali¶my w sierpniu 1996. Wersja ta zyska³a
+        popularno¶æ szczególnie po¶ród dostawców us³ug internetowych (ISP)
+        oraz szerokopojêtej spo³eczno¶ci komercyjnej. Docenione zosta³o
+        równie¿ kolejne wydanie w ga³êzi 2.1-STABLE. Mowa tu o
+        FreeBSD&nbsp;2.1.7.1, wydanym w lutym 1997 r., a zamykaj±cym g³ówne
+        prace nad 2.1-STABLE. Od tej pory trwa³y jedynie prace nad utrzymaniem
+        ga³êzi (RELENG_2_1_0); dodawane by³y ³aty bezpieczeñstwa i naprawiane
+        krytyczne luki./para>
+
+      <para>Z g³ównego nurtu rozwojowu (<quote>-CURRENT</quote>) w listopadzie
+        1996 r. odga³êzi³ siê FreeBSD&nbsp;2.2 jako ga³±¼ RELENG_2_2.
+        Piersze pe³ne wydanie (2.2.1) pojawi³o siê w kwietniu 1997 r.
+        Kolejne wydania z ga³êzi 2.2 ujrza³y ¶wiat³o dzienne w lecie i na
+        jesieni 1997 r., przy czym ostatnie (2.2.8) pojawi³o siê w listopadzie
+        1998 r. Pierwsze oficjalne wydanie 3.0 pochodzi z pa¼dziernika
+        1998 r. i stanowi³o pocz±tek koñca ga³êzi 2.2.</para>
+
+      <para>Drzewo ewolucji FreeBSD ponownie rozdzieli³o siê 20 stycznia
+        1999 r., prowadz±c do 4.0-CURRENT i 3.X-STABLE. Wersja 3.1 z 3.X-STABLE
+        wydana zosta³a 15 lutego 1999, wersja 3.2 dnia 15 maja 1999, 3.3 w dniu
+        16 wrze¶nia 1999, 3.4 - 20 grudnia 1999 oraz 3.5 dnia 24 stycznia 2000.
+        Wkrótce pojawi³o siê równie¿ pomniejsze wydanie 3.5.1, które zawiera³o
+        kilka poprawek z ostatniej chwili do systemu Kerberos. By³o to ostatnie
+        wydanie ga³êzi 3.X.</para>
+
+      <para>Kolejne rozga³êzienie mia³o miejsce 13 marca 2000 r. w wyniku czego
+        pojawi³a siê ga³±¼ 4.X-STABLE: 4.0-RELEASE w marcu 2000 i ostatnie
+        wydanie 4.11-RELEASE w styczniu 2005.</para>
+
+      <para>Pojawienie siê d³ugo oczekiwanej ga³êzi 5.0-RELEASE zosta³o og³oszone
+        19 stycznia 2003 r. Stanowi³a ona punkt kulminacyjny prawie
+        trzyletniego wysi³ku. Wydanie te wprowadzi³o FreeBSD na ¶cie¿kê ku
+        wspó³pracy z komputerami multiprocesorowymi oraz zaawansowanej
+        obs³ugi w±tków aplikacji. Oferowa³a równie¿ wsparcie dla platform
+        &ultrasparc; i <literal>ia64</literal>. Wydanie 5.1 pojawi³o siê w
+        czerwcu 2003 r. Ostatnie wydanie 5.X z ga³êzi -CURRENT stanowi³o
+        5.2.1-RELEASE, wprowadzone w lutym 2004.</para>
+
+      <para>Ga³±¼ RELENG_5 powsta³a w sierpniu 2004 r., a tak¿e wydanie
+        5.3-RELEASE, stanowi pocz±tek wydañ ga³êzi 5-STABLE. Najnowsze wydanie
+        &rel2.current;-RELEASE pojawi³o siê w maju 2006. Wydawane bêd±
+        wci±¿ kolejne wersje z ga³êzi RELENG_5.</para>
+
+      <para>Kolejne rozga³êzienie nast±pi³o w czerwcu 2005: powsta³a ga³±¼
+        RELENG_6. Wydanie 6.0-RELEASE, pierwsze z ga³êzi 6.X, pojawi³o siê
+        w listopadzie 2005. Najnowsze wydanie &rel.current;-RELEASE ujrza³o
+        ¶wiat³o dzienne w maju 2006 r. Bêd± pojawiaæ siê równie¿ kolejne
+        wydania z ga³êzi RELENG_6.</para>
+
+      <para>Na chwilê obecn± projekty d³ugoterminowe prowadzone s± w ga³êzi
+        7.X-CURRENT. Migawki wydañ 7.X, obrazuj±ce postêp prac, s± ca³y
+        czas dostêpne z
+        <ulink url="ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/">serwera
+          migawkowego</ulink> jak równie¿ na p³ytach CD.</para>
+    </sect2>
+      
+    <sect2 id="goals">
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>Jordan</firstname>
+	    <surname>Hubbard</surname>
+   	    <contrib>Napisa³ </contrib>
+	  </author>
+        </authorgroup>
+      </sect2info>
+
+      <title>Cele Projektu FreeBSD</title>
+    
+      <indexterm>
+        <primary>FreeBSD Project</primary>
+        <secondary>goals</secondary>
+      </indexterm>
+      <para>G³ównym celem Projektu FreeBSD jest dostarczanie
+        oprogramowania, które mo¿e byæ wykorzystane w dowolny sposób
+        i bez dodatkowych zobowi±zañ. Wielu z nas ma du¿y wk³ad w tworzenie
+        kodu (i rozwój projektu w ogóle) i z pewno¶ci± nie mia³oby nic
+        przeciw drobnemu wsparciu finansowemu. Tym nie mniej nie wywieramy
+        ¿adnego nacisku. Wierzymy, ¿e nasz± pierwsz± i najwa¿niejsz±
+        <quote>misj±</quote> jest dostarczanie kodu wszystkim tym, ktorzy
+        go potrzebuj± bez wzglêdu na to do czego go wykorzystaj±, by zyska³
+        on mo¿liwie najszersz± bazê u¿ytkowników dostarczaj±c mo¿liwie
+        najwiêkszych korzy¶ci. W moim przekonaniu jest to jeden z najbardziej
+        fundamentalnych celów stawianych przed ca³ym Wolnym Oprogramowaniem,
+        a przez nas entuzjastycznie wspierany.</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>Te czê¶ci kodu w naszym drzewie ¼ród³owym, które udostêpniane
+        s± na licencji GNU General Public License (GPL) b±d¼ Library General
+        Public License (LGPL) posiadaj± kilka dodatkowych zobowi±zañ, choæ
+        zwi±zanych raczej z wymogiem udostêpnienia kodu ¼ród³owego. Z uwagi
+        na dodatkowe komplikacje, które mog± pojawiæ siê w przypadku
+        komercyjnego zastosowania aplikacji na licencji GPL, osobi¶cie
+        sk³aniamy siê - kiedy jest to mo¿liwe - ku oprogramowaniu
+        dystrybuowanemu przy wykorzystaniu mniej restrykcyjnej licencji
+        BSD.</para>
+    </sect2>
+  
+    <sect2 id="development">
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>Satoshi</firstname>
+	    <surname>Asami</surname>
+   	    <contrib>Napisa³ </contrib>
+	  </author>
+        </authorgroup>
+      </sect2info>
+
+      <title>Model rozwoju FreeBSD</title>
+    
+      <indexterm>
+        <primary>Projekt FreeBSD</primary>
+        <secondary>model rozwoju</secondary>
+      </indexterm>
+      <para>Rozwój FreeBSD jest otwartym i elastycznym procesem
+        realizowanym przez setki ludzi na ca³ym ¶wiecie (patrz
+        <ulink
+	url="&url.articles.contributors;/article.html">Lista
+          wspó³pracowników</ulink>). Infrastruktura systemu rozwoju
+        FreeBSD pozwala tym¿e setkom projektantów wspó³pracowaæ przez
+        Internet. Tym nie mniej nieustannie poszukujemy nowych
+        projektantów, a tak¿e nowych pomys³ów. Osoby zainteresowane
+        nawi±zaniem bli¿szej wspó³pracy z projektem mog± kontaktowaæ
+        siê z nami bezpo¶rednio poprzez &a.pl.hackers.b;. Natomiast
+        &a.pl.announce.m; jest równie¿ dostêpna dla osób chc±cych
+        poinformowaæ innych u¿ytkowników FreeBSD o g³ównych
+        obszarach prowadzonych prac.</para>
+
+      <para>Oto gar¶æ informacji o projekcie FreeBSD i jego procesie
+        rozwoju, przydatnych zarówno niezale¿nym projektantom jak
+        i bliskim wspó³pracownikom:</para>
+
+      <variablelist>
+	<varlistentry>
+          <term>Repozytorium CVS<anchor
+	    id="development-cvs-repository"></term>
+
+	  <indexterm>
+      <primary>CVS</primary>
+      <secondary>repozytorium</secondary>
+    </indexterm>
+	  <indexterm>
+	    <primary>Concurrent Versions System</primary>
+      <see>CVS</see>
+	  </indexterm>
+	  <listitem>
+            <para>G³ówne drzewo ¼ród³owe FreeBSD utrzymywane jest w systemie
+              <ulink url="http://ximbiot.com/cvs/wiki/">CVS</ulink>
+              (Concurrent Versions System) - wolnodostêpnym narzêdziu
+              kontroli wersji kodu ¼ród³owego, dostêpnym we FreeBSD.
+              Podstawowe <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi">repozytorium
+              CVS</ulink> znajduje siê na maszynie zlokalizowanej w Santa Clara w Kalifornii,
+              USA, sk±d replikowane jest na serwery lustrzane, rozrzucone po
+              ca³ym ¶wiecie. G³ówne drzewo CVS, zawieraj±ce zarówno drzewo
+              <link linkend="current">-CURRENT</link> jak i <link
+	      linkend="stable">-STABLE</link>, mo¿na ³atwo skopiowaæ równie¿
+              na swój w³asny komputer. Proces ten zosta³ dok³adniej opisany
+              w podro¼dziale <link linkend="synching">Synchronizacja w³asnego
+              drzewa kodu ¼ród³owego</link>.</para>
+	  </listitem>
+	</varlistentry>
+      
+	<varlistentry>
+          <term>Lista twórców<anchor
+	    id="development-committers"></term>
+	      
+	  <indexterm><primary>twórcy</primary></indexterm>
+	  <listitem>
+            <para><firstterm>Twórcy</firstterm> s± lud¼mi, którzy posiadaj± prawa
+              zapisu do drzewa CVS i posiadaj± upowa¿nienie do wprowadzania
+              modyfikacji do kodu ¼ród³owego FreeBSD. Angielski odpowiednik
+              terminu <quote>twórca</quote> (ang. committer) pochodzi od
+              polecenia <command>commit</command> systemu &man.cvs.1;,
+              stosowanego do wprowadzania zmian do repozytorium CVS.
+              Najlepszym sposobem przedstawienia w³asnych propozycji na li¶cie
+              dyskusyjnej twórców jest wykorzystanie polecenia &man.send-pr.1;.
+              Je¶li system sprawia wra¿enie zablokowanego mo¿na równie¿ wys³aæ
+              e-mail bezpo¶rednio na &a.pl.committers.b;.</para>
+	  </listitem>
+	</varlistentry>
+      
+	<varlistentry>
+          <term>G³ówni projektanci FreeBSD<anchor id="development-core"></term>
+
+	  <indexterm><primary>zespó³ g³ówny</primary></indexterm>
+	  <listitem>
+            <para>Porównuj±c Projekt FreeBSD z przedsiêbiorstwem,
+              <firstterm>zespó³ g³ówny</firstterm> nale¿a³oby porównaæ
+              z zarz±dem firmy. Podstawowym zadaniem tej¿e grupy jest
+              czuwanie nad prawid³owym rozwojem projektu jako ca³o¶ci.
+              Jedn± z funkcji grupy jest zapraszanie oddanych i odpowiedzialnych
+              projektantów w szeregi twórców systemu, podobnie jak przyjmowanie
+              w szeregi samej grupy. Obecna grupa zosta³a wybrana spo¶ród
+              wszystkich twórców w czerwcu 2004 r. Wybory maj± miejsce co
+              dwa lata.</para>
+
+            <para>Niektórzy z cz³onków grupy posiadaj± równie¿ dodatkowy
+              zakres obowi±zków, tj. czuwaj± nad zapewnieniem poprawnego
+              funkcjonowania wybranych czê¶ci systemu. Pe³na lista projektantów
+              FreeBSD i ich obowi±zków dostêpna jest w artykule <ulink
+	      url="&url.articles.contributors;/article.html">Lista
+              wspó³pracowników</ulink>.</para>
+
+	    <note>
+              <para>Wiêkszo¶æ cz³onków grupy jest ochotnikami, je¶li
+                chodzi o rozwój FreeBSD, i nie otrzymuj± ¿adnego wynagrodzenia
+                finansowwego z projektu. Nie nale¿y zatem b³êdnie
+                interpretowaæ <quote>wspó³pracy</quote> z projektem jako
+                <quote>gwarancji wsparcia</quote>. W tym ¶wietle, powy¿sze
+                porównanie z <quote>zarz±dem</quote> nie jest do koñca celne.
+                Bardziej odpowiednim by³oby powiedzieæ, ¿e s± to ludzie,
+                którzy z w³asnego wyboru oddali swój wolny czas dla
+                FreeBSD!</para>
+	    </note>
+	  </listitem>
+	</varlistentry>
+      
+	<varlistentry>
+          <term>Zewnêtrzni wspó³pracownicy</term>
+
+	  <indexterm><primary>wspó³pracownicy</primary></indexterm>
+	  <listitem>
+            <para>Co prawda jako ostatnia, ale zdecydowanie nie jako
+              najmniej istotna, omówiona zostanie grupa wspó³pracowników
+              zewnêtrznych, czyli samych u¿ytkowników, którzy dostarczaj±
+              na bie¿±co informacji o funkcjonowaniu systemu oraz poprawek
+              wykrytych b³êdów. Najlepszym sposobem na udzia³ w rozwoju
+              FreeBSD jest subskrypcja &a.pl.hackers.d;. <xref
+              linkend="eresources"> zawiera wiêcej informacji o ró¿norodnych
+              listach dyskusyjnych FreeBSD.</para>
+	  
+	    <para><citetitle><ulink
+              url="&url.articles.contributors;/article.html">Lista wspó³pracowników
+              FreeBSD</ulink></citetitle> ca³y czas ro¶nie. Czemu by nie do³±czyæ
+              do listy pomagaj±c w pracy nad FreeBSD ju¿ dzisiaj?</para>
+
+            <para>Pisanie kodu nie jest jedyn± form± wspó³pracy z projektem:
+              kompletna lista rzeczy, które trzeba zrobiæ dostêpna jest na
+              <ulink url="&url.base;/index.html">stronie Projektu
+              FreeBSD</ulink>.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    
+      <para>Reasumuj±c, nasz model rozwoju zorganizowany jest jako niezale¿ne,
+        wspó³centryczne okrêgi. Zcentralizowany model ma za zadanie u³atwiæ
+        <emphasis>u¿ytkownikom</emphasis> FreeBSD ¶ledzenie zmian w kodzie.
+        Odstraszanie potencjalnych wspó³pracowników nie jest naszym celem!
+        Pragniemy dostarczaæ stabilny system operacyjny z du¿± baz± ³atwych
+        do instalacji i wykorzystania <link linkend="ports">programów</link>
+        &mdash; ten model doskonale siê w tym spisuje.</para>
+    
+      <para>Jedyne o co prosimy tych, którzy mieliby wst±piæ w szeregi
+        projektantów FreeBSD, jest oddanie takie same jakie cechuje ich
+        obecnych twórców.</para>
+    </sect2>
+
+    <sect2 id="relnotes">
+      <title>Aktualne wydanie FreeBSD</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>Uniwersytet Kalifornijski w Berkeley</primary></indexterm>
+      <indexterm>
+        <primary>Computer Systems Research Group (CSRG)</primary>
+      </indexterm>
+      <para>FreeBSD jest ³atwo dostêpnym systemem operacyjnym, bazuj±cym
+        na kodzie 4.4BSD-Lite, dla nastêpuj±cych platform sprzêtowych:
+        Intel &i386;, &i486;, &pentium;,
+        &pentium;&nbsp;Pro,
+        &celeron;,
+        &pentium;&nbsp;II,
+        &pentium;&nbsp;III,
+        &pentium;&nbsp;4 (b±d¼ inny zgodny),
+        &xeon;, DEC <trademark>Alpha</trademark>
+        oraz Sun &ultrasparc;. Opiera siê on przede wszystkim na oprogramowaniu
+        grupy CSRG z Uniwersytetu Kalifornijskiego w Berkeley, rozszerzonym o dodatkowe
+        elementy z NetBSD, OpenBSD, 386BSD i Free Software Foundation.</para>
+
+      <para>Pocz±wszy od wydania FreeBSD&nbsp;2.0 w koñcu 1994 r., nast±pi³a
+        dramatyczna poprawa wydajno¶ci, mo¿liwo¶ci i stabilno¶ci systemu.
+        <!-- XXX is the rest of this paragraph still true ? -->
+        <!-- Ja tu tylko tlumacze :) -->
+        Najwiêksz± zmian± by³a ca³kowita reformacja systemu wirtualnej pamiêci
+        wraz ze wspó³dzielon± pamiêci± podrêczn± <quote>VM/buffer cache</quote>,
+        która nie tylko wp³ynê³a na wzrost wydajno¶ci ale równie¿ zmniejszenie
+        minimalnego miejsca zajmowanego w pamiêci przez FreeBSD &mdash;
+        5&nbsp;MB jest ju¿ akceptowalnym minimum. Inne rozszerzenia to m.in.
+        kompletna obs³uga klienta i serwera NIS, wsparcie dla transakcji TCP,
+        wdzwanianie na ¿±danie PPP, zintegrowana obs³uga DHCP, usprawniony
+        podsystem SCSI, obs³uga ISDN, ATM, FDDI, Fast i Gigabit Ethernet
+        (100 i 1000&nbsp;Mbit). Usprawniona obs³uga najnowszych kontrolerów
+        Adaptec i tysi±ce poprawionych b³êdów.</para>
+
+      <para>Oprócz podstawowej grupy aplikacji dystrybuowanych wraz z
+        systemem, FreeBSD oferuje kolekcjê tysiêcy dodatkowych programów.
+        W momencie pisania niniejszego tekstu ich lista obejmuje ponad &os.numports;
+        pozycji! Od serwerów http (WWW) poprzez gry po edytory i prawie wszystko
+        pomiêdzy. Ca³a Kolekcja Portów zajmuje oko³o &ports.size; na dysku, przy
+        czym ka¿dy port to zaledwie u³amek oryginalnej objêto¶ci ¼róde³. Takie
+        rozwi±zanie u³atwia man aktualizacjê portów i zdecydowanie zmniejsza
+        zajmowan± przestrzeñ na dysku. Kompilacja portu sprowadza siê do zmiany
+        katalogu na zawieraj±cy port wybranego programu i wpisanie
+        <command>make install</command>. Reszt± zajmuje siê system. Oryginalne
+        pakiety ¼róde³ dla ka¿dego kompilowanego portu pobierane s± dynamicznie z
+        p³yty CDROM b±d¼ lokalnego serwera FTP. Wystarczy zadbaæ o dostateczn±
+        ilo¶æ wolnego miejsca na dysku. Dla osób nie maj±cych ochoty kompilowaæ
+        programów w³asnorêcznie, wiêkszo¶æ portów jest równie¿ dostêpna w
+        skompilowanej postaci jako <quote>pakiety</quote>, które mog± byæ
+        instalowane przy pomocy prostego polecenia <command>pkg_add</command>.
+        Wiêcej informacji o systemie pakietów i portów zawiera <xref
+        linkend="ports">.</para>
+
+      <para>Dodatkowe dokumenty pomocne przy instalacji i u¿ytkowaniu FreeBSD
+        znajduj± siê równie¿ w katalogu <filename>/usr/share/doc</filename>
+        na maszynach z najnowszymi wersjami FreeBSD. Mog± byæ przegl±dane
+        lokalnie za pomoc± przegl±darki internetowej przy wykorzystaniu
+        poni¿szych odno¶ników:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>Podrêczki FreeBSD (ang.)</term>
+
+	  <listitem>
+	    <para><ulink type="html"
+	      url="file://localhost/usr/share/doc/handbook/index.html"><filename>/usr/share/doc/handbook/index.html</filename></ulink></para>
+	  </listitem>
+        </varlistentry>
+      
+        <varlistentry>
+          <term>FAQ FreeBSD (ang.)</term>
+
+	  <listitem>
+	    <para><ulink type="html"
+	      url="file://localhost/usr/share/doc/faq/index.html"><filename>/usr/share/doc/faq/index.html</filename></ulink></para>
+	  </listitem>
+        </varlistentry>
+      </variablelist>
+    
+      <para>G³ówne i najczê¶ciej aktualizowane wersje dokumentów dostêpne
+        s± na stronie <ulink
+	url="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/pl_PL.ISO8859-2/books/handbook/kernelconfig/Makefile b/pl_PL.ISO8859-2/books/handbook/kernelconfig/Makefile
new file mode 100644
index 0000000000..95839d340a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/kernelconfig/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	kernelconfig/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/kernelconfig/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/kernelconfig/chapter.sgml
new file mode 100644
index 0000000000..f0b1569432
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/kernelconfig/chapter.sgml
@@ -0,0 +1,1432 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="kernelconfig">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Jim</firstname>
+	<surname>Mock</surname>
+	<contrib>Updated and restructured by </contrib>
+	<!-- Mar 2000 -->
+      </author>
+    </authorgroup>
+    <authorgroup>
+      <author>
+	<firstname>Jake</firstname>
+	<surname>Hamby</surname>
+	<contrib>Originally contributed by </contrib>
+	<!-- 6 Oct 1995 -->
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Configuring the FreeBSD Kernel</title>
+
+  <sect1 id="kernelconfig-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>building a custom kernel</secondary>
+    </indexterm>
+
+    <para>The kernel is the core of the &os; operating system.  It is
+      responsible for managing memory, enforcing security controls,
+      networking, disk access, and much more.  While more and more of &os;
+      becomes dynamically configurable it is still occasionally necessary to
+      reconfigure and recompile your kernel.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Why you might need to build a custom kernel.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to write a kernel configuration file, or alter an existing
+	  configuration file.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use the kernel configuration file to create and build a
+	  new kernel.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to install the new kernel.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to troubleshoot if things go wrong.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>All of the commands listed within this chapter by way of example
+      should be executed as <username>root</username> in order to
+      succeed.</para>
+  </sect1>
+
+  <sect1 id="kernelconfig-custom-kernel">
+    <title>Why Build a Custom Kernel?</title>
+
+    <para>Traditionally, &os; has had what is called a
+      <quote>monolithic</quote> kernel.  This means that the kernel was one
+      large program, supported a fixed list of devices, and if you wanted to
+      change the kernel's behavior then you had to compile a new kernel, and
+      then reboot your computer with the new kernel.</para>
+
+    <para>Today, &os; is rapidly moving to a model where much of the
+      kernel's functionality is contained in modules which can be
+      dynamically loaded and unloaded from the kernel as necessary.
+      This allows the kernel to adapt to new hardware suddenly
+      becoming available (such as PCMCIA cards in a laptop), or for
+      new functionality to be brought into the kernel that was not
+      necessary when the kernel was originally compiled.  This is
+      known as a modular kernel.</para>
+
+    <para>Despite this, it is still necessary to carry out some static kernel
+      configuration.  In some cases this is because the functionality is so
+      tied to the kernel that it can not be made dynamically loadable.  In
+      others it may simply be because no one has yet taken the time to write a
+      dynamic loadable kernel module for that functionality.</para>
+
+    <para>Building a custom kernel is one of the most important rites of
+      passage nearly every BSD user must endure.  This process, while
+      time consuming, will provide many benefits to your &os; system.
+      Unlike the <filename>GENERIC</filename> kernel, which must support a
+      wide range of hardware, a custom kernel only contains support for
+      <emphasis>your</emphasis> PC's hardware.  This has a number of
+      benefits, such as:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Faster boot time.  Since the kernel will only probe the
+	hardware you have on your system, the time it takes your system to
+	boot can decrease dramatically.</para>
+      </listitem>
+
+      <listitem>
+	<para>Lower memory usage.  A custom kernel often uses less memory
+	  than the <filename>GENERIC</filename> kernel, which is important
+	  because the kernel must always be present in real
+	  memory.  For this reason, a custom kernel is especially useful
+	  on a system with a small amount of RAM.</para>
+      </listitem>
+
+      <listitem>
+	<para>Additional hardware support.  A custom kernel allows you to
+	  add in support for devices which are not
+	  present in the <filename>GENERIC</filename> kernel, such as
+	  sound cards.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="kernelconfig-building">
+    <title>Building and Installing a Custom Kernel</title>
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>building / installing</secondary>
+    </indexterm>
+
+    <para>First, let us take a quick tour of the kernel build directory.
+      All directories mentioned will be relative to the main
+      <filename>/usr/src/sys</filename> directory, which is also
+      accessible through the path name <filename>/sys</filename>.  There are a number of
+      subdirectories here representing different parts of the kernel, but
+      the most important for our purposes are
+      <filename><replaceable>arch</replaceable>/conf</filename>, where you
+      will edit your custom kernel configuration, and
+      <filename>compile</filename>, which is the staging area where your
+      kernel will be built.  <replaceable>arch</replaceable> represents
+      one of <filename>i386</filename>, <filename>alpha</filename>,
+      <filename>amd64</filename>, <filename>ia64</filename>,
+      <filename>powerpc</filename>, <filename>sparc64</filename>, or
+      <filename>pc98</filename> (an alternative development branch of PC
+      hardware, popular in Japan).  Everything inside a particular
+      architecture's directory deals with that architecture only; the rest
+      of the code is machine independent code common to all platforms to which &os; could
+      potentially be ported.  Notice the logical organization of the
+      directory structure, with each supported device, file system, and
+      option in its own subdirectory.</para>
+
+    <para>This chapter assumes that you are using the i386 architecture
+      in the examples.  If this is not the case for your situation,
+      make appropriate adjustments to the path names for your system's
+      architecture.</para>
+
+    <note>
+      <para>If there is <emphasis>not</emphasis> a
+	<filename>/usr/src/sys</filename> directory on your system,
+	then the kernel source has not been installed.  The easiest
+	way to do this is by running
+	<command>sysinstall</command> as
+	<username>root</username>, choosing
+	<guimenuitem>Configure</guimenuitem>, then
+	<guimenuitem>Distributions</guimenuitem>, then
+	<guimenuitem>src</guimenuitem>, then
+	<guimenuitem>sys</guimenuitem>.  If you have an aversion to
+	<application>sysinstall</application> and you have access to
+	an <quote>official</quote> &os; CDROM, then you can also
+	install the source from the command line:</para>
+
+      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+&prompt.root; <userinput>mkdir -p /usr/src/sys</userinput>
+&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput>
+&prompt.root; <userinput>cat /cdrom/src/ssys.[a-d]* | tar -xzvf -</userinput></screen>
+    </note>
+
+    <para>Next, move to the
+      <filename><replaceable>arch</replaceable>/conf</filename> directory
+      and copy the <filename>GENERIC</filename> configuration file to the
+      name you want to give your kernel.  For example:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
+&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen>
+
+    <para>Traditionally, this name is in all capital letters and, if you
+      are maintaining multiple &os; machines with different hardware,
+      it is a good idea to name it after your machine's hostname.  We will
+      call it <filename>MYKERNEL</filename> for the purpose of this
+      example.</para>
+
+    <tip>
+      <para>Storing your kernel configuration file directly under
+	<filename>/usr/src</filename> can be a bad idea.  If you are
+	experiencing problems it can be tempting to just delete
+	<filename>/usr/src</filename> and start again.  After doing this,
+	it usually only takes a few seconds for
+	you to realize that you have deleted your custom kernel
+	configuration file.  Also, do not edit <filename>GENERIC</filename>
+	directly, as it may get overwritten the next time you
+	<link linkend="cutting-edge">update your source tree</link>, and
+	your kernel modifications will be lost.</para>
+
+      <para>You might want to keep your kernel configuration file
+	elsewhere, and then create a symbolic link to the file in
+	the <filename><replaceable>i386</replaceable></filename>
+	directory.</para>
+
+      <para>For example:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput>
+&prompt.root; <userinput>mkdir /root/kernels</userinput>
+&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput>	
+&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen>
+    </tip>
+
+    <para>Now, edit <filename>MYKERNEL</filename> with your favorite text
+      editor.  If you are just starting out, the only editor available
+      will probably be <application>vi</application>, which is too complex to
+      explain here, but is covered well in many books in the <link
+      linkend="bibliography">bibliography</link>.  However, &os; does
+      offer an easier editor called <application>ee</application> which, if
+      you are a beginner, should be your editor of choice.  Feel free to
+      change the comment lines at the top to reflect your configuration or
+      the changes you have made to differentiate it from
+      <filename>GENERIC</filename>.</para>
+    <indexterm><primary>SunOS</primary></indexterm>
+
+    <para>If you have built a kernel under &sunos; or some other BSD
+      operating system, much of this file will be very familiar to you.
+      If you are coming from some other operating system such as DOS, on
+      the other hand, the <filename>GENERIC</filename> configuration file
+      might seem overwhelming to you, so follow the descriptions in the
+      <link linkend="kernelconfig-config">Configuration File</link>
+      section slowly and carefully.</para>
+
+    <note>
+      <para>If you <link
+        linkend="cutting-edge">sync your source tree</link> with the
+        latest sources of the &os; project,
+        be sure to always check the file
+        <filename>/usr/src/UPDATING</filename> before you perform any update
+        steps.  This file describes any important issues or areas
+        requiring special attention within the updated source code.
+        <filename>/usr/src/UPDATING</filename> always matches
+        your version of the &os; source, and is therefore more up to date
+        with new information than this handbook.</para>
+    </note>
+
+    <para>You must now compile the source code for the kernel.  There are two
+      procedures you can use to do this, and the one you will use depends on
+      why you are rebuilding the kernel and the version of &os; that you are
+      running.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>If you have installed <emphasis>only</emphasis> the kernel
+	  source code, use procedure 1.</para>
+      </listitem>
+
+      <listitem>
+	<para>If you are building a new kernel without updating the source
+	  code (perhaps just to add a new option, such as
+	  <literal>IPFIREWALL</literal>) you can use either procedure.</para>
+      </listitem>
+
+      <listitem>
+	<para>If you are rebuilding the kernel as part of a
+          <command>make buildworld</command> process, use procedure 2.
+        </para>
+      </listitem>
+    </itemizedlist>
+    
+    <indexterm>
+      <primary><command>cvsup</command></primary>
+    </indexterm>
+    <indexterm><primary>CTM</primary></indexterm>
+    <indexterm>
+      <primary>CVS</primary>
+      <secondary>anonymous</secondary>
+    </indexterm>
+
+    <para>If you have <emphasis>not</emphasis> upgraded your source
+      tree in any way since the last time you successfully completed
+      a <maketarget>buildworld</maketarget>-<maketarget>installworld</maketarget> cycle
+      (you have not run <application>CVSup</application>,
+      <application>CTM</application>, or used 
+      <application>anoncvs</application>), then it is safe to use the
+      <command>config</command>, <command>make depend</command>,
+      <command>make</command>, <command>make install</command> sequence.
+    </para>
+
+    <procedure>
+      <title>Procedure 1.  Building a Kernel the <quote>Traditional</quote> Way</title>
+      
+      <step>
+	<para>Run &man.config.8; to generate the kernel source code.</para>
+	
+	<screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen>
+      </step>
+
+      <step>
+	<para>Change into the build directory.  &man.config.8; will print
+	  the name of this directory after being run as above.</para>
+
+	<screen>&prompt.root; <userinput>cd ../compile/<replaceable>MYKERNEL</replaceable></userinput></screen>
+      </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>This method of kernel building requires full source files.  If you
+	only installed the kernel source, use the traditional method, as
+	described above.</para>
+    </note>
+
+    <tip>
+      <para>By default, when you build a custom kernel,
+	<emphasis>all</emphasis> kernel modules will be rebuilt as well.
+	If you want to update a kernel faster or to build only custom
+	modules, you should edit <filename>/etc/make.conf</filename>
+	before starting to build the kernel:</para>
+
+      <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting>
+
+      <para>This variable sets up a list of modules to build instead
+	of all of them.  For other variables which you may find useful
+	in the process of building kernel, refer to &man.make.conf.5;
+	manual page.</para>
+    </tip>
+
+    <indexterm>
+      <primary><filename class="directory">/boot/kernel.old</filename></primary>
+    </indexterm> 
+
+    <para>The new kernel will be copied to the <filename
+        class="directory">/boot/kernel</filename> directory as
+      <filename>/boot/kernel/kernel</filename> and the old kernel will be moved to
+      <filename>/boot/kernel.old/kernel</filename>.  Now, shutdown the system and
+      reboot to use your new kernel.  If something goes wrong, there are
+      some <link linkend="kernelconfig-trouble">troubleshooting</link>
+      instructions at the end of this chapter that you may find useful.  Be sure to read the
+      section which explains how to recover in case your new kernel <link
+      linkend="kernelconfig-noboot">does not boot</link>.</para>
+
+    <note>
+      <para>Other files relating to the boot process, such as the boot
+	&man.loader.8; and configuration are stored in
+	<filename>/boot</filename>.  Third party or custom modules
+	can be placed in <filename class="directory">/boot/kernel</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>
+  </sect1>
+
+  <sect1 id="kernelconfig-config">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Joel</firstname>
+	  <surname>Dahl</surname>
+	  <contrib>Updated for &os; 6.X by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>The Configuration File</title>
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>NOTES</secondary>
+    </indexterm>
+    <indexterm><primary>NOTES</primary></indexterm>
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>configuration file</secondary>
+    </indexterm>
+
+    <para>The general format of a configuration file is quite simple.
+      Each line contains a keyword and one or more arguments.  For
+      simplicity, most lines only contain one argument.  Anything
+      following a <literal>#</literal> is considered a comment and
+      ignored.  The following sections describe each keyword, in
+      the order they are listed in <filename>GENERIC</filename>.
+      <anchor
+      id="kernelconfig-options"> For an exhaustive list of architecture
+      dependent options and devices, see the <filename>NOTES</filename>
+      file in the same directory as the <filename>GENERIC</filename> file. For
+      architecture independent options, see
+      <filename>/usr/src/sys/conf/NOTES</filename>.</para>
+
+    <note>
+      <para>To build a file which contains all available options,
+	as normally done for testing purposes, run the following
+	command as <username>root</username>:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf &amp;&amp; make LINT</userinput></screen>
+    </note>
+
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>configuration file</secondary>
+    </indexterm>
+
+    <para>The following is an example of the <filename>GENERIC</filename> kernel
+      configuration file with various additional comments where needed for
+      clarity.  This example should match your copy in
+      <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename>
+      fairly closely.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>machine</secondary>
+    </indexterm>
+
+    <programlisting>machine		i386</programlisting>
+
+    <para>This is the machine architecture.  It must be either
+      <literal>alpha</literal>, <literal>amd64</literal>,
+      <literal>i386</literal>, <literal>ia64</literal>,
+      <literal>pc98</literal>, <literal>powerpc</literal>, or
+      <literal>sparc64</literal>.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>cpu</secondary>
+    </indexterm>
+    <programlisting>cpu          I486_CPU
+cpu          I586_CPU
+cpu          I686_CPU</programlisting>
+
+    <para>The above option specifies the type of CPU you have in your
+      system.  You may have multiple instances of the CPU line (if, for
+      example, you are not sure whether you should use
+      <literal>I586_CPU</literal> or <literal>I686_CPU</literal>),
+      but for a custom kernel it is best to specify only the CPU
+      you have.  If you are unsure of your CPU type, you can check the
+      <filename>/var/run/dmesg.boot</filename> file to view your boot
+      messages.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>ident</secondary>
+    </indexterm>
+
+    <programlisting>ident          GENERIC</programlisting>
+
+    <para>This is the identification of the kernel.  You should change
+      this to whatever you named your kernel,
+      i.e. <literal>MYKERNEL</literal> if you have followed the
+      instructions of the previous examples.  The value you put in the
+      <literal>ident</literal> string will print when you boot up the
+      kernel, so it is useful to give the new kernel a different name if you
+      want to keep it separate from your usual kernel (e.g., you want to
+      build an experimental kernel).</para>
+
+    <programlisting>#To statically compile in device wiring instead of /boot/device.hints
+#hints          "GENERIC.hints"         # Default places to look for devices.</programlisting>
+
+    <para>The &man.device.hints.5; is
+      used to configure options of the device drivers.  The default
+      location that &man.loader.8; will check at boot time is
+      <filename>/boot/device.hints</filename>.  Using the
+      <literal>hints</literal> option you can compile these hints
+      statically into your kernel.  Then there is no need to create a
+      <filename>device.hints</filename> file in
+      <filename>/boot</filename>.</para>
+
+    <!-- XXX: Add a comment here that explains when compiling hints into
+      the kernel is a good idea and why. -->
+
+    <programlisting>makeoptions     DEBUG=-g          # Build kernel with gdb(1) debug symbols</programlisting>
+
+    <para>The normal build process of &os; includes
+      debugging information when building the kernel with the
+      the <option>-g</option> option, which enables debugging
+      information when passed to &man.gcc.1;.  The same can be
+      accomplished by the &man.config.8; <option>-g</option> option, if
+      you are using the <quote>traditional</quote> way for building your
+      kernels (see <xref linkend="kernelconfig-building">
+      for more information).</para>
+
+    <programlisting>options          SCHED_4BSD         # 4BSD scheduler</programlisting>
+
+    <para>The traditional and default system scheduler for &os;.  Keep this.</para>
+
+    <programlisting>options          PREEMPTION         # Enable kernel thread preemption</programlisting>
+
+    <para>Allows threads that are in the kernel to be preempted
+      by higher priority threads.  It helps with interactivity and
+      allows interrupt threads to run sooner rather than waiting.</para>
+
+    <programlisting>options          INET              # InterNETworking</programlisting>
+
+    <para>Networking support.  Leave this in, even if you do not plan to
+      be connected to a network.  Most programs require at least loopback
+      networking (i.e., making network connections within your PC), so
+      this is essentially mandatory.</para>
+
+    <programlisting>options          INET6             # IPv6 communications protocols</programlisting>
+
+    <para>This enables the IPv6 communication protocols.</para>
+
+    <programlisting>options          FFS               # Berkeley Fast Filesystem</programlisting>
+
+    <para>This is the basic hard drive file system.  Leave it in if you
+      boot from the hard disk.</para>
+
+    <programlisting>options          SOFTUPDATES       # Enable FFS Soft Updates support</programlisting>
+
+    <para>This option enables Soft Updates in the kernel, this will
+      help speed up write access on the disks.  Even when this
+      functionality is provided by the kernel, it must be turned on
+      for specific disks.  Review the output from &man.mount.8; to see
+      if Soft Updates is enabled for your system disks.  If you do not
+      see the <literal>soft-updates</literal> option then you will
+      need to activate it using the &man.tunefs.8; (for existing
+      file systems) or &man.newfs.8; (for new file systems)
+      commands.</para>
+
+    <programlisting>options          UFS_ACL           # Support for access control lists</programlisting>
+
+    <para>This option enables kernel support
+      for access control lists.  This relies on the use of extended
+      attributes and <acronym>UFS2</acronym>, and the feature is described
+      in detail in <xref linkend="fs-acl">.  <acronym>ACL</acronym>s are
+      enabled by default and should not be
+      disabled in the kernel if they have been used previously on a file
+      system, as this will remove the access control lists, changing the
+      way files are protected in unpredictable ways.</para>
+
+    <programlisting>options          UFS_DIRHASH       # Improve performance on big directories</programlisting>
+
+    <para>This option includes functionality to speed up disk
+      operations on large directories, at the expense of using
+      additional memory.  You would normally keep this for a large
+      server, or interactive workstation, and remove it if you are
+      using &os; on a smaller system where memory is at a premium and
+      disk access speed is less important, such as a firewall.</para>
+
+    <programlisting>options          MD_ROOT           # MD is a potential root device</programlisting>
+
+    <para>This option enables support for a memory backed virtual disk
+      used as a root device.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>NFS</secondary>
+    </indexterm>
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>NFS_ROOT</secondary>
+    </indexterm>
+    <programlisting>options          NFSCLIENT         # Network Filesystem Client
+options          NFSSERVER         # Network Filesystem Server
+options          NFS_ROOT          # NFS usable as /, requires NFSCLIENT</programlisting>
+
+    <para>The network file system.  Unless you plan to mount partitions
+      from a &unix; file server over TCP/IP, you can comment these
+      out.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>MSDOSFS</secondary>
+    </indexterm>
+    <programlisting>options          MSDOSFS           # MSDOS Filesystem</programlisting>
+
+    <para>The &ms-dos; file system.  Unless you plan to mount a DOS formatted
+      hard drive partition at boot time, you can safely comment this out.
+      It will be automatically loaded the first time you mount a DOS
+      partition, as described above.  Also, the excellent
+      <filename role="package">emulators/mtools</filename> software
+      allows you to access DOS floppies without having to mount and
+      unmount them (and does not require <literal>MSDOSFS</literal> at
+      all).</para>
+
+    <programlisting>options          CD9660            # ISO 9660 Filesystem</programlisting>
+
+    <para>The ISO 9660 file system for CDROMs.  Comment it out if you do
+      not have a CDROM drive or only mount data CDs occasionally (since it
+      will be dynamically loaded the first time you mount a data CD).
+      Audio CDs do not need this file system.</para>
+
+    <programlisting>options          PROCFS            # Process filesystem (requires PSEUDOFS)</programlisting>
+
+    <para>The process file system.  This is a <quote>pretend</quote>
+      file system mounted on <filename>/proc</filename> which allows
+      programs like &man.ps.1; to give you more information on what
+      processes are running.  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>: installs will not mount this file
+      system by default.</para>
+
+    <programlisting>options          PSEUDOFS          # Pseudo-filesystem framework</programlisting>
+
+      <para>6.X kernels making use of <literal>PROCFS</literal> must also
+        include support for <literal>PSEUDOFS</literal>.</para>
+
+    <programlisting>options          GEOM_GPT          # GUID Partition Tables.</programlisting>
+
+    <para>This option brings the ability to have a large number of
+      partitions on a single disk.</para>
+
+    <programlisting>options          COMPAT_43         # Compatible with BSD 4.3 [KEEP THIS!]</programlisting>
+
+    <para>Compatibility with 4.3BSD.  Leave this in; some programs will
+      act strangely if you comment this out.</para>
+
+    <programlisting>options          COMPAT_FREEBSD4   # Compatible with &os;4</programlisting>
+
+    <para>This option is required on &os;&nbsp;5.X &i386; and Alpha systems
+      to support applications compiled on older versions of &os;
+      that use older system call interfaces.  It is recommended that
+      this option be used on all &i386; and Alpha systems that may
+      run older applications; platforms that gained support only in
+      5.X, such as ia64 and &sparc64;, do not require this option.</para>
+
+    <programlisting>options          SCSI_DELAY=5000  # Delay (in ms) before probing SCSI</programlisting>
+
+    <para>This causes the kernel to pause for 5 seconds before probing
+      each SCSI device in your system.  If you only have IDE hard drives,
+      you can ignore this, otherwise you can try to lower this
+      number, to speed up booting.  Of course, if
+      you do this and &os; has trouble recognizing your SCSI devices,
+      you will have to raise it again.</para>
+
+    <programlisting>options          KTRACE            # ktrace(1) support</programlisting>
+
+    <para>This enables kernel process tracing, which is useful in
+      debugging.</para>
+
+    <programlisting>options          SYSVSHM           # SYSV-style shared memory</programlisting>
+
+    <para>This option provides for System&nbsp;V shared memory.  The most
+      common use of this is the XSHM extension in X, which many
+      graphics-intensive programs will automatically take advantage of for
+      extra speed.  If you use X, you will definitely want to include
+      this.</para>
+
+    <programlisting>options          SYSVMSG           # SYSV-style message queues</programlisting>
+
+    <para>Support for System&nbsp;V messages.  This option only adds
+      a few hundred bytes to the kernel.</para>
+
+    <programlisting>options          SYSVSEM           # SYSV-style semaphores</programlisting>
+
+    <para>Support for System&nbsp;V semaphores.  Less commonly used but only
+      adds a few hundred bytes to the kernel.</para>
+
+    <note>
+      <para>The <option>-p</option> option of the &man.ipcs.1; command will
+	list any processes using each of these System&nbsp;V facilities.</para>
+    </note>
+
+    <programlisting>options 	     _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting>
+
+    <para>Real-time extensions added in the 1993 &posix;.  Certain
+      applications in the Ports Collection use these
+      (such as <application>&staroffice;</application>).</para>
+
+    <programlisting>options          KBD_INSTALL_CDEV  # install a CDEV entry in /dev</programlisting>
+
+    <para>This option is related to the keyboard. It installs a CDEV entry
+      in <filename>/dev</filename>.</para>
+
+    <programlisting>options          AHC_REG_PRETTY_PRINT     # Print register bitfields in debug
+                                          # output.  Adds ~128k to driver.
+options          AHD_REG_PRETTY_PRINT     # Print register bitfields in debug
+                                          # output.  Adds ~215k to driver.</programlisting>
+
+    <para>This helps debugging by printing easier register definitions for
+      reading.</para>
+
+    <programlisting>options          ADAPTIVE_GIANT    # Giant mutex is adaptive.</programlisting>
+
+    <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex)
+      that protects a large set of kernel resources.  Today, this is an
+      unacceptable performance bottleneck which is actively being replaced
+      with locks that protect individual resources.  The
+      <literal>ADAPTIVE_GIANT</literal> option causes Giant to be included
+      in the set of mutexes adaptively spun on.  That is, when a thread
+      wants to lock the Giant mutex, but it is already locked by a thread
+      on another CPU, the first thread will keep running and wait for the
+      lock to be released.  Normally, the thread would instead go back to
+      sleep and wait for its next chance to run.  If you are not sure,
+      leave this in.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>SMP</secondary>
+    </indexterm>
+    <programlisting>device          apic               # I/O APIC</programlisting>
+
+    <para>The apic device enables the use of the I/O APIC for interrupt
+      delivery.  The apic device can be used in both UP and SMP kernels, but
+      is required for SMP kernels.  Add <literal>options SMP</literal> to
+      include support for multiple processors.</para>
+
+    <programlisting>device          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          fdc</programlisting>
+
+    <para>This is the floppy drive controller.</para>
+
+    <programlisting># ATA and ATAPI devices
+device          ata</programlisting>
+
+    <para>This driver supports all ATA and ATAPI devices.  You only need
+      one <literal>device ata</literal> line for the kernel to detect all
+      PCI ATA/ATAPI devices on modern machines.</para>
+
+    <programlisting>device          atadisk                 # ATA disk drives</programlisting>
+
+    <para>This is needed along with <literal>device ata</literal> for
+      ATA disk drives.</para>
+
+    <programlisting>device          ataraid                 # ATA RAID drives</programlisting>
+
+    <para>This is needed along with <literal>device ata</literal> for ATA
+      RAID drives.</para>
+
+    <programlisting><anchor id="kernelconfig-atapi">
+device          atapicd                 # ATAPI CDROM drives</programlisting>
+
+    <para>This is needed along with <literal>device ata</literal> for
+      ATAPI CDROM drives.</para>
+
+    <programlisting>device          atapifd                 # ATAPI floppy drives</programlisting>
+
+    <para>This is needed along with <literal>device ata</literal> for
+      ATAPI floppy drives.</para>
+
+    <programlisting>device          atapist                 # ATAPI tape drives</programlisting>
+
+    <para>This is needed along with <literal>device ata</literal> for
+      ATAPI tape drives.</para>
+
+    <programlisting>options         ATA_STATIC_ID           # Static device numbering</programlisting>
+
+    <para>This makes the controller number static; without this,
+      the device numbers are dynamically allocated.</para>
+
+    <programlisting># SCSI Controllers
+device          ahb        # EISA AHA1742 family
+device          ahc        # AHA2940 and onboard AIC7xxx devices
+device          ahd        # AHA39320/29320 and onboard AIC79xx devices
+device          amd        # AMD 53C974 (Teckram DC-390(T))
+device          isp        # Qlogic family
+#device         ispfw      # Firmware for QLogic HBAs- normally a module
+device          mpt        # LSI-Logic MPT-Fusion
+#device         ncr        # NCR/Symbios Logic
+device          sym        # NCR/Symbios Logic (newer chipsets)
+device          trm        # Tekram DC395U/UW/F DC315U adapters
+
+device          adv        # Advansys SCSI adapters
+device          adw        # Advansys wide SCSI adapters
+device          aha        # Adaptec 154x SCSI adapters
+device          aic        # Adaptec 15[012]x SCSI adapters, AIC-6[23]60.
+device          bt         # Buslogic/Mylex MultiMaster SCSI adapters
+
+device          ncv        # NCR 53C500
+device          nsp        # Workbit Ninja SCSI-3
+device          stg        # TMC 18C30/18C50</programlisting>
+
+    <para>SCSI controllers.  Comment out any you do not have in your
+      system.  If you have an IDE only system, you can remove these
+      altogether.</para>
+
+    <programlisting># SCSI peripherals
+device          scbus      # SCSI bus (required for SCSI)
+device          ch         # SCSI media changers
+device          da         # Direct Access (disks)
+device          sa         # Sequential Access (tape etc)
+device          cd         # CD
+device          pass       # Passthrough device (direct SCSI access)
+device          ses        # SCSI Environmental Services (and SAF-TE)</programlisting>
+
+    <para>SCSI peripherals.  Again, comment out any you do not have, or if
+      you have only IDE hardware, you can remove them completely.</para>
+
+    <note>
+      <para>The USB &man.umass.4; driver and a few other drivers use
+	the SCSI subsystem even though they are not real SCSI devices.
+	Therefore make sure not to remove SCSI support, if any such
+	drivers are included in the kernel configuration.</para>
+    </note>
+
+    <programlisting># RAID controllers interfaced to the SCSI subsystem
+device          amr        # AMI MegaRAID
+device          arcmsr     # Areca SATA II RAID
+device          asr        # DPT SmartRAID V, VI and Adaptec SCSI RAID
+device          ciss       # Compaq Smart RAID 5*
+device          dpt        # DPT Smartcache III, IV - See NOTES for options
+device          hptmv      # Highpoint RocketRAID 182x
+device          rr232x     # Highpoint RocketRAID 232x
+device          iir        # Intel Integrated RAID
+device          ips        # IBM (Adaptec) ServeRAID
+device          mly        # Mylex AcceleRAID/eXtremeRAID
+device          twa        # 3ware 9000 series PATA/SATA RAID
+
+# RAID controllers
+device          aac        # Adaptec FSA RAID
+device          aacp       # SCSI passthrough for aac (requires CAM)
+device          ida        # Compaq Smart RAID
+device          mfi        # LSI MegaRAID SAS
+device          mlx        # Mylex DAC960 family
+device          pst        # Promise Supertrak SX6000
+device          twe        # 3ware ATA RAID</programlisting>
+
+    <para>Supported RAID controllers.  If you do not have any of these,
+      you can comment them out or remove them.</para>
+
+    <programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse
+device          atkbdc     # AT keyboard controller</programlisting>
+
+    <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O
+      services for the AT keyboard and PS/2 style pointing devices.  This
+      controller is required by the keyboard driver
+      (<literal>atkbd</literal>) and the PS/2 pointing device driver
+      (<literal>psm</literal>).</para>
+
+    <programlisting>device          atkbd      # AT keyboard</programlisting>
+
+    <para>The <literal>atkbd</literal> driver, together with
+      <literal>atkbdc</literal> controller, provides access to the AT 84
+      keyboard or the AT enhanced keyboard which is connected to the AT
+      keyboard controller.</para>
+
+    <programlisting>device          psm        # PS/2 mouse</programlisting>
+
+    <para>Use this device if your mouse plugs into the PS/2 mouse
+      port.</para>
+
+    <programlisting>device          kbdmux        # keyboard multiplexer</programlisting>
+
+    <para>Basic support for keyboard multiplexing.</para>
+
+    <programlisting>device          vga        # VGA video card driver</programlisting>
+
+    <para>The video card driver.</para>
+
+    <programlisting>
+device          splash     # Splash screen and screen saver support</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          sc</programlisting>
+
+    <para><literal>sc</literal> is the default console driver and
+      resembles a SCO console.  Since most full-screen programs access the
+      console through a terminal database library like
+      <filename>termcap</filename>, it should not matter whether you use
+      this or <literal>vt</literal>, the <literal>VT220</literal>
+      compatible console driver.  When you log in, set your
+      <envar>TERM</envar> variable to <literal>scoansi</literal> if
+      full-screen programs have trouble running under this console.</para>
+
+    <programlisting># Enable this for the pcvt (VT220 compatible) console driver
+#device          vt
+#options         XSERVER          # support for X server on a vt console
+#options         FAT_CURSOR       # start with block cursor</programlisting>
+
+    <para>This is a VT220-compatible console driver, backward compatible to
+      VT100/102.  It works well on some laptops which have hardware
+      incompatibilities with <literal>sc</literal>.  Also set your
+      <envar>TERM</envar> variable to <literal>vt100</literal> or
+      <literal>vt220</literal> when you log in.  This driver might also
+      prove useful when connecting to a large number of different machines
+      over the network, where <filename>termcap</filename> or
+      <filename>terminfo</filename> entries for the <literal>sc</literal>
+      device are often not available &mdash; <literal>vt100</literal>
+      should be available on virtually any platform.</para>
+
+    <programlisting>device          agp</programlisting>
+
+    <para>Include this if you have an AGP card in the system.  This
+      will enable support for AGP, and AGP GART for boards which
+      have these features.</para>
+
+    <indexterm>
+      <primary>APM</primary>
+    </indexterm>
+
+    <programlisting># Power management support (see NOTES for more options)
+#device          apm</programlisting>
+
+    <para>Advanced Power Management support.  Useful for laptops,
+      although in &os; 5.X and above this is disabled in
+      <filename>GENERIC</filename> by default.</para>
+
+    <programlisting># Add suspend/resume support for the i8254.
+device           pmtimer</programlisting>
+
+    <para>Timer device driver for power management events, such as APM and
+      ACPI.</para>
+
+    <programlisting># PCCARD (PCMCIA) support
+# PCMCIA and cardbus bridge support
+device          cbb               # cardbus (yenta) bridge
+device          pccard            # PC Card (16-bit) bus
+device          cardbus           # CardBus (32-bit) bus</programlisting>
+
+    <para>PCMCIA support.  You want this if you are using a
+      laptop.</para>
+
+    <programlisting># Serial (COM) ports
+device          sio               # 8250, 16[45]50 based serial ports</programlisting>
+
+    <para>These are the serial ports referred to as
+      <devicename>COM</devicename> ports in the &ms-dos;/&windows;
+      world.</para>
+
+    <note>
+      <para>If you have an internal modem on <devicename>COM4</devicename>
+	and a serial port at <devicename>COM2</devicename>, you will have
+	to change the IRQ of the modem to 2 (for obscure technical reasons,
+	IRQ2 = IRQ 9) in order to access it
+	from &os;.  If you have a multiport serial card, check the
+	manual page for &man.sio.4; for more information on the proper
+	values to add to your <filename>/boot/device.hints</filename>.
+	Some video cards (notably those based on
+	S3 chips) use IO addresses in the form of
+	<literal>0x*2e8</literal>, and since many cheap serial cards do
+	not fully decode the 16-bit IO address space, they clash with
+	these cards making the <devicename>COM4</devicename> port
+	practically unavailable.</para>
+
+      <para>Each serial port is required to have a unique IRQ (unless you
+        are using one of the multiport cards where shared interrupts are
+	supported), so the default IRQs for <devicename>COM3</devicename>
+	and <devicename>COM4</devicename> cannot be used.</para>
+    </note>
+
+    <programlisting># Parallel port
+device          ppc</programlisting>
+
+    <para>This is the ISA-bus parallel port interface.</para>
+
+    <programlisting>device          ppbus      # Parallel port bus (required)</programlisting>
+
+    <para>Provides support for the parallel port bus.</para>
+
+    <programlisting>device          lpt        # Printer</programlisting>
+
+    <para>Support for parallel port printers.</para>
+
+    <note>
+      <para>All three of the above are required to enable parallel printer
+	support.</para>
+    </note>
+
+    <programlisting>device          plip       # TCP/IP over parallel</programlisting>
+
+    <para>This is the driver for the parallel network interface.</para>
+
+    <programlisting>device          ppi        # Parallel port interface device</programlisting>
+
+    <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284
+      I/O.</para>
+
+    <programlisting>#device         vpo        # Requires scbus and da</programlisting>
+
+    <indexterm><primary>zip drive</primary></indexterm>
+    <para>This is for an Iomega Zip drive.  It requires
+      <literal>scbus</literal> and <literal>da</literal> support.  Best
+      performance is achieved with ports in EPP 1.9 mode.</para>
+
+    <programlisting>#device         puc</programlisting>
+
+    <para>Uncomment this device if you have a <quote>dumb</quote> serial
+      or parallel PCI card that is supported by the &man.puc.4; glue
+      driver.</para>
+
+    <programlisting># PCI Ethernet NICs.
+device          de         # DEC/Intel DC21x4x (<quote>Tulip</quote>)
+device          em         # Intel PRO/1000 adapter Gigabit Ethernet Card
+device          ixgb       # Intel PRO/10GbE Ethernet Card
+device          txp        # 3Com 3cR990 (<quote>Typhoon</quote>)
+device          vx         # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting>
+
+    <para>Various PCI network card drivers.  Comment out or remove any of
+      these not present in your system.</para>
+
+    <programlisting># PCI Ethernet NICs that use the common MII bus controller code.
+# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs!
+device          miibus     # MII bus support</programlisting>
+
+    <para>MII bus support is required for some PCI 10/100 Ethernet NICs,
+      namely those which use MII-compliant transceivers or implement
+      transceiver control interfaces that operate like an MII.  Adding
+      <literal>device miibus</literal> to the kernel config pulls in
+      support for the generic miibus API and all of the PHY drivers,
+      including a generic one for PHYs that are not specifically handled
+      by an individual driver.</para>
+
+    <programlisting>device          bce        # Broadcom BCM5706/BCM5708 Gigabit Ethernet
+device          bfe        # Broadcom BCM440x 10/100 Ethernet
+device          bge        # Broadcom BCM570xx Gigabit Ethernet
+device          dc         # DEC/Intel 21143 and various workalikes
+device          fxp        # Intel EtherExpress PRO/100B (82557, 82558)
+device          lge        # Level 1 LXT1001 gigabit ethernet
+device          nge        # NatSemi DP83820 gigabit ethernet
+device          nve        # nVidia nForce MCP on-board Ethernet Networking
+device          pcn        # AMD Am79C97x PCI 10/100 (precedence over 'lnc')
+device          re         # RealTek 8139C+/8169/8169S/8110S
+device          rl         # RealTek 8129/8139
+device          sf         # Adaptec AIC-6915 (<quote>Starfire</quote>)
+device          sis        # Silicon Integrated Systems SiS 900/SiS 7016
+device          sk         # SysKonnect SK-984x &amp; SK-982x gigabit Ethernet
+device          ste        # Sundance ST201 (D-Link DFE-550TX)
+device          ti         # Alteon Networks Tigon I/II gigabit Ethernet
+device          tl         # Texas Instruments ThunderLAN
+device          tx         # SMC EtherPower II (83c170 <quote>EPIC</quote>)
+device          vge        # VIA VT612x gigabit ethernet
+device          vr         # VIA Rhine, Rhine II
+device          wb         # Winbond W89C840F
+device          xl         # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting>
+
+    <para>Drivers that use the MII bus controller code.</para>
+
+    <programlisting># ISA Ethernet NICs.  pccard NICs included.
+device          cs         # Crystal Semiconductor CS89x0 NIC
+# 'device ed' requires 'device miibus'
+device          ed         # NE[12]000, SMC Ultra, 3c503, DS8390 cards
+device          ex         # Intel EtherExpress Pro/10 and Pro/10+
+device          ep         # Etherlink III based cards
+device          fe         # Fujitsu MB8696x based cards
+device          ie         # EtherExpress 8/16, 3C507, StarLAN 10 etc.
+device          lnc        # NE2100, NE32-VL Lance Ethernet cards
+device          sn         # SMC's 9000 series of Ethernet chips
+device          xe         # Xircom pccard Ethernet
+
+# ISA devices that use the old ISA shims
+#device         le</programlisting>
+
+    <para>ISA Ethernet drivers.  See
+      <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename> for details
+of which cards are
+      supported by which driver.</para>
+
+    <programlisting># Wireless NIC cards
+device          wlan       # 802.11 support
+device          an         # Aironet 4500/4800 802.11 wireless NICs.
+device          awi        # BayStack 660 and others
+device          ral        # Ralink Technology RT2500 wireless NICs.
+device          wi         # WaveLAN/Intersil/Symbol 802.11 wireless NICs.
+#device         wl         # Older non 802.11 Wavelan wireless NIC.</programlisting>
+
+    <para>Support for various wireless cards.</para>
+
+    <programlisting># Pseudo devices
+device   loop          # Network loopback</programlisting>
+
+    <para>This is the generic loopback device for TCP/IP.  If you telnet
+      or FTP to <hostid>localhost</hostid> (a.k.a. <hostid
+      role="ipaddr">127.0.0.1</hostid>) it will come back at you through
+      this device.  This is <emphasis>mandatory</emphasis>.</para>
+
+    <programlisting>device   random        # Entropy device</programlisting>
+
+    <para>Cryptographically secure random number generator.</para>
+
+    <programlisting>device   ether         # Ethernet support</programlisting>
+
+    <para><literal>ether</literal> is only needed if you have an Ethernet
+      card.  It includes generic Ethernet protocol code.</para>
+
+    <programlisting>device   sl            # Kernel SLIP</programlisting>
+
+    <para><literal>sl</literal> is for SLIP support.  This has been almost
+      entirely supplanted by PPP, which is easier to set up, better suited
+      for modem-to-modem connection, and more powerful.</para>
+
+    <programlisting>device   ppp           # Kernel PPP</programlisting>
+
+    <para>This is for kernel PPP support for dial-up connections.  There
+      is also a version of PPP implemented as a userland application that
+      uses <literal>tun</literal> and offers more flexibility and features
+      such as demand dialing.</para>
+
+    <programlisting>device   tun           # Packet tunnel.</programlisting>
+
+    <para>This is used by the userland PPP software.
+      See
+      the <link linkend="userppp">PPP</link> section of this book for more
+      information.</para>
+
+    <programlisting><anchor id="kernelconfig-ptys">
+device   pty           # Pseudo-ttys (telnet etc)</programlisting>
+
+    <para>This is a <quote>pseudo-terminal</quote> or simulated login port.
+      It is used by incoming <command>telnet</command> and
+      <command>rlogin</command> sessions,
+      <application>xterm</application>, and some other applications such
+      as <application>Emacs</application>.</para>
+
+    <programlisting>device   md            # Memory <quote>disks</quote></programlisting>
+
+    <para>Memory disk pseudo-devices.</para>
+
+    <programlisting>device   gif           # IPv6 and IPv4 tunneling</programlisting>
+
+    <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling,
+      IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling.  The
+      <literal>gif</literal> device is
+      <quote>auto-cloning</quote>, and will create device nodes as
+      needed.</para>
+
+    <programlisting>device   faith         # IPv6-to-IPv4 relaying (translation)</programlisting>
+
+    <para>This pseudo-device captures packets that are sent to it and
+      diverts them to the IPv4/IPv6 translation daemon.</para>
+
+    <programlisting># The `bpf' device enables the Berkeley Packet Filter.
+# Be aware of the administrative consequences of enabling this!
+# Note that 'bpf' is required for DHCP.
+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 &man.bpf.4; device is also used by
+	&man.dhclient.8; to obtain the IP address of the default router
+	(gateway) and so on.  If you use DHCP, leave this
+	uncommented.</para>
+    </note>
+
+    <programlisting># USB support
+device          uhci          # UHCI PCI-&gt;USB interface
+device          ohci          # OHCI PCI-&gt;USB interface
+#device         ehci          # EHCI PCI-&gt;USB interface (USB 2.0)
+device          usb           # USB Bus (required)
+#device         udbp          # USB Double Bulk Pipe devices
+device          ugen          # Generic
+device          uhid          # <quote>Human Interface Devices</quote>
+device          ukbd          # Keyboard
+device          ulpt          # Printer
+device          umass         # Disks/Mass storage - Requires scbus and da
+device          ums           # Mouse
+device          urio          # Diamond Rio 500 MP3 player
+device          uscanner      # Scanners
+# USB Ethernet, requires mii
+device          aue           # ADMtek USB Ethernet
+device          axe           # ASIX Electronics USB Ethernet
+device          cdce          # Generic USB over Ethernet
+device          cue           # CATC USB Ethernet
+device          kue           # Kawasaki LSI USB Ethernet
+device          rue           # RealTek RTL8150 USB Ethernet</programlisting>
+
+    <para>Support for various USB devices.</para>
+
+    <programlisting># FireWire support
+device          firewire      # FireWire bus code
+device          sbp           # SCSI over FireWire (Requires scbus and da)
+device          fwe           # Ethernet over FireWire (non-standard!)</programlisting>
+
+    <para>Support for various Firewire devices.</para>
+
+    <para>For more information and additional devices supported by
+      &os;, see
+      <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>.</para>
+
+      <sect2>
+        <title>Large Memory Configurations (<acronym>PAE</acronym>)</title>
+	<indexterm>
+	  <primary>Physical Address Extensions
+	    (<acronym>PAE</acronym>)</primary>
+	  <secondary>large memory</secondary>
+	</indexterm>
+
+	<para>Large memory configuration machines require access to
+	  more than the 4 gigabyte limit on User+Kernel Virtual
+	  Address (<acronym>KVA</acronym>) space.  Due to this
+	  limitation, Intel added support for 36-bit physical address
+	  space access in the &pentium; Pro and later line of CPUs.</para>
+	
+	<para>The Physical Address Extension (<acronym>PAE</acronym>)
+	  capability of the &intel; &pentium; Pro and later CPUs
+	  allows memory configurations of up to 64 gigabytes.
+	  &os; provides support for this capability via the
+	  <option>PAE</option> kernel configuration option, available
+	  in all current release versions of &os;.  Due to
+	  the limitations of the Intel memory architecture, no distinction
+	  is made for memory above or below 4 gigabytes.  Memory allocated
+	  above 4 gigabytes is simply added to the pool of available
+	  memory.</para>
+
+	<para>To enable <acronym>PAE</acronym> support in the kernel,
+	  simply add the following line to your kernel configuration
+	  file:</para>
+	
+	<programlisting>options		    PAE</programlisting>
+
+	<note>
+	  <para>The <acronym>PAE</acronym> support in &os; is only
+	    available for &intel; IA-32 processors.  It should also be
+	    noted, that the <acronym>PAE</acronym> support in &os; has
+	    not received wide testing, and should be considered beta
+	    quality compared to other stable features of &os;.</para>
+	</note>
+
+	<para><acronym>PAE</acronym> support in &os; has a few limitations:</para>
+	
+	<itemizedlist>
+	  <listitem>
+	    <para>A process is not able to access more than 4
+	      gigabytes of VM space.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para><acronym>KLD</acronym> modules cannot be loaded into
+	      a <acronym>PAE</acronym> enabled kernel, due to the
+	      differences in the build framework of a module and the
+	      kernel.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Device drivers that do not use the &man.bus.dma.9;
+	      interface will cause data corruption in a
+	      <acronym>PAE</acronym> enabled kernel and are not
+	      recommended for use.  For this reason, a
+	      <filename>PAE</filename> kernel
+	      configuration file is provided in &os; which
+	      excludes all drivers not known to work in a <acronym>PAE</acronym> enabled
+	      kernel.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Some system tunables determine memory resource usage
+	      by the amount of available physical memory.  Such
+	      tunables can unnecessarily over-allocate due to the
+	      large memory nature of a <acronym>PAE</acronym> system.
+	      One such example is the <option>kern.maxvnodes</option>
+	      sysctl, which controls the maximum number of vnodes allowed
+	      in the kernel.  It is advised to adjust this and other
+	      such tunables to a reasonable value.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>It might be necessary to increase the kernel virtual
+	      address (<acronym>KVA</acronym>) space or to reduce the
+	      amount of specific kernel resource that is heavily used
+	      (see above) in order to avoid <acronym>KVA</acronym>
+	      exhaustion.  The <option>KVA_PAGES</option> kernel option
+	      can be used for increasing the
+	      <acronym>KVA</acronym> space.</para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>For performance and stability concerns, it is advised to
+	  consult the &man.tuning.7; manual page.  The &man.pae.4;
+	  manual page contains up-to-date information on &os;'s
+	  <acronym>PAE</acronym> support.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="kernelconfig-trouble">
+    <title>If Something Goes Wrong</title>
+
+    <para>There are five categories of trouble that can occur when
+      building a custom kernel.  They are:</para>
+
+    <variablelist>
+      <varlistentry>
+	<term><command>config</command> fails:</term>
+
+	<listitem>
+	  <para>If the &man.config.8; command fails when you
+	    give it your kernel description, you have probably made a
+	    simple error somewhere.  Fortunately,
+	    &man.config.8; will print the line number that it
+	    had trouble with, so that you can quickly locate the line
+	    containing the error.  For example, if you see:</para>
+
+	  <screen>config: line 17: syntax error</screen>
+
+	  <para>Make sure the
+	    keyword is typed correctly by comparing it to the
+	    <filename>GENERIC</filename> kernel or another
+	    reference.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term><command>make</command> fails:</term>
+
+	<listitem>
+	  <para>If the <command>make</command> command fails, it usually
+	    signals an error in your kernel description which is not severe
+	    enough for &man.config.8; to catch.  Again, look
+	    over your configuration, and if you still cannot resolve the
+	    problem, send mail to the &a.questions; with your kernel
+	    configuration, and it should be diagnosed quickly.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>The kernel does not boot:<anchor
+	  id="kernelconfig-noboot"></term>
+
+	<listitem>
+	  <para>If your new kernel does not boot, or fails to
+	    recognize your devices, do not panic!  Fortunately, &os; has
+	    an excellent mechanism for recovering from incompatible
+	    kernels.  Simply choose the kernel you want to boot from at
+	    the &os; boot loader. You can access this when the system
+	    boot menu appears.  Select the <quote>Escape to a loader
+	    prompt</quote> option, number six.  At the prompt, type
+	    <command>unload kernel</command>
+            and then type
+	    <command>boot /boot/<replaceable>kernel.old</replaceable>/kernel</command>,
+            or the filename of any other kernel that will boot properly.
+            When reconfiguring a kernel, it is always a good idea to keep
+            a kernel that is known to work on hand.</para>
+
+	  <para>After booting with a good kernel you can check over your
+	    configuration file and try to build it again.  One helpful
+	    resource is the <filename>/var/log/messages</filename> file
+	    which records, among other things, all of the kernel messages
+	    from every successful boot.  Also, the &man.dmesg.8; command
+	    will print the kernel messages from the current boot.</para>
+
+	  <note>
+	    <para>If you are having trouble building a kernel, make sure
+	      to keep a <filename>GENERIC</filename>, or some other kernel
+	      that is known to work on hand as a different name that will
+	      not get erased on the next build.  You cannot rely on
+	      <filename>kernel.old</filename> because when installing a
+	      new kernel, <filename>kernel.old</filename> is overwritten
+	      with the last installed kernel which may be non-functional.
+	      Also, as soon as possible, move the working kernel to the
+	      proper <filename class="directory">/boot/kernel</filename>
+	      location or commands such
+	      as &man.ps.1; may not work properly.  To do this, simply
+	      rename the directory containing the good kernel:</para>
+
+	    <screen>&prompt.root; <userinput>mv /boot/kernel /boot/kernel.bad</userinput>
+&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen>
+
+	  </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 -CURRENT kernel on a -RELEASE, many system-status
+	    commands like &man.ps.1; and &man.vmstat.8; will not work any
+	    more.  You should <link linkend="makeworld">recompile and install
+	    a world</link> built with the same version of the source tree as
+	    your kernel.  This is one reason it is
+	    not normally a good idea to use a different version of the
+	    kernel from the rest of the operating system.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </sect1>
+</chapter>
+
+<!-- 
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/l10n/Makefile b/pl_PL.ISO8859-2/books/handbook/l10n/Makefile
new file mode 100644
index 0000000000..c6741a2341
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/l10n/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	l10n/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/l10n/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/l10n/chapter.sgml
new file mode 100644
index 0000000000..8acb937c50
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/l10n/chapter.sgml
@@ -0,0 +1,940 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="l10n">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Andrey</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 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 Window System 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 id="l10n-basics">
+    <title>The Basics</title>
+
+    <sect2>
+      <title>What Is I18N/L10N?</title>
+    <indexterm>
+      <primary>internationalization</primary>
+      <see>localization</see>
+    </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 &unix; like systems), 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" pgwide="1">
+	<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="&url.base;/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;), e.g.
+	    ISO8859-1, ISO8859-15, KOI8-R, CP437.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Wide or multibyte encodings, e.g. 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>&os; 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</primary><secondary>BIG-5 encoding</secondary></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>
+
+	    <para>Before changing users Login Classes execute
+	      the following command</para>
+
+	    <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
+
+	    <para>to make new configuration in
+	      <filename>/etc/login.conf</filename> visible to the system.</para>
+
+	    <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 shell 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
+	<command>sysinstall</command> (<command>/stand/sysinstall</command>
+	in &os; versions older than 5.2).
+	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 &os;, add the following line to
+	<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 are
+	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" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>Character Set</entry>
+	      <entry>Terminal Type</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>ISO8859-1 or ISO8859-15</entry>
+	      <entry><literal>cons25l1</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry>ISO8859-2</entry>
+	      <entry><literal>cons25l2</literal></entry>
+	    </row>
+
+	    <row>
+	      <entry>ISO8859-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" pgwide="1">
+	<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/kon2-16dot</filename> or
+	        <filename role="package">japanese/mule-freewnn</filename></entry>
+	    </row>
+
+	    <row>
+	      <entry>Korean</entry>
+	      <entry><filename role="package">korean/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.x.org/">&xorg;
+	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 <application>&xorg;</application> server
+	  (<filename role="package">x11-servers/xorg-server</filename>)
+	  or <application>&xfree86;</application> server
+	  (<filename role="package">x11-servers/XFree86-4-Server</filename>),
+	  then 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
+	information 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 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</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>Add the following line
+	      to your <filename>/etc/rc.conf</filename> file:</para>
+
+	    <programlisting>mousechar_start=3</programlisting>
+	  </listitem>
+
+	  <listitem>
+	    <para>Also, 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>The option <option>-L</option> selects the locale name
+	  used, and <option>-W</option> sets the character conversion
+	  table.  To use the <option>-W</option> option, be sure to
+	  mount <filename>/usr</filename> before the &ms-dos; partition
+	  because the conversion tables are located in
+	  <filename>/usr/libdata/msdosfs</filename>.  For more
+	  information, see the &man.mount.msdos.8; manual
+	  page.</para>
+      </sect3>
+
+      <sect3>
+	<title>X11 Setup</title>
+
+	<orderedlist>
+	  <listitem>
+	    <para>Do <link linkend="setting-locale">non-X locale
+	      setup</link> first as described.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>If you use <application>&xorg;</application>,
+	    install
+	    <filename role="package">x11-fonts/xorg-fonts-cyrillic</filename>
+	    package.</para>
+
+	    <para>Check the <literal>"Files"</literal> section
+	      in your <filename>/etc/X11/xorg.conf</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>xorg.conf</filename> file.</para>
+
+	    <programlisting>Option "XkbLayout"   "us,ru"
+Option "XkbOptions"  "grp:toggle"</programlisting>
+
+	    <para>Also make sure that <literal>XkbDisable</literal> is
+	      turned off (commented out) there.</para>
+
+	    <para>For <literal>grp:caps_toggle</literal>
+	    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). For <literal>grp:toggle</literal>
+	    the RUS/LAT switch will be <keycap>Right Alt</keycap>.
+	    <literal>grp:caps_toggle</literal> does not work in
+	    <application>&xorg;</application> for unknown reason.</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>xorg.conf</filename> file.</para>
+
+	<programlisting>Option "XkbVariant" ",winkeys"</programlisting>
+
+	    <note>
+	      <para>The Russian XKB keyboard may not work with non-localized
+		applications.</para>
+	    </note>
+	  </listitem>
+	</orderedlist>
+	<note>
+	  <para>Minimally localized applications
+	    should call a <function>XtSetLanguageProc (NULL, NULL,
+	    NULL);</function> function early in the program.</para>
+	  <para>See <ulink
+	    url="http://koi8.pp.ru/xwin.html">
+	    KOI8-R for X Window</ulink> for more instructions on
+	    localizing X11 applications.</para>
+	</note>
+      </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 Chinese HOWTO for
+	FreeBSD at <ulink url="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/"></ulink>
+	using many Chinese ports.
+	Current editor for the <literal>FreeBSD Chinese HOWTO</literal> is
+        Shen Chuan-Hsing <email>statue@freebsd.sinica.edu.tw</email>.
+      </para>
+
+      <para>Chuan-Hsing Shen <email>statue@freebsd.sinica.edu.tw</email> has
+	created the <ulink url="http://netlab.cse.yzu.edu.tw/~statue/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://freebsd.csie.nctu.edu.tw/pub/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/"></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/"></ulink>,
+	and for Korean, refer to
+	<ulink url="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="&url.base;/index.html">main site</ulink> or in
+	<filename>/usr/share/doc</filename>.</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/pl_PL.ISO8859-2/books/handbook/linuxemu/Makefile b/pl_PL.ISO8859-2/books/handbook/linuxemu/Makefile
new file mode 100644
index 0000000000..37adfa9af6
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/linuxemu/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	linuxemu/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/linuxemu/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/linuxemu/chapter.sgml
new file mode 100644
index 0000000000..60624c3e77
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/linuxemu/chapter.sgml
@@ -0,0 +1,3357 @@
+<!--
+     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 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>&staroffice;</application>,
+      the Linux version of <application>&netscape;</application>,
+      <application>&adobe;&nbsp;&acrobat;</application>,
+      <application><trademark class="registered">RealPlayer</trademark></application>,
+      <application><trademark>VMware</trademark></application>,
+      <application>&oracle;</application>,
+      <application><trademark class="registered">WordPerfect</trademark></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>
+
+    <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 &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 typing the
+      following as <username>root</username>:</para>
+
+    <screen>&prompt.root; <userinput>kldload linux</userinput></screen>
+
+    <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>COMPAT_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 COMPAT_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 type="html" url="file://localhost/usr/ports/">Ports Collection</ulink>.
+	  Simply do the following:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base-fc4</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>
+
+	<note><para>There may be multiple versions of the <filename
+	  role="package">emulators/linux_base</filename> port available,
+	  corresponding to different versions of various Linux distributions.
+	  You should install the port most closely resembling the
+	  requirements of the Linux applications you would like to
+	  install.</para></note>
+
+      </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 unnecessary 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>Boris</firstname>
+	  <surname>Hollas</surname>
+	  <contrib>Updated for Mathematica 5.X 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; 5.X</application> onto
+      a FreeBSD system.</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/"></ulink>.</para>
+
+    <sect2>
+      <title>Running the &mathematica; Installer</title>
+
+      <para>First, you have to tell &os; that
+	<application>&mathematica;</application>'s Linux
+	binaries use the Linux ABI.  The easiest way to do so is to
+	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 &os; assume that unbranded ELF binaries
+	use the Linux ABI and so you should be able to run the
+	installer straight from the CDROM.</para>
+
+      <para>Now, copy the file <filename>MathInstaller</filename> to
+	your hard drive:</para>
+
+      <screen>&prompt.root; <userinput>mount /cdrom</userinput>
+&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen>
+
+      <para>and in this file, replace <literal>/bin/sh</literal> in
+	the first line by <literal>/compat/linux/bin/sh</literal>.
+	This makes sure that the installer is executed by the Linux
+	version of &man.sh.1;.  Next, replace all occurrences of
+	<literal>Linux)</literal> by <literal>FreeBSD)</literal> with
+	a text editor or the script below in the next section.  This
+	tells the <application>&mathematica;</application> installer,
+	who calls <command>uname -s</command> to determine the
+	operating system, to treat &os; as a Linux-like operating
+	system.  Invoking <command>MathInstaller</command> will now
+	install <application>&mathematica;</application>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Modifying the &mathematica; Executables</title>
+
+      <para>The shell scripts that
+	<application>&mathematica;</application> created during
+	installation have to be modified before you can use them.  If
+	you chose <filename role="directory">/usr/local/bin</filename>
+	as the directory to place the
+	<application>&mathematica;</application> executables in, you
+	will find symlinks in this directory to files called
+	<filename>math</filename>, <filename>mathematica</filename>,
+	<filename>Mathematica</filename>, and
+	<filename>MathKernel</filename>.  In each of these, replace
+	<literal>Linux)</literal> by <literal>FreeBSD)</literal> with
+	a text editor or the following shell script:</para>
+
+      <programlisting>#!/bin/sh
+cd /usr/local/bin
+for i in math mathematica Mathematica MathKernel
+  do sed 's/Linux)/FreeBSD)/g' $i &gt; $i.tmp
+  sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp &gt; $i
+  rm $i.tmp
+  chmod a+x $i
+done</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Obtaining Your &mathematica; Password</title>
+
+      <indexterm>
+	<primary>Ethernet</primary>
+	<secondary>MAC address</secondary>
+      </indexterm>
+
+      <para>When you start <application>&mathematica;</application>
+	for the first time, you will be asked for a password.  If you
+	have not yet obtained a password from Wolfram, run the program
+	<command>mathinfo</command> in the installation directory to
+	obtain your <quote>machine ID</quote>.  This machine ID is
+	based solely on the MAC address of your first Ethernet card,
+	so you cannot run your copy of
+	<application>&mathematica;</application> on different
+	machines.</para>
+
+      <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.</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 &man.mkfontdir.1; 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 <application>&xorg;</application> server, you can have these font
+	directories loaded automatically by adding them to your
+	<filename>xorg.conf</filename> file.</para>
+
+      <note><para>For <application>&xfree86;</application> servers,
+	the configuration file is <filename>XF86Config</filename>.</para></note>
+      <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><application>&maple;</application> is a commercial mathematics program similar to
+      <application>&mathematica;</application>.  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 <application>&maple;</application>
+	  from Maple Waterloo Software (<ulink url="http://register.maplesoft.com/"></ulink>)
+	  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 <command>uname -a</command> 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&gt;&gt; ${LOG} 1&gt;&2
+	echo -n " lmgrd"
+	;;
+stop)
+	lmgrd -c ${LICENSE_FILE} -x lmdown 2&gt;&gt; ${LOG} 1&gt;&2
+	;;
+*)
+	echo "Usage: `basename $0` {start|stop}" 1&gt;&2
+	exit 64
+	;;
+esac
+
+exit 0
+   ----- snip ------------</programlisting></step>
+
+
+      <step><para>Test-start <application>&maple;</application>:</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 <application>FLEXlm</application> 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-matlab">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Dan</firstname>
+	  <surname>Pelleg</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+	<!-- daniel+handbook@pelleg.org -->
+      </authorgroup>
+    </sect1info>
+    <title>Installing &matlab;</title>
+
+    <indexterm>
+      <primary>applications</primary>
+      <secondary><application>MATLAB</application></secondary>
+    </indexterm>
+
+    <para>This document describes the process of installing the Linux
+      version of <application>&matlab; version 6.5</application> onto
+      a &os; system.  It works quite well, with the exception of the
+      <application>&java.virtual.machine;</application> (see
+      <xref linkend="matlab-jre">).</para>
+
+    <para>The Linux version of <application>&matlab;</application> can be
+      ordered directly from The MathWorks at <ulink
+      url="http://www.mathworks.com"></ulink>.  Make sure you also get
+      the license file or instructions how to create it.  While you
+      are there, let them know you would like a native &os;
+      version of their software.</para>
+
+    <sect2>
+      <title>Installing &matlab;</title>
+
+      <para>To install <application>&matlab;</application>, do the 
+	following:</para>
+
+      <procedure>
+	<step>
+	  <para>Insert the installation CD and mount it.
+	    Become <username>root</username>, as recommended by the
+	    installation script.  To start the installation script
+	    type:</para>
+
+	  <screen>&prompt.root; <userinput>/compat/linux/bin/sh /cdrom/install</userinput></screen>
+
+	  <tip>
+	    <para>The installer is graphical.  If you get errors about
+	      not being able to open a display, type
+	      <command>setenv HOME ~<replaceable>USER</replaceable></command>,
+	      where <replaceable>USER</replaceable> is the user you did a
+	      &man.su.1; as.</para>
+	  </tip>
+	</step>
+
+	<step>
+	  <para>
+	    When asked for the <application>&matlab;</application> root
+	    directory, type:
+	    <userinput>/compat/linux/usr/local/matlab</userinput>.</para>
+
+	  <tip>
+	    <para>For easier typing on the rest of the installation
+	      process, type this at your shell prompt:
+	      <command>set MATLAB=/compat/linux/usr/local/matlab</command></para>
+	  </tip>
+	</step>
+
+	<step>
+	  <para>Edit the license file as instructed when
+	    obtaining the <application>&matlab;</application> license.</para>
+
+	  <tip>
+	    <para>You can prepare this file in advance using your
+	      favorite editor, and copy it to
+	      <filename>$MATLAB/license.dat</filename> before the
+	      installer asks you to edit it.</para>
+	  </tip>
+	</step>
+
+	<step>
+	  <para>Complete the installation process.</para>
+	</step>
+      </procedure>
+
+      <para>At this point your <application>&matlab;</application>
+	installation is complete.  The following steps apply
+	<quote>glue</quote> to connect it to your &os; system.</para>
+    </sect2>
+
+    <sect2>
+      <title>License Manager Startup</title>
+      <procedure>
+	<step>
+	  <para>Create symlinks for the license manager scripts:</para>
+
+	  <screen>&prompt.root; <userinput>ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW</userinput>
+&prompt.root; <userinput>ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW</userinput></screen>
+	</step>
+	
+	<step>
+	  <para>Create a startup file at
+	    <filename>/usr/local/etc/rc.d/flexlm.sh</filename>.  The
+	    example below is a modified version of the distributed
+	    <filename>$MATLAB/etc/rc.lm.glnx86</filename>.  The changes
+	    are file locations, and startup of the license manager
+	    under Linux emulation.</para>
+
+	  <programlisting>#!/bin/sh
+case "$1" in
+  start)
+        if [ -f /usr/local/etc/lmboot_TMW ]; then
+              /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u <replaceable>username</replaceable> &amp;&amp; echo 'MATLAB_lmgrd'
+        fi
+        ;;
+  stop)
+	if [ -f /usr/local/etc/lmdown_TMW ]; then
+            /compat/linux/bin/sh /usr/local/etc/lmdown_TMW  &gt; /dev/null 2&gt;&amp;1
+	fi
+        ;;
+  *)
+	echo "Usage: $0 {start|stop}"
+	exit 1
+	;;
+esac
+
+exit 0</programlisting>
+
+	  <important>
+	    <para>The file must be made executable:</para>
+
+	    <screen>&prompt.root; <userinput>chmod +x /usr/local/etc/rc.d/flexlm.sh</userinput></screen>
+
+	    <para>You must also replace
+	      <replaceable>username</replaceable> above with the name
+	      of a valid user on your system (and not
+	      <username>root</username>).</para>
+	  </important>
+	</step>
+
+	<step>
+	  <para>Start the license manager with the command:</para>
+
+	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/flexlm.sh start</userinput></screen>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2 id="matlab-jre">
+      <title>Linking the &java; Runtime Environment</title>
+
+      <para>Change the <application>&java;</application> Runtime
+	Environment (JRE) link to one working under &os;:</para>
+
+      <screen>&prompt.root; <userinput>cd $MATLAB/sys/java/jre/glnx86/</userinput>
+&prompt.root; <userinput>unlink jre; ln -s ./jre1.1.8 ./jre</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Creating a &matlab; Startup Script</title>
+
+      <procedure>
+	<step>
+	  <para>Place the following startup script in
+	    <filename>/usr/local/bin/matlab</filename>:
+	  </para>
+
+	  <programlisting>#!/bin/sh
+/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"</programlisting>
+	</step>
+
+	<step>
+	  <para>Then type the command
+	    <command>chmod +x /usr/local/bin/matlab</command>.</para>
+	</step>
+      </procedure>
+
+      <tip>
+	<para>Depending on your version of
+	  <filename role="package">emulators/linux_base</filename>, you
+	  may run into errors when running this script.  To avoid that,
+	  edit the file
+	  <filename>/compat/linux/usr/local/matlab/bin/matlab</filename>,
+	  and change the line that says:</para>
+
+	<programlisting>if [ `expr "$lscmd" : '.*-&gt;.*'` -ne 0 ]; then</programlisting>
+
+	<para>(in version 13.0.1 it is on line 410) to this
+	  line:</para>
+
+	<programlisting>if test -L $newbase; then</programlisting>
+      </tip>
+    </sect2>
+
+    <sect2>
+      <title>Creating a &matlab; Shutdown Script</title>
+
+      <para>The following is needed to solve a problem with &matlab;
+	not exiting correctly.</para>
+
+      <procedure>
+	<step>
+	  <para>Create a file
+	    <filename>$MATLAB/toolbox/local/finish.m</filename>, and
+	    in it put the single line:</para>
+
+	  <programlisting>! $MATLAB/bin/finish.sh</programlisting>
+
+	  <note><para>The <literal>$MATLAB</literal> is
+	    literal.</para></note>
+
+	  <tip>
+	    <para>In the same directory, you will find the files
+	      <filename>finishsav.m</filename> and
+	      <filename>finishdlg.m</filename>, which let you save
+	      your workspace before quitting.  If you use either of
+	      them, insert the line above immediately after the
+	      <literal>save</literal> command.</para></tip>
+	</step>
+
+	<step>
+	  <para>Create a file
+	    <filename>$MATLAB/bin/finish.sh</filename>, which will
+	    contain the following:</para>
+
+	  <programlisting>#!/usr/compat/linux/bin/sh
+(sleep 5; killall -1 matlab_helper) &
+exit 0</programlisting>
+	</step>
+
+	<step>
+	  <para>Make the file executable:</para>
+
+	  <screen>&prompt.root; <userinput>chmod +x $MATLAB/bin/finish.sh</userinput></screen>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2 id="matlab-using">
+      <title>Using &matlab;</title>
+
+      <para>At this point you are ready to type
+	<command>matlab</command> and start using it.</para>
+    </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 <application>&oracle; 8.0.5</application> and
+	<application>&oracle; 8.0.5.1 Enterprise Edition</application> for Linux onto a FreeBSD
+	machine.</para>
+    </sect2>
+
+    <sect2>
+      <title>Installing the Linux Environment</title>
+
+      <para>Make sure you have both <filename role='package'>emulators/linux_base</filename> and
+	<filename role='package'>devel/linux_devtools</filename> from the Ports Collection
+	installed.  If you run into difficulties with these ports,
+	you may have to use
+	the packages or older versions available in the Ports Collection.</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 <application>RPM</application> port (<filename role='package'>archivers/rpm</filename>) 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 <replaceable>package</replaceable> should not generate any errors.</para>
+    </sect2>
+
+    <sect2>
+      <title>Creating the &oracle; Environment</title>
+
+      <para>Before you can install <application>&oracle;</application>, you need to set up a proper
+	environment.  This document only describes what to do
+	<emphasis>specially</emphasis> to run <application>&oracle;</application> for Linux on FreeBSD, not
+	what has been described in the <application>&oracle;</application> installation guide.</para>
+
+      <sect3 id="linuxemu-kernel-tuning">
+        <title>Kernel Tuning</title>
+	<indexterm><primary>kernel tuning</primary></indexterm>
+
+	<para>As described in the <application>&oracle;</application> 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 <application>&oracle;</application>.</para>
+
+	<para>Also, make sure you have the following options in your kernel
+	  configuration 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 <username>oracle</username> account just as you would create any other
+	  account. The  <username>oracle</username> 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 <username>oracle</username>
+	  account to <filename>/compat/linux/bin/bash</filename>.</para>
+      </sect3>
+
+      <sect3 id="linuxemu-environment">
+        <title>Environment</title>
+
+	<para>Besides the normal <application>&oracle;</application> variables, such as
+	  <envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must
+	  set the following environment variables:</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+          <colspec colwidth="1*">
+          <colspec colwidth="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.
+	Let it be owned by the <username>oracle</username> user.  You
+	should be able to install <application>&oracle;</application> without any problems.  If you have
+	problems, check your <application>&oracle;</application> distribution and/or configuration first!
+	After you have installed <application>&oracle;</application>, 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 <application>&oracle;</application>, some actions, which need to be performed
+	  as <username>root</username>, are recorded in a shell script called
+	  <filename>root.sh</filename>.  This script is
+	  written in the <filename>orainst</filename> directory.  Apply the
+	  following patch to <filename>root.sh</filename>, 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 <application>&oracle;</application> 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 <envar>PATH</envar>:</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.r3;</title>
+
+    <indexterm>
+      <primary>applications</primary>
+      <secondary><application>SAP R/3</application></secondary>
+    </indexterm>
+
+    <para>Installations of <application>&sap;</application> 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.r3; 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.r3; 4.6B (IDES)</application> with
+	  <application>&oracle; 8.0.5</application> on FreeBSD 4.3-STABLE</para>
+	</listitem>
+
+	<listitem>
+	  <para><application>&sap.r3; 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.r3;</application> installation guides.</para>
+
+      <para>Please see the documentation that comes with the
+	<application>&sap.r3;</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 <application>&sap;</application> installations:</para>
+
+      <sect3 id="software-46b">
+	<title>&sap.r3; 4.6B, &oracle; 8.0.5</title>
+
+      <informaltable frame="none" pgwide="1">
+	<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, we 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
+	FreeBSD 4.3-STABLE (it was only a few days past 4.3
+	RELEASE).</para>
+
+      </sect3>
+      <sect3 id="software-46c">
+	<title>&sap.r3; 4.6C SR2, &oracle; 8.1.7</title>
+
+	<informaltable frame="none" pgwide="1">
+	  <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 are 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.r3;</application> and proved to be useful
+	during installation:</para>
+
+      <sect3 id="sap-notes-46b">
+	<title>&sap.r3; 4.6B, &oracle; 8.0.5</title>
+
+	<informaltable frame="none" pgwide="1">
+	  <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.r3; 4.6C, &oracle; 8.1.7</title>
+
+	<informaltable frame="none" pgwide="1">
+	  <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.r3; System</application>. For production
+	use, a more exact sizing is of course needed:</para>
+
+      <informaltable frame="none" pgwide="1">
+	<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.r3; 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.r3; 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, for more information read the <xref
+	linkend="install-diff-media">.</para>
+
+      <sect3 id="disk-layout">
+	<title>Disk Layout</title>
+
+	<para>To keep it simple, the same disk layout both for the
+	  <application>&sap.r3; 46B</application> and <application>&sap.r3; 46C
+	  SR2</application> installation was used. Only the device names
+	  changed, as the installations were on different hardware (<filename>/dev/da</filename>
+	  and <filename>/dev/amr</filename> respectively, so if using an AMI &megaraid;, one will see
+	  <filename>/dev/amr0s1a</filename> instead of <filename>/dev/da0s1a</filename>):</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="4">
+	    <thead>
+	      <row>
+		<entry>File system</entry>
+		<entry>Size (1k-blocks)</entry>
+		<entry>Size (GB)</entry>
+		<entry>Mounted on</entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+		<entry><filename>/dev/da0s1a</filename></entry>
+		<entry>1.016.303</entry>
+		<entry>1</entry>
+		<entry><filename>/</filename></entry>
+	      </row>
+
+	      <row>
+		<entry><filename>/dev/da0s1b</filename></entry>
+		<entry> </entry>
+		<entry>6</entry>
+		<entry>swap</entry>
+	      </row>
+
+	      <row>
+		<entry><filename>/dev/da0s1e</filename></entry>
+		<entry>2.032.623</entry>
+		<entry>2</entry>
+		<entry><filename>/var</filename></entry>
+	      </row>
+
+	      <row>
+		<entry><filename>/dev/da0s1f</filename></entry>
+		<entry>8.205.339</entry>
+		<entry>8</entry>
+		<entry><filename>/usr</filename></entry>
+	      </row>
+
+	      <row>
+		<entry><filename>/dev/da1s1e</filename></entry>
+		<entry>45.734.361</entry>
+		<entry>45</entry>
+		<entry><filename>/compat/linux/oracle</filename></entry>
+	      </row>
+
+	      <row>
+		<entry><filename>/dev/da1s1f</filename></entry>
+		<entry>2.032.623</entry>
+		<entry>2</entry>
+		<entry><filename>/compat/linux/sapmnt</filename></entry>
+	      </row>
+
+	      <row>
+		<entry><filename>/dev/da1s1g</filename></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
+	  <acronym>BIOS</acronym> boot phase.</para>
+
+	<para> Please note that this disk layout differs slightly from
+	  the &sap; recommendations, as &sap; suggests mounting the
+	  <application>&oracle;</application> subdirectories (and some others) separately &mdash; we
+	  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.r3;</application>
+	  and <application>&oracle;</application>.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="installingthelinuxenviornment">
+      <title>Installing the Linux Environment</title>
+
+      <sect3 id="installinglinuxbase-system">
+	<title>Installing the Linux Base System</title>
+
+	<para>First the <link linkend="linuxemu-libs-port">linux_base</link>
+	  port needs to be installed (as <username>root</username>):</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base</userinput>
+&prompt.root; <userinput>make install distclean</userinput></screen>
+
+      </sect3>
+
+
+      <sect3 id="installinglinuxdevelopment">
+	<title>Installing Linux Development Environment</title>
+
+	<para>The Linux development environment is needed, if you want to install
+	  <application>&oracle;</application> on FreeBSD according to the
+	  <xref linkend="linuxemu-oracle">:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/devel/linux_devtools</userinput>
+&prompt.root; <userinput>make install distclean</userinput></screen>
+
+	<para>The Linux development environment has only been installed for the <application>&sap.r3;
+	  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 the Necessary RPMs</title>
+	<indexterm><primary>RPMs</primary></indexterm>
+
+	<para>To start the <command>R3SETUP</command> program, PAM support is needed.
+	  During the first <application>&sap;</application> Installation on FreeBSD 4.3-STABLE we
+	  tried to install PAM with all the required packages and
+	  finally forced the installation of the PAM package, which
+	  worked. For <application>&sap.r3; 4.6C SR2</application> we
+	  directly forced the installation of the PAM RPM, which also
+	  works, so it seems the dependent 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, we also had to install the RedHat Tcl package
+	  <filename>tcl-8.0.5-30.i386.rpm</filename> (otherwise the
+	  relinking during <application>&oracle;</application> installation
+	  will not work).  There are some other issues regarding
+	  relinking of <application>&oracle;</application>, but that is
+	  a <application>&oracle;</application> 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 <literal>linprocfs</literal>
+	  to <filename>/etc/fstab</filename>, for more information, see the &man.linprocfs.5; manual page.
+	  Another parameter to set is <literal>kern.fallback_elf_brand=3</literal>
+	  which is done in the file <filename>/etc/sysctl.conf</filename>.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="creatingsapr3env">
+      <title>Creating the &sap.r3; Environment</title>
+
+      <sect3 id="filesystemsandmountpoints">
+	<title>Creating the Necessary File Systems and Mountpoints</title>
+
+	<para>For a simple installation, it is sufficient to create the
+          following file systems:</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+	    <thead>
+	      <row>
+		<entry>mount point</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 <application>&sap;</application> 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.r3; 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.r3;</application> needs two users and
+	  three groups. The user names 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
+	  <literal>SAP</literal> and <literal>NIX</literal>. For a
+	  complete list please see the <application>&sap;</application> documentation).  For the IDES
+	  installation we used <literal>IDS</literal>, for the
+	  4.6C SR2 installation <literal>PRD</literal>, as that system
+	  is intended for production use.  We have
+	  therefore the following groups (group IDs might differ, these
+	  are just the values we used with our installation):</para>
+
+        <informaltable frame="none" pgwide="1">
+          <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 <application>&oracle;</application> installation, only group
+          <groupname>dba</groupname> is used. As
+          <groupname>oper</groupname> group, one also uses group
+          <groupname>dba</groupname> (see <application>&oracle;</application> and
+          <application>&sap;</application> documentation for further information).</para>
+
+        <para>We also need the following users:</para>
+
+        <informaltable frame="none" pgwide="1">
+          <tgroup cols="6">
+          <thead>
+          <row>
+            <entry>user ID</entry>
+            <entry>user name</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>&oracle; Administrator</entry>
+          </row>
+          </tbody>
+          </tgroup>
+        </informaltable>
+
+        <para>Adding the users with &man.adduser.8;
+          requires the following (please note shell and home
+          directory) entries for <quote>&sap; Administrator</quote>:</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 <quote>&oracle; Administrator</quote>:</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
+          file systems.  This depends entirely on your requirements.  We
+          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. Do not 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 <filename>/etc/services</filename></title>
+
+        <para><application>&sap.r3;</application> 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 &mdash; in this case,
+          <literal>00</literal>.  It will do no harm adding all
+          entries from <literal>00</literal> to
+          <literal>99</literal> for <literal>dp</literal>,
+          <literal>gw</literal>, <literal>sp</literal> and
+          <literal>ms</literal>). If you are going to use a <application>SAProuter</application>
+	  or need to access <application>&sap;</application> OSS, you also need <literal>99</literal>,
+	  as port 3299 is usually used for the <application>SAProuter</application> 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><application>&sap;</application> 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 we 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 <literal>STATUS</literal> of the offending steps to
+          <literal>OK</literal> in file <filename>CENTRDB.R3S</filename>), it will be impossible to log onto
+          the <application>&sap;</application> system without some additional effort.</para>
+      </sect3>
+
+      <sect3 id="kerneltuning">
+        <title>Kernel Tuning</title>
+	<indexterm><primary>kernel tuning</primary></indexterm>
+
+        <para><application>&sap.r3;</application> systems need a lot of resources.  We therefore
+        added the following parameters to the kernel configuration 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 identifiers
+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 on &i386;,
+	  leave <literal>MAXDSIZ</literal> and <literal>DFLDSIZ</literal> 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.r3;</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.  We decided to copy the CDROMs
+          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 Installation Script</title>
+
+	<para>First you have to prepare an <filename class="directory">install</filename> 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 installation script is started, which will copy nearly
+          all the relevant files into the <filename class="directory">install</filename> 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.r3; demonstration 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 (<application>&r3;</application> and database), not the IDES central
+	  instance, so one needs to copy the corresponding <filename>CENTRDB.R3S</filename>
+	  from the <filename class="directory">EXPORT1</filename> directory, otherwise <command>R3SETUP</command> 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.
+	  <application>&sap;</application> is using a separate template for database installation. To restart
+	  the installation later it is however sufficient to restart with
+	  the original file.</para>
+
+	<para>During and after installation, <application>&sap;</application> 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 <filename>.profile</filename> and <filename>.login</filename> files of
+	  both users that are installed during 
+	  <application>&sap;</application> installation.</para>
+      </sect3>
+
+      <sect3 id="startr3setup-46B">
+        <title>Start <command>R3SETUP</command> 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 <command>R3SETUP</command> 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 frame="none" pgwide="1">
+          <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 <application>&sap;</application> installer cannot find the CD needed (identified
+          by the <filename>LABEL.ASC</filename> file on the 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 our case, it requested EXPORT4 CD again but
+          indicated the correct key (6_LOCATION, then 7_LOCATION
+          etc.), so one can just continue with entering the correct
+          values.</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 <command>R3SETUP</command> 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 <command>R3SETUP</command> as user <username>root</username> 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 frame="none" pgwide="1">
+	  <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; <filename>Readme</filename>s
+        regarding Linux and <application>&oracle; DB</application> for possible problems. Most if
+        not all problems stem from incompatible libraries.</para>
+
+      <para>For more information on installing <application>&oracle;</application>, refer to <link
+	  linkend="linuxemu-oracle">the Installing &oracle;
+	  chapter.</link></para>
+
+
+      <sect3 id="installingtheoracle805withorainst">
+        <title>Installing the &oracle; 8.0.5 with <command>orainst</command></title>
+
+        <para>If <application>&oracle; 8.0.5</application> is to be
+          used, some additional libraries are needed for successfully
+          relinking, as <application>&oracle; 8.0.5</application> 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; <filename>Readme</filename>s for
+          further information.  If this is no option (at the time of
+          installation we 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. <application>&oracle;</application> 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 we 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. We did not
+          delete the remains of our previous RDBMS installation tries,
+          though.</para>
+
+        <para>Afterwards, <application>&oracle;</application> 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.r3; 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, <command>R3SETUP</command> can either be restarted or continued
+          (depending on whether exit was chosen or not). <command>R3SETUP</command> then
+	  creates the tablespaces and loads the data (for 46B IDES, from 
+	  EXPORT1 to EXPORT6, for 46C from DISK1 to DISK4) with <command>R3load</command>
+	  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 frame="none" pgwide="1">
+          <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 We had a few problems with 
+	  <command>dipgntab</command> during the 4.6B
+	  installation.</para>
+      </sect3>
+
+      <sect3 id="listener">
+        <title>Listener</title>
+
+        <para>Start the <application>&oracle;</application> 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 the error <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 <application>&sap;</application> 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 <application>&sap;</application> installation.</para>
+	<note><para>If you do not need MNLS, it is still necessary to check
+	  the table TCPDB and initializing it if this has not 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.r3; License Key</title>
+
+        <para>You have to request your <application>&sap.r3;</application> 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 parameters 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 user name, We usually choose
+        <username>wartung</username> (or
+        <username>service</username> in English).  Profiles
+        required are <literal>sap_new</literal> and
+        <literal>sap_all</literal>. 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 <username>sap*</username>, do at least the following:</para>
+
+        <informaltable frame="none" pgwide="1">
+          <tgroup cols="2">
+          <thead>
+          <row>
+            <entry>Task</entry>
+            <entry>Transaction</entry>
+          </row>
+          </thead>
+          <tbody>
+          <row>
+            <entry>Configure Transport System, e.g. 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 <application>&sap;</application> installation guides.</para>
+      </sect3>
+
+      <sect3 id="editintsidsap">
+        <title>Edit <filename>init<replaceable>sid</replaceable>.sap</filename> (<filename>initIDS.sap</filename>)</title>
+
+	<para>The file <filename>/oracle/IDS/dbs/initIDS.sap</filename>
+	  contains the <application>&sap;</application> 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>, we 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 we 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 <option>-B</option> which
+        sets block size to 5120&nbsp;Bytes. For DLT Tapes, HP recommends at
+        least 32&nbsp;K block size, so we used <option>--block-size=128</option> for
+        64&nbsp;K. <option>--format=newc</option> is needed because we have inode numbers greater than
+        65535. The last option <option>--quiet</option> 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
+        automatically.</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 <command>cpio</command>.</para>
+      </sect3>
+
+      <sect3>
+	<title>Configuration Issues after Installation</title>
+
+	<para>The following <application>&sap;</application> parameters should be tuned after
+	  installation (examples for IDES 46B, 1&nbsp;GB memory):</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <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" pgwide="1">
+	  <tgroup cols="2">
+	    <thead>
+	      <row>
+		<entry>Name</entry>
+		<entry>Value</entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+		<entry>ztta/dynpro_area</entry>
+		<entry>2500000</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+
+	<para>&sap; Note 0157246:</para>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="2">
+	    <thead>
+	      <row>
+		<entry>Name</entry>
+		<entry>Value</entry>
+	      </row>
+	    </thead>
+	    <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 <command>R3SETUP</command> after Fixing a Problem</title>
+
+	<para><command>R3SETUP</command> stops if it encounters an error. If you have
+	  looked at the corresponding logfiles and fixed the error,
+	  you have to start <command>R3SETUP</command> again, usually selecting REPEAT
+	  as option for the last step <command>R3SETUP</command> complained about.</para>
+
+	<para>To restart <command>R3SETUP</command>, just start it with the corresponding
+	  <filename>R3S</filename> file:</para>
+
+	  <screen>&prompt.root; <userinput>./R3SETUP -f CENTRDB.R3S</userinput></screen>
+
+	  <para>for 4.6B, or with</para>
+
+	  <screen>&prompt.root; <userinput>./R3SETUP -f CENTRAL.R3S</userinput></screen>
+
+	  <para>for 4.6C, no matter whether the error occurred
+	  with <filename>CENTRAL.R3S</filename> or
+	  <filename>DATABASE.R3S</filename>.</para>
+
+	<note><para>At some stages, <command>R3SETUP</command> assumes that both database
+	    and <application>&sap;</application> 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 <application>&sap;</application> by hand after you fixed the errors and before starting 
+	    <command>R3SETUP</command> again.</para>
+	  <para>Do not forget to also start the <application>&oracle;</application> 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 <command>R3SETUP</command></title>
+
+        <para>If <command>R3SETUP</command> complains at this stage, edit the
+	  template file <command>R3SETUP</command> used at that time
+          (<filename>CENTRDB.R3S</filename> (4.6B) or either
+	  <filename>CENTRAL.R3S</filename> or
+	  <filename>DATABASE.R3S</filename> (4.6C)).
+	  Locate <literal>[OSUSERSIDADM_IND_ORA]</literal> or search for the
+	  only <literal>STATUS=ERROR</literal> 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 <command>R3SETUP</command> again.</para>
+      </sect3>
+
+      <sect3 id="indoraduringr3setup">
+        <title>OSUSERDBSID_IND_ORA during <command>R3SETUP</command></title>
+
+        <para>Possibly <command>R3SETUP</command> also complains at this stage. The error
+	  here is similar to the one in phase OSUSERSIDADM_IND_ORA. 
+	  Just edit
+	  the template file <command>R3SETUP</command> used at that time
+          (<filename>CENTRDB.R3S</filename> (4.6B) or either
+	  <filename>CENTRAL.R3S</filename> or
+	  <filename>DATABASE.R3S</filename> (4.6C)).
+	  Locate <literal>[OSUSERDBSID_IND_ORA]</literal> or search for the
+	  only <literal>STATUS=ERROR</literal> entry
+	  and edit the following value in that section:</para>
+
+        <programlisting>STATUS=OK</programlisting>
+
+        <para>Then restart <command>R3SETUP</command>.</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 <application>&oracle;</application> installation menu and restart installation.</para>
+      </sect3>
+
+      <sect3 id="textenvincalid">
+        <title><errorname>TEXTENV_INVALID</errorname> during <command>R3SETUP</command>, 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 (e.g. <filename>saplocales-1.0-3</filename>,
+	  <filename>saposcheck-1.0-1</filename> for RedHat 6.1). In case
+	  you ignored all the related errors and set the corresponding
+	  <literal>STATUS</literal> from <literal>ERROR</literal> to <literal>OK</literal> (in <filename>CENTRDB.R3S</filename>) every time <command>R3SETUP</command>
+	  complained and just restarted <command>R3SETUP</command>, the <application>&sap;</application> system will not
+	  be properly configured and you will then not be able to
+	  connect to the system with a
+	  <application>SAPgui</application>, even though the system
+	  can be started. Trying to connect with the old Linux
+	  <application>SAPgui</application> 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 <application>&sap.r3;</application> 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 <application>&sap;</application>, 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 <application>&sap;</application> 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 <application>&sap;</application>
+	  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.
+	  The reason was that the <application>&oracle;</application> 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 <command>startsap</command> script (for example
+	  <command>startsap_majestix_00</command>) 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 <application>&oracle;</application> 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 happened whilst trying to use values for
+	  <literal>MAXDSIZ</literal> and <literal>DFLDSIZ</literal>
+	  greater than 1&nbsp;GB (1024x1024x1024). Additionally, we got 
+	  <errorname>Linux Error 12: Cannot allocate memory</errorname>.</para>
+      </sect3>
+
+      <sect3 id="dipgntabindind">
+        <title>[DIPGNTAB_IND_IND] during <command>R3SETUP</command></title>
+
+        <para>In general, see &sap; Note 0130581 (<command>R3SETUP</command> step 
+	  <literal>DIPGNTAB</literal> terminates).  During the
+	  IDES-specific installation, for some reason the installation
+	  process was not using the proper <application>&sap;</application> system name <quote>IDS</quote>, but
+	  the empty string <literal>""</literal> instead. This leads 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, we 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 -&gt; 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>We also found &sap; Notes (0029227 and 0008401) describing
+        this behavior. We 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 <command>R3SETUP</command></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 
+	  <literal>STATUS</literal> of the offending step from <literal>ERROR</literal> to <literal>OK</literal> (file
+	  <filename>CENTRDB.R3S</filename>) and restart <command>R3SETUP</command>. 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 <command>R3SETUP</command></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 <literal>STATUS</literal> of the offending step from <literal>ERROR</literal> to <literal>OK</literal> (file
+	  <filename>CENTRDB.R3S</filename>) and restart <command>R3SETUP</command>. After
+	  installation, you have to execute the report
+	  <literal>RADDBDIF</literal> from transaction SE38.</para>
+      </sect3>
+
+      <sect3 id="sigactionsig31">
+        <title><errorcode>sigaction sig31: File size limit exceeded</errorcode></title>
+
+	<para>This error occurred during start of <application>&sap;</application> processes
+	  <emphasis>disp+work</emphasis>. If starting <application>&sap;</application> with the
+	  <command>startsap</command> script, subprocesses are then started which
+	  detach and do the dirty work of starting all other <application>&sap;</application>
+          processes. As a result, the script itself will not notice
+	  if something goes wrong.</para>
+
+	<para>To check whether the <application>&sap;</application> 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 <application>&oracle;</application> and <application>&sap;</application> processes. If it looks like
+	  some processes are missing or if you cannot connect to the <application>&sap;</application> 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
+	  <application>&oracle;</application> and <application>&sap;</application> 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 <command>saposcol</command> Failed</title>
+	<para>There are some problems with the program <command>saposcol</command> (version 4.6D).
+	  The <application>&sap;</application> system is using <command>saposcol</command> to collect data about the 
+	  system performance. This program is not needed to use the <application>&sap;</application> system,
+	  so this problem can be considered a minor one. The older versions
+	  (4.6B) does work, but does not collect all the data (many calls will
+	  just return 0, for example for CPU usage).</para>
+      </sect3>
+    </sect2>
+  </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
+	<option>union</option> option to file system mounts
+	(<emphasis>not</emphasis> the <literal>unionfs</literal> file system type!) 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 execute 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 <emphasis>glue</emphasis> 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/pl_PL.ISO8859-2/books/handbook/mac/Makefile b/pl_PL.ISO8859-2/books/handbook/mac/Makefile
new file mode 100644
index 0000000000..74aca4172f
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/mac/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	mac/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/mac/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/mac/chapter.sgml
new file mode 100644
index 0000000000..1a8bd9f165
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/mac/chapter.sgml
@@ -0,0 +1,2182 @@
+<!--
+     The FreeBSD Documentation Project
+     $FreeBSD$
+-->
+
+<chapter id="mac">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Written by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Mandatory Access Control</title>
+
+  <sect1 id="mac-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm><primary>MAC</primary></indexterm>
+    <indexterm>
+      <primary>Mandatory Access Control</primary>
+      <see>MAC</see>
+    </indexterm>
+
+    <para>&os;&nbsp;5.X introduced new security extensions from the
+      TrustedBSD project based on the &posix;.1e draft.  Two of the most
+      significant new security mechanisms are file system Access Control
+      Lists (<acronym>ACLs</acronym>) and Mandatory Access Control
+      (<acronym>MAC</acronym>) facilities.  Mandatory Access Control allows
+      new access control modules to be loaded, implementing new security
+      policies.  Some provide protections of a narrow subset of the
+      system, hardening a particular service.  Others provide
+      comprehensive labeled security across all subjects and objects.
+      The mandatory part
+      of the definition comes from the fact that the enforcement of
+      the controls is done by administrators and the system, and is
+      not left up to the discretion of users as is done with
+      discretionary access control (<acronym>DAC</acronym>, the standard
+      file and System V <acronym>IPC</acronym> permissions on &os;).</para>
+
+    <para>This chapter will focus on the
+      Mandatory Access Control Framework (<acronym>MAC</acronym> Framework), and a set
+      of pluggable security policy modules enabling various security
+      mechanisms.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>What <acronym>MAC</acronym> security policy modules are currently
+          included in &os; and their associated mechanisms.</para>
+      </listitem>
+
+      <listitem>
+	<para>What <acronym>MAC</acronym> security policy modules implement as
+	  well as the difference between a labeled and non-labeled
+	  policy.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to efficiently configure a system to use
+	  the <acronym>MAC</acronym> framework.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure the different security policy modules included with the
+	  <acronym>MAC</acronym> framework.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to implement a more secure environment using the
+	  <acronym>MAC</acronym> framework and the examples
+	  shown.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to test the <acronym>MAC</acronym> configuration
+	  to ensure the framework has been properly implemented.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand &unix; and &os; basics
+	  (<xref linkend="basics">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Be familiar with
+	  the basics of kernel configuration/compilation
+	  (<xref linkend="kernelconfig">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Have some familiarity with security and how it
+	  pertains to &os; (<xref linkend="security">).</para>
+      </listitem>
+    </itemizedlist>
+
+    <warning>
+      <para>The improper use of the
+	information contained herein may cause loss of system access,
+	aggravation of users, or inability to access the features
+	provided by X11.  More importantly, <acronym>MAC</acronym> should not
+	be relied upon to completely secure a system.  The
+	<acronym>MAC</acronym> framework only augments
+	existing security policy; without sound security practices and
+	regular security checks, the system will never be completely
+	secure.</para>
+
+      <para>It should also be noted that the examples contained
+	within this chapter are just that, examples.  It is not
+	recommended that these particular settings be rolled out
+	on a production system.  Implementing the various security policy modules takes
+	a good deal of thought and testing.  One who does not fully understand
+	exactly how everything works may find him or herself going
+	back through the entire system and reconfiguring many files
+	or directories.</para>
+    </warning>
+
+    <sect2>
+      <title>What Will Not Be Covered</title>
+
+      <para>This chapter covers a broad range of security issues relating
+	to the <acronym>MAC</acronym> framework.  The
+	development of new <acronym>MAC</acronym> security policy modules
+	will not be covered.  A number of security policy modules included with the
+	<acronym>MAC</acronym> framework have specific characteristics
+	which are provided for both testing and new module
+	development. These include the &man.mac.test.4;,
+	&man.mac.stub.4; and &man.mac.none.4;.
+        For more information on these security policy modules and the various
+	mechanisms they provide, please review the manual pages.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-inline-glossary">
+    <title>Key Terms in this Chapter</title>
+
+    <para>Before reading this chapter, a few key terms must be
+      explained.  This will hopefully clear up any confusion that
+      may occur and avoid the abrupt introduction of new terms
+      and information.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><emphasis>compartment</emphasis>: A compartment is a
+	  set of programs and data to be partitioned or separated,
+	  where users are given explicit access to specific components
+	  of a system.  Also, a compartment represents a grouping,
+	  such as a work group, department, project, or topic.  Using
+	  compartments, it is possible to implement a need-to-know
+	  security policy.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>high water mark</emphasis>: A high water mark
+	  policy is one which permits the raising of security levels
+	  for the purpose of accessing higher level information.  In
+	  most cases, the original level is restored after the process
+	  is complete.  Currently, the &os; <acronym>MAC</acronym>
+	  framework does not have a policy for this, but the definition
+	  is included for completeness.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>integrity</emphasis>: Integrity, as a key
+	  concept, is the level of trust which can be placed on data.
+	  As the integrity of the data is elevated, so does the ability
+	  to trust that data.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>label</emphasis>: A label is a security
+	  attribute which can be applied to files, directories, or
+	  other items in the system.  It could be considered
+	  a confidentiality stamp; when a label is placed on
+	  a file it describes the security properties for that specific
+	  file and will only permit access by files, users, resources,
+	  etc. with a similar security setting.  The meaning and
+	  interpretation of label values depends on the policy configuration: while
+	  some policies might treat a label as representing the
+	  integrity or secrecy of an object, other policies might use
+	  labels to hold rules for access.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>level</emphasis>: The increased or decreased
+	  setting of a security attribute.  As the level increases,
+	  its security is considered to elevate as well.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>low water mark</emphasis>: A low water mark
+	  policy is one which permits lowering of the security levels
+	  for the purpose of accessing information which is less
+	  secure.  In most cases, the original security level of the
+	  user is restored after the process is complete.  The only
+	  security policy module in &os; to use this is
+	  &man.mac.lomac.4;.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>multilabel</emphasis>: The
+	  <option>multilabel</option> property is a file system option
+	  which can be set in single user mode using the
+	  &man.tunefs.8; utility, during the boot operation
+	  using the &man.fstab.5; file, or during the creation of
+	  a new file system.  This option will permit an administrator
+	  to apply different <acronym>MAC</acronym> labels on different
+	  objects.  This option
+	  only applies to security policy modules which support labeling.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>object</emphasis>: An object or system
+	  object is an entity through which information flows
+	  under the direction of a <emphasis>subject</emphasis>.
+	  This includes directories, files, fields, screens, keyboards,
+	  memory, magnetic storage, printers or any other data
+	  storage/moving device.  Basically, an object is a data container or
+	  a system resource; access to an <emphasis>object</emphasis>
+	  effectively means access to the data.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>policy</emphasis>: A collection of rules
+	  which defines how objectives are to be achieved.  A
+	  <emphasis>policy</emphasis> usually documents how certain
+	  items are to be handled.  This chapter will
+	  consider the term <emphasis>policy</emphasis> in this
+	  context as a <emphasis>security policy</emphasis>; i.e.
+	  a collection of rules which will control the flow of data
+	  and information and define whom will have access to that
+	  data and information.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>sensitivity</emphasis>: Usually used when
+	  discussing <acronym>MLS</acronym>.  A sensitivity level is
+	  a term used to describe how important or secret the data
+	  should be.  As the sensitivity level increases, so does the
+	  importance of the secrecy, or confidentiality of the data.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>single label</emphasis>: A single label is
+	  when the entire file system uses one label to
+	  enforce access control over the flow of data.  When a file
+	  system has this set, which is any time when the
+	  <option>multilabel</option> option is not set, all
+	  files will conform to the same label setting.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>subject</emphasis>: a subject is any
+	  active entity that causes information to flow between
+	  <emphasis>objects</emphasis>; e.g. a user, user processor,
+	  system process, etc.  On &os;, this is almost always a thread
+	  acting in a process on behalf of a user.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="mac-initial">
+    <title>Explanation of MAC</title>
+
+    <para>With all of these new terms in mind, consider how the
+      <acronym>MAC</acronym> framework augments the security of
+      the system as a whole.  The various security policy modules provided by
+      the <acronym>MAC</acronym> framework could be used to
+      protect the network and file systems, block users from
+      accessing certain ports and sockets, and more.  Perhaps
+      the best use of the policy modules is to blend them together, by loading
+      several security policy modules at a time for a multi-layered
+      security environment.  In a multi-layered security environment,
+      multiple policy modules are in effect to keep security in check.  This
+      is different to a hardening policy, which typically hardens
+      elements of a system that is used only for specific purposes.
+      The only downside is administrative overhead in cases of
+      multiple file system labels, setting network access control
+      user by user, etc.</para>
+
+    <para>These downsides are minimal when compared to the lasting
+      effect of the framework; for instance, the ability to pick and choose
+      which policies are required for a specific configuration keeps
+      performance overhead down.  The reduction of support for unneeded
+      policies can increase the overall performance of the system as well as
+      offer flexibility of choice.  A good implementation would
+      consider the overall security requirements and effectively implement
+      the various security policy modules offered by the framework.</para>
+
+    <para>Thus a system utilizing <acronym>MAC</acronym> features
+      should at least guarantee that a user will not be permitted
+      to change security attributes at will; all user utilities,
+      programs and scripts must work within the constraints of
+      the access rules provided by the selected security policy modules; and
+      that total control of the <acronym>MAC</acronym> access
+      rules are in the hands of the system administrator.</para>
+
+    <para>It is the sole duty of the system administrator to
+      carefully select the correct security policy modules.  Some environments
+      may need to limit access control over the network; in these
+      cases, the &man.mac.portacl.4;, &man.mac.ifoff.4; and even
+      &man.mac.biba.4; policy modules might make good starting points.  In other
+      cases, strict confidentiality of file system objects might
+      be required.  Policy modules such as &man.mac.bsdextended.4;
+      and &man.mac.mls.4; exist for this purpose.</para>
+
+    <para>Policy decisions could be made based on network
+      configuration.  Perhaps only certain users should be permitted
+      access to facilities provided by &man.ssh.1; to access the
+      network or the Internet.  The &man.mac.portacl.4; would be
+      the policy module of choice for these situations.  But what should be
+      done in the case of file systems?  Should all access to certain
+      directories be severed from other groups or specific
+      users?  Or should we limit user or utility access to specific
+      files by setting certain objects as classified?</para>
+
+    <para>In the file system case, access to objects might be
+      considered confidential to some users, but not to others.
+      For an example, a large development team might be broken
+      off into smaller groups of individuals.  Developers in
+      project A might not be permitted to access objects written
+      by developers in project B.  Yet they might need to access
+      objects created by developers in project C; that is quite a
+      situation indeed.  Using the different security policy modules provided by
+      the <acronym>MAC</acronym> framework; users could
+      be divided into these groups and then given access to the
+      appropriate areas without fear of information
+      leakage.</para>
+
+    <para>Thus, each security policy module has a unique way of dealing with
+      the overall security of a system.  Module selection should be based
+      on a well thought out security policy.  In many cases, the
+      overall policy may need to be revised and reimplemented on
+      the system.  Understanding the different security policy modules offered by
+      the <acronym>MAC</acronym> framework will help administrators
+      choose the best policies for their situations.</para>
+
+    <para>The default &os; kernel does not include the option for
+      the <acronym>MAC</acronym> framework; thus the following
+      kernel option must be added before trying any of the examples or
+      information in this chapter:</para>
+
+    <programlisting>options	MAC</programlisting>
+
+    <para>And the kernel will require a rebuild and a reinstall.</para>
+
+    <caution>
+      <para>While the various manual pages for <acronym>MAC</acronym>
+	policy modules state that they may be built into the kernel,
+	it is possible to lock the system out of
+	the network and more.  Implementing <acronym>MAC</acronym>
+	is much like implementing a firewall, care must be taken
+	to prevent being completely locked out of the system.  The
+	ability to revert back to a previous configuration should be
+	considered while the implementation of <acronym>MAC</acronym>
+	remotely should be done with extreme caution.</para>
+    </caution>
+  </sect1>
+
+  <sect1 id="mac-understandlabel">
+    <title>Understanding MAC Labels</title>
+
+    <para>A <acronym>MAC</acronym> label is a security attribute
+      which may be applied to subjects and objects throughout
+      the system.</para>
+
+    <para>When setting a label, the user must be able to comprehend
+      what it is, exactly, that is being done.  The attributes
+      available on an object depend on the policy module loaded, and that
+      policy modules interpret their attributes in different
+      ways.  If improperly configured due to lack of comprehension, or
+      the inability to understand the implications, the result will
+      be the unexpected and perhaps, undesired, behavior of the
+      system.</para>
+
+    <para>The security label on an object is used as a part of a
+      security access control decision by a policy.  With some
+      policies, the label by itself contains all information necessary
+      to make a decision; in other models, the labels may be processed
+      as part of a larger rule set, etc.</para>
+
+    <para>For instance, setting the label of <literal>biba/low</literal>
+      on a file will represent a label maintained by the Biba security policy module,
+      with a value of <quote>low</quote>.</para>
+
+    <para>A few policy modules which support the labeling feature in
+      &os; offer three specific predefined labels.  These
+      are the low, high, and equal labels.  Although they enforce
+      access control in a different manner with each policy module, you
+      can be sure that the low label will be the lowest setting,
+      the equal label will set the subject or object to be disabled
+      or unaffected, and the high label will enforce the highest
+      setting available in the Biba and <acronym>MLS</acronym>
+      policy modules.</para>
+
+    <para>Within single label file system environments, only one label may be
+      used on objects.  This will enforce one set of
+      access permissions across the entire system and in many
+      environments may be all that is required.  There are a few
+      cases where multiple labels may be set on objects
+      or subjects in the file system.  For those cases, the
+      <option>multilabel</option> option may be passed to
+      &man.tunefs.8;.</para>
+
+    <para>In the case of Biba and <acronym>MLS</acronym>, a numeric
+      label may be set to indicate the precise level of hierarchical
+      control.  This numeric level is used to partition or sort
+      information into different groups of say, classification only
+      permitting access to that group or a higher group level.</para>
+
+    <para>In most cases the administrator will only be setting up a
+      single label to use throughout the file system.</para>
+
+    <para><emphasis>Hey wait, this is similar to <acronym>DAC</acronym>!
+      I thought <acronym>MAC</acronym> gave control strictly to the
+      administrator.</emphasis>  That statement still holds true, to some
+      extent as <username>root</username> is the one in control and who
+      configures the policies so that users are placed in the
+      appropriate categories/access levels.  Alas, many policy modules can
+      restrict the <username>root</username> user as well.  Basic
+      control over objects will then be released to the group, but
+      <username>root</username> may revoke or modify the settings
+      at any time.  This is the hierarchal/clearance model covered
+      by policies such as Biba and <acronym>MLS</acronym>.</para>
+
+    <sect2>
+      <title>Label Configuration</title>
+
+      <para>Virtually all aspects of label policy module configuration
+	will be performed using the base system utilities.  These
+	commands provide a simple interface for object or subject
+	configuration or the manipulation and verification of
+	the configuration.</para>
+
+      <para>All configuration may be done by use of the
+	&man.setfmac.8; and &man.setpmac.8; utilities.
+	The <command>setfmac</command> command is used to set
+	<acronym>MAC</acronym> labels on system objects while the
+	<command>setpmac</command> command is used to set the labels
+	on system subjects.  Observe:</para>
+
+      <screen>&prompt.root; <userinput>setfmac biba/high test</userinput></screen>
+
+      <para>If no errors occurred with the command above, a prompt
+	will be returned.  The only time these commands are not
+	quiescent is when an error occurred; similarly to the
+	&man.chmod.1; and &man.chown.8; commands.  In some cases this
+	error may be a <errorname>Permission denied</errorname> and
+	is usually obtained when the label is being set or modified
+	on an object which is restricted.<footnote><para>Other conditions
+	may produce different failures.  For instance, the file may not
+	be owned by the	user attempting to relabel the object, the
+	object may not exist or	may be read only.  A mandatory policy
+	will not allow the process to relabel the file, maybe because
+	of a property of the file, a property of the process, or a
+	property of the proposed new label value.  For example: a user
+	running at low integrity tries to change the label of a high
+	integrity file.  Or perhaps a user running at low integrity
+	tries to change the label of a low integrity file to a high
+	integrity label.</para></footnote>  The system administrator
+	may use the following commands to overcome this:</para>
+
+      <screen>&prompt.root; <userinput>setfmac biba/high test</userinput>
+<errorname>Permission denied</errorname>
+&prompt.root; <userinput>setpmac biba/low setfmac biba/high test</userinput>
+&prompt.root; <userinput>getfmac test</userinput>
+test: biba/high</screen>
+
+      <para>As we see above, <command>setpmac</command>
+	can be used to override the policy module's settings by assigning
+	a different label to the invoked process.  The
+	<command>getpmac</command> utility is usually used with currently
+	running processes, such as <application>sendmail</application>:
+	although it takes a process ID in place of
+	a command the logic is extremely similar.  If users
+	attempt to manipulate a file not in their access, subject to the
+	rules of the loaded policy modules, the
+	<errorname>Operation not permitted</errorname> error
+	will be displayed by the <function>mac_set_link</function>
+	function.</para>
+
+      <sect3>
+	<title>Common Label Types</title>
+
+	<para>For the &man.mac.biba.4;, &man.mac.mls.4; and
+	  &man.mac.lomac.4; policy modules, the ability to assign
+	  simple labels is provided.  These take the form of high,
+	  equal and low, what follows is a brief description of
+	  what these labels provide:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>The <literal>low</literal> label is considered the
+	      lowest label setting an object or subject may have.
+	      Setting this on objects or subjects will block their
+	      access to objects or subjects marked high.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>The <literal>equal</literal> label should only be
+	      placed on objects considered to be exempt from the
+	      policy.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>The <literal>high</literal> label grants an object or
+	      subject the highest possible setting.</para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>With respect to each policy module, each of those settings
+	  will instate a different information flow directive.  Reading
+	  the proper manual pages will further explain the traits of
+	  these generic label configurations.</para>
+
+        <sect4>
+	  <title>Advanced Label Configuration</title>
+
+	  <para>Numeric grade labels are used for
+	    <literal>comparison:compartment+compartment</literal>; thus
+	    the following:</para>
+
+	  <programlisting>biba/10:2+3+6(5:2+3-20:2+3+4+5+6)</programlisting>
+
+	  <para>May be interpreted as:</para>
+
+	  <para><quote>Biba Policy Label</quote>/<quote>Grade 10</quote>
+	    :<quote>Compartments 2, 3 and 6</quote>:
+	    (<quote>grade 5 ...</quote>)</para>
+
+	  <para>In this example, the first grade would be considered
+	    the <quote>effective grade</quote> with
+	    <quote>effective compartments</quote>, the second grade
+	    is the low grade and the last one is the high grade.
+	    In most configurations these settings will not be used;
+	    indeed, they offered for more advanced
+	    configurations.</para>
+
+	  <para>When applied to system objects, they will only have a
+	    current grade/compartments as opposed to system subjects
+	    as they reflect the range of available rights in the system,
+	    and network interfaces, where they are used for access
+	    control.</para>
+
+	  <para>The grade and compartments in a subject and object pair
+	    are used to construct a relationship referred to as
+	    <quote>dominance</quote>, in which a subject dominates an
+	    object, the object dominates the subject, neither dominates
+	    the other, or both dominate each other.  The
+	    <quote>both dominate</quote> case occurs when the two labels
+	    are equal.  Due to the information flow nature of Biba, you
+	    have rights to a set of compartments,
+	    <quote>need to know</quote>, that might correspond to
+	    projects, but objects also have a set of compartments.
+	    Users may have to subset their rights using
+	    <command>su</command> or <command>setpmac</command> in order
+	    to access objects in a compartment from which they are not
+	    restricted.</para>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<title>Users and Label Settings</title>
+
+	<para>Users themselves are required to have labels so that
+	  their files and processes may properly interact with the
+	  security policy defined on the system.  This is
+	  configured through the <filename>login.conf</filename> file
+	  by use of login classes.  Every policy module that uses labels
+	  will implement the user class setting.</para>
+
+	<para>An example entry containing every policy module setting is displayed
+	  below:</para>
+
+	<programlisting>default:\
+	:copyright=/etc/COPYRIGHT:\
+	:welcome=/etc/motd:\
+	:setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\
+	:path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:\
+	:manpath=/usr/share/man /usr/local/man:\
+	:nologin=/usr/sbin/nologin:\
+	:cputime=1h30m:\
+	:datasize=8M:\
+	:vmemoryuse=100M:\
+	:stacksize=2M:\
+	:memorylocked=4M:\
+	:memoryuse=8M:\
+	:filesize=8M:\
+	:coredumpsize=8M:\
+	:openfiles=24:\
+	:maxproc=32:\
+	:priority=0:\
+	:requirehome:\
+	:passwordtime=91d:\
+	:umask=022:\
+	:ignoretime@:\
+	:label=partition/13,mls/5,biba/10(5-15),lomac/10[2]:</programlisting>
+
+	<para>The <literal>label</literal> option is used to set the
+	  user class default label which will be enforced by
+	  <acronym>MAC</acronym>.  Users will never be permitted to
+	  modify this value, thus it can be considered not optional
+	  in the user case.  In a real configuration, however, the
+	  administrator will never wish to enable every policy module.
+	  It is recommended that the rest of this chapter be reviewed
+	  before any of this configuration is implemented.</para>
+
+	<note>
+	  <para>Users may change their label after the initial login;
+	    however, this change is subject constraints of the policy.
+	    The example above tells the Biba policy that a process's
+	    minimum integrity is 5, its maximum is 15, but the default
+	    effective label is 10.  The process will run at 10 until
+	    it chooses to change label, perhaps due to the user using
+	    the setpmac command, which will be constrained by Biba to
+	    the range set at login.</para>
+	</note>
+
+	<para>In all cases, after a change to
+	  <filename>login.conf</filename>, the login class capability
+	  database must be rebuilt using <command>cap_mkdb</command>
+	  and this will be reflected throughout every forthcoming
+	  example or discussion.</para>
+
+	<para>It is useful to note that many sites may have a
+	  particularly large number of users requiring several
+	  different user classes.  In depth planning is required
+	  as this may get extremely difficult to manage.</para>
+
+	<para>Future versions of &os; will include a new way to
+	  deal with mapping users to labels; however, this will
+	  not be available until some time after &os;&nbsp;5.3.</para>
+      </sect3>
+
+      <sect3>
+	<title>Network Interfaces and Label Settings</title>
+
+	<para>Labels may also be set on network interfaces to help
+	  control the flow of data across the network.  In all cases
+	  they function in the same way the policies function with
+	  respect to objects.  Users at high settings in
+	  <literal>biba</literal>, for example, will not be permitted
+	  to access network interfaces with a label of low.</para>
+
+	<para>The <option>maclabel</option> may be passed to
+	  <command>ifconfig</command> when setting the
+	  <acronym>MAC</acronym> label on network interfaces.  For
+	  example:</para>
+
+	<screen>&prompt.root; <userinput>ifconfig bge0 maclabel biba/equal</userinput></screen>
+
+	<para>will set the <acronym>MAC</acronym> label of
+	  <literal>biba/equal</literal> on the &man.bge.4; interface.
+	  When using a setting similar to
+	  <literal>biba/high(low-high)</literal> the entire label should
+	  be quoted; otherwise an error will be returned.</para>
+
+	<para>Each policy module which supports labeling has a tunable
+	  which may be used to disable the <acronym>MAC</acronym>
+	  label on network interfaces.  Setting the label to
+	  <option>equal</option> will have a similar effect.  Review
+	  the output from <command>sysctl</command>, the policy manual
+	  pages, or even the information found later in this chapter
+	  for those tunables.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Singlelabel or Multilabel?</title>
+<!-- Stopped here with my edits -->
+      <para>By default the system will use the
+	<option>singlelabel</option> option.  But what does this
+	mean to the administrator?  There are several differences
+	which, in their own right, offer pros and cons to the
+	flexibility in the systems security model.</para>
+
+      <para>The <option>singlelabel</option> only permits for one
+	label, for instance <literal>biba/high</literal> to be used
+	for each subject or object.  It provides for lower
+	administration overhead but decreases the flexibility of
+	policies which support labeling.  Many administrators may
+	want to use the <option>multilabel</option> option in
+	their security policy.</para>
+
+      <para>The <option>multilabel</option> option will permit each
+	subject or object to have its own independent
+	<acronym>MAC</acronym> label in
+	place of the standard <option>singlelabel</option> option
+	which will allow only one label throughout the partition.
+	The <option>multilabel</option> and <option>single</option>
+	label options are only required for the policies which
+	implement the labeling feature, including the Biba, Lomac,
+	<acronym>MLS</acronym> and <acronym>SEBSD</acronym>
+	policies.</para>
+    
+      <para>In many cases, the <option>multilabel</option> may not need
+	to be set at all.  Consider the following situation and
+	security model:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>&os; web-server using the <acronym>MAC</acronym>
+	    framework and a mix of the various policies.</para>
+	</listitem>
+
+	<listitem>
+	  <para>This machine only requires one label,
+	    <literal>biba/high</literal>, for everything in the system.
+	    Here the file system would not require the
+	    <option>multilabel</option> option as a single label
+	    will always be in effect.</para>
+	</listitem>
+
+	<listitem>
+	  <para>But, this machine will be a web server and should have
+	    the web server run at <literal>biba/low</literal> to prevent
+	    write up capabilities.  The Biba policy and how it works
+	    will be discussed later, so if the previous comment was
+	    difficult to interpret just continue reading and return.
+	    The server could use a separate partition set at
+	    <literal>biba/low</literal> for most if not all of its
+	    runtime state.  Much is lacking from this example, for
+	    instance the restrictions on data, configuration and user
+	    settings; however, this is just a quick example to prove the
+	    aforementioned point.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>If any of the non-labeling policies are to be used,
+	then the <option>multilabel</option> option would never
+	be required.  These include the <literal>seeotheruids</literal>,
+	<literal>portacl</literal> and <literal>partition</literal>
+	policies.</para>
+
+      <para>It should also be noted that using
+	<option>multilabel</option> with a partition and establishing
+	a security model based on <option>multilabel</option>
+	functionality could open the doors for higher administrative
+	overhead as everything in the file system would have a label.
+	This includes directories, files, and even device
+	nodes.</para>
+
+      <para>The following command will set <option>multilabel</option>
+	on the file systems to have multiple labels.  This may only be
+	done in single user mode:</para>
+
+      <screen>&prompt.root; <userinput>tunefs -l enable /</userinput></screen>
+
+      <para>This is not a requirement for the swap file
+	system.</para>
+
+      <note>
+	<para>Some users have experienced problems with setting the
+	  <option>multilabel</option> flag on the root partition.
+	  If this is the case, please review the
+	  <xref linkend="mac-troubleshoot"> of this chapter.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Controlling MAC with Tunables</title>
+
+      <para>Without any modules loaded, there are still some parts
+        of <acronym>MAC</acronym> which may be configured using
+	the <command>sysctl</command> interface.  These tunables
+	are described below and in all cases the number one (1)
+	means enabled while the number zero (0) means
+	disabled:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><literal>security.mac.enforce_fs</literal> defaults to
+	    one (1) and enforces <acronym>MAC</acronym> file system
+	    policies on the file systems.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_kld</literal> defaults to
+	    one (1) and enforces <acronym>MAC</acronym> kernel linking
+	    policies on the dynamic kernel linker (see
+	    &man.kld.4;).</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_network</literal> defaults
+	    to one (1) and enforces <acronym>MAC</acronym> network
+	    policies.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_pipe</literal> defaults
+	    to one (1) and enforces <acronym>MAC</acronym> policies
+	    on pipes.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_process</literal> defaults
+	    to one (1) and enforces <acronym>MAC</acronym> policies
+	    on processes which utilize inter-process
+	    communication.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_socket</literal> defaults
+	    to one (1) and enforces <acronym>MAC</acronym> policies
+	    on sockets (see the &man.socket.2; manual page).</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_system</literal> defaults
+	    to one (1) and enforces <acronym>MAC</acronym> policies
+	    on system activities such as accounting and
+	    rebooting.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>security.mac.enforce_vm</literal> defaults
+	    to one (1) and enforces <acronym>MAC</acronym> policies
+	    on the virtual memory system.</para>
+	</listitem>
+      </itemizedlist>
+
+      <note>
+	<para>Every policy or <acronym>MAC</acronym> option supports
+	  tunables.  These usually hang off of the
+	  <literal>security.mac.&lt;policyname&gt;</literal> tree.
+	  To view all of the tunables from <acronym>MAC</acronym>
+	  use the following command:</para>
+
+	<screen>&prompt.root; <userinput>sysctl -da | grep mac</userinput></screen>
+      </note>
+
+      <para>This should be interpreted as all of the basic
+	<acronym>MAC</acronym> policies are enforced by default.
+	If the modules were built into the kernel the system
+	would be extremely locked down and most likely unable to
+	communicate with the local network or connect to the Internet,
+	etc.  This is why building the modules into the kernel is not
+	completely recommended.  Not because it limits the ability to
+	disable features on the fly with <command>sysctl</command>,
+	but it permits the administrator to instantly switch the
+	policies of a system without the requirement of rebuilding
+	and reinstalling a new system.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-planning">
+    <title>Planning the Security Configuration</title>
+
+    <para>Whenever a new technology is implemented, a planning phase is
+      always a good idea.  During the planning stages, an administrator
+      should in general look at the <quote>big picture</quote>, trying
+      to keep in view at least the following:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The implementation requirements;</para>
+      </listitem>
+
+      <listitem>
+	<para>The implementation goals;</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>For <acronym>MAC</acronym> installations, these include:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>How to classify information and resources available on
+	  the target systems.</para>
+      </listitem>
+
+      <listitem>
+	<para>What sorts of information or resources to restrict
+	  access to along with the type of restrictions that should be
+	  applied.</para>
+      </listitem>
+
+      <listitem>
+	<para>Which <acronym>MAC</acronym> module or modules will be
+	  required to achieve this goal.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>It is always possible to reconfigure and change the
+      system resources and security settings, it is quite often very inconvenient to
+      search through the system and fix existing files and user
+      accounts.  Planning helps to ensure a trouble-free and efficient
+      trusted system implementation.  A trial run of the trusted system,
+      including the configuration, is often vital and definitely
+      beneficial <emphasis>before</emphasis> a <acronym>MAC</acronym>
+      implementation is used on production systems.  The idea of just
+      letting loose on a system
+      with <acronym>MAC</acronym> is like setting up for failure.</para>
+
+    <para>Different environments may have explicit needs and
+      requirements.  Establishing an in depth and complete security
+      profile will decrease the need of changes once the system
+      goes live.  As such, the future sections will cover the
+      different modules available to administrators; describe their
+      use and configuration; and in some cases provide insight on
+      what situations they would be most suitable for.  For instance,
+      a web server might roll out the &man.mac.biba.4; and
+      &man.mac.bsdextended.4; policies.  In other cases, a machine
+      with very few local users, the &man.mac.partition.4; might
+      be a good choice.</para>
+  </sect1>
+
+  <sect1 id="mac-modules">
+    <title>Module Configuration</title>
+
+    <para>Every module included with the <acronym>MAC</acronym>
+      framework may be either compiled into the kernel as noted above
+      or loaded as a run-time kernel module.
+      The recommended method is to add the module name to the
+      <filename>/boot/loader.conf</filename> file so that it will load
+      during the initial boot operation.</para>
+
+    <para>The following sections will discuss the various
+      <acronym>MAC</acronym> modules and cover their features.
+      Implementing them into a specific environment will also
+      be a consideration of this chapter.  Some modules support
+      the use of labeling, which is controlling access by enforcing
+      a label such as <quote>this is allowed and this is not</quote>.
+      A label configuration file may control how files may be accessed,
+      network communication can be exchanged, and more.  The previous
+      section showed how the <option>multilabel</option> flag could
+      be set on file systems to enable per-file or per-partition
+      access control.</para>
+
+    <para>A single label configuration would enforce only one label
+      across the system, that is why the <command>tunefs</command>
+      option is called <option>multilabel</option>.</para>
+
+    <sect2 id="mac-seeotheruids">
+      <title>The MAC seeotheruids Module</title>
+
+      <indexterm>
+        <primary>MAC See Other UIDs Policy</primary>
+      </indexterm>
+      <para>Module name: <filename>mac_seeotheruids.ko</filename></para>
+
+      <para>Kernel configuration line:
+        <literal>options MAC_SEEOTHERUIDS</literal></para>
+
+      <para>Boot option:
+	<literal>mac_seeotheruids_load="YES"</literal></para>
+
+      <para>The &man.mac.seeotheruids.4; module mimics and extends
+	the <literal>security.bsd.see_other_uids</literal> and
+	<literal>security.bsd.see_other_gids</literal>
+	<command>sysctl</command> tunables.  This option does
+	not require any labels to be set before configuration and
+	can operate transparently with the other modules.</para>
+
+      <para>After loading the module, the following
+	<command>sysctl</command> tunables may be used to control
+	the features:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><literal>security.mac.seeotheruids.enabled</literal>
+	    will enable the module's features and use the default
+	    settings.  These default settings will deny users the
+	    ability to view processes and sockets owned by other
+	    users.</para>
+	</listitem>
+
+	<listitem>
+	  <para>
+	    <literal>security.mac.seeotheruids.specificgid_enabled</literal>
+	    will allow a certain group to be exempt from this policy.
+	    To exempt specific groups from this policy, use the
+	    <literal>security.mac.seeotheruids.specificgid=<replaceable>XXX</replaceable></literal>
+	    <command>sysctl</command> tunable.  In the above example,
+	    the <replaceable>XXX</replaceable> should be replaced with the
+	    numeric group ID to be exempted.</para>
+	</listitem>
+
+	<listitem>
+	  <para>
+	    <literal>security.mac.seeotheruids.primarygroup_enabled</literal>
+	    is used to exempt specific primary groups from this policy.
+	    When using this tunable, the
+	    <literal>security.mac.seeotheruids.specificgid_enabled</literal>
+	    may not be set.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-bsdextended">
+    <title>The MAC bsdextended Module</title>
+
+    <indexterm>
+    <primary>MAC</primary>
+      <secondary>File System Firewall Policy</secondary>
+    </indexterm>
+    <para>Module name: <filename>mac_bsdextended.ko</filename></para>
+
+    <para>Kernel configuration line:
+      <literal>options MAC_BSDEXTENDED</literal></para>
+
+    <para>Boot option:
+      <literal>mac_bsdextended_load="YES"</literal></para>
+
+    <para>The &man.mac.bsdextended.4; module enforces the file system
+      firewall.  This module's policy provides an extension to the
+      standard file system permissions model, permitting an
+      administrator to create a firewall-like ruleset to protect files,
+      utilities, and directories in the file system hierarchy.  When
+      access to a file system object is attempted, the list of rules
+      is iterated until either a matching rule is located or the end
+      is reached.  This behavior may be changed by the use of a
+      &man.sysctl.8; parameter,
+      security.mac.bsdextended.firstmatch_enabled.  Similar to
+      other firewall modules in &os;, a file containing access control
+      rules can be created and read by the system at boot time using
+      an &man.rc.conf.5; variable.</para>
+
+    <para>The rule list may be entered using a utility, &man.ugidfw.8;,
+      that has a syntax similar to that of &man.ipfw.8;.  More tools
+      can be written by using the functions in the
+      &man.libugidfw.3; library.</para>
+
+    <para>Extreme caution should be taken when working with this
+      module; incorrect use could block access to certain parts of
+      the file system.</para>
+
+    <sect2>
+      <title>Examples</title>
+
+      <para>After the &man.mac.bsdextended.4; module has
+	been loaded, the following command may be used to list the
+	current rule configuration:</para>
+
+      <screen>&prompt.root; <userinput>ugidfw list</userinput>
+0 slots, 0 rules</screen>
+
+      <para>As expected, there are no rules defined.  This means that
+	everything is still completely accessible.  To create a rule
+	which will block all access by users but leave
+	<username>root</username> unaffected, simply run the
+	following command:</para>
+
+      <screen>&prompt.root; <userinput>ugidfw add subject not uid root new object not uid root mode n</userinput></screen>
+
+      <note>
+	<para>In releases prior to &os;&nbsp;5.3, the
+	  <parameter>add</parameter> parameter did not exist.  In those
+	  cases the <parameter>set</parameter> should be used
+	  instead.  See below for a command example.</para></note>
+
+      <para>This is a very bad idea as it will block all users from
+	issuing even the most simple commands, such as
+	<command>ls</command>.  A more patriotic list of rules
+	might be:</para>
+
+      <screen>&prompt.root; <userinput>ugidfw set 2 subject uid <replaceable>user1</replaceable> object uid <replaceable>user2</replaceable> mode n</userinput>
+&prompt.root; <userinput>ugidfw set 3 subject uid <replaceable>user1</replaceable> object gid <replaceable>user2</replaceable> mode n</userinput></screen>
+
+      <para>This will block any and all access, including directory
+	listings, to <username><replaceable>user2</replaceable></username>'s home
+	directory from the username <username>user1</username>.</para>
+
+      <para>In place of <username>user1</username>, the
+	<option>not uid <replaceable>user2</replaceable></option> could
+	be passed.  This will enforce the same access restrictions
+	above for all users in place of just one user.</para>
+
+      <note>
+	<para>The <username>root</username> user will be unaffected
+	    by these changes.</para>
+      </note>
+
+      <para>This should provide a general idea of how the
+	&man.mac.bsdextended.4; module may be used to help fortify
+	a file system.  For more information, see the
+	&man.mac.bsdextended.4; and the &man.ugidfw.8; manual
+	pages.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-ifoff">
+    <title>The MAC ifoff Module</title>
+
+    <indexterm>
+      <primary>MAC Interface Silencing Policy</primary>
+    </indexterm>
+    <para>Module name: <filename>mac_ifoff.ko</filename></para>
+
+    <para>Kernel configuration line:
+      <literal>options MAC_IFOFF</literal></para>
+
+    <para>Boot option: <literal>mac_ifoff_load="YES"</literal></para>
+
+    <para>The &man.mac.ifoff.4; module exists solely to disable network
+      interfaces on the fly and keep network interfaces from being
+      brought up during the initial system boot.  It does not require
+      any labels to be set up on the system, nor does it have a
+      dependency on other <acronym>MAC</acronym> modules.</para>
+
+    <para>Most of the control is done through the
+      <command>sysctl</command> tunables listed below.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>security.mac.ifoff.lo_enabled</literal> will
+	  enable/disable all traffic on the loopback (&man.lo.4;)
+	  interface.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.ifoff.bpfrecv_enabled</literal> will
+	  enable/disable all traffic on the Berkeley Packet Filter
+	  interface (&man.bpf.4;)</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.ifoff.other_enabled</literal> will
+	  enable/disable traffic on all other interfaces.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>One of the most common uses of &man.mac.ifoff.4; is network
+      monitoring in an environment where network traffic should not
+      be permitted during the boot sequence.  Another suggested use
+      would be to write a script which uses
+      <filename role="package">security/aide</filename> to automatically
+      block network traffic if it finds new or altered files in
+      protected directories.</para>
+  </sect1>
+
+  <sect1 id="mac-portacl">
+    <title>The MAC portacl Module</title>
+
+    <indexterm>
+      <primary>MAC Port Access Control List Policy</primary>
+    </indexterm>
+    <para>Module name: <filename>mac_portacl.ko</filename></para>
+
+    <para>Kernel configuration line:
+      <literal>MAC_PORTACL</literal></para>
+
+    <para>Boot option: <literal>mac_portacl_load="YES"</literal></para>
+
+    <para>The &man.mac.portacl.4; module is used to limit binding to
+      local <acronym>TCP</acronym> and <acronym>UDP</acronym> ports
+      using a variety of <command>sysctl</command> variables.  In
+      essence &man.mac.portacl.4; makes it possible to allow
+      non-<username>root</username> users to bind to specified
+      privileged ports, i.e. ports fewer than 1024.</para>
+
+    <para>Once loaded, this module will enable the
+      <acronym>MAC</acronym> policy on all sockets.  The following
+      tunables are available:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>security.mac.portacl.enabled</literal> will
+	  enable/disable the policy completely.<footnote><para>Due to
+	  a bug the <literal>security.mac.portacl.enabled</literal>
+	  <command>sysctl</command> variable will not work on
+	  &os;&nbsp;5.2.1 or previous releases.</para></footnote></para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.portacl.port_high</literal> will set
+	  the highest port number that &man.mac.portacl.4;
+	  will enable protection for.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.portacl.suser_exempt</literal> will,
+	  when set to a non-zero value, exempt the
+	  <username>root</username> user from this policy.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.portacl.rules</literal> will
+	  specify the actual mac_portacl policy; see below.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>The actual <literal>mac_portacl</literal> policy, as
+      specified in the <literal>security.mac.portacl.rules</literal>
+      sysctl, is a text string of the form:
+      <literal>rule[,rule,...]</literal> with as many rules as
+      needed.  Each rule is of the form:
+      <literal>idtype:id:protocol:port</literal>.  The
+      <parameter>idtype</parameter> parameter can be
+      <literal>uid</literal> or <literal>gid</literal> and used to
+      interpret the <parameter>id</parameter> parameter as either a
+      user id or group id, respectively.  The
+      <parameter>protocol</parameter> parameter is used to determine if
+      the rule should apply to <acronym>TCP</acronym> or
+      <acronym>UDP</acronym> by setting the parameter to
+      <literal>tcp</literal> or <literal>udp</literal>.  The final
+      <parameter>port</parameter> parameter is the port number to allow
+      the specified user or group to bind to.</para>
+
+    <note>
+      <para>Since the ruleset is interpreted directly by the kernel
+	only numeric values can be used for the user ID, group ID, and
+	port parameters.  I.e. user, group, and port service names
+	cannot be used.</para>
+    </note>
+
+    <para>By default, on &unix;-like systems, ports fewer than 1024
+      can only be used by/bound to privileged processes,
+      i.e. those run as <username>root</username>.  For
+      &man.mac.portacl.4; to allow non-privileged processes to bind
+      to ports below 1024 this standard &unix; restriction has to be
+      disabled.  This can be accomplished by setting the &man.sysctl.8;
+      variables <literal>net.inet.ip.portrange.reservedlow</literal> and
+      <literal>net.inet.ip.portrange.reservedhigh</literal>
+      to zero.</para>
+
+    <para>See the examples below or review the &man.mac.portacl.4;
+      manual page for further information.</para>
+
+    <sect2>
+      <title>Examples</title>
+
+      <para>The following examples should illuminate the above
+	discussion a little better:</para>
+
+      <screen>&prompt.root; <userinput>sysctl security.mac.portacl.port_high=1023</userinput>
+&prompt.root; <userinput>sysctl net.inet.ip.portrange.reservedlow=0 net.inet.ip.portrange.reservedhigh=0</userinput></screen>
+
+      <para>First we set &man.mac.portacl.4; to cover the standard
+	privileged ports and disable the normal &unix; bind
+	restrictions.</para>
+
+      <screen>&prompt.root; <userinput>sysctl security.mac.portacl.suser_exempt=1</userinput></screen>
+
+      <para>The <username>root</username> user should not be crippled
+	by this policy, thus set the
+	<literal>security.mac.portacl.suser_exempt</literal> to a
+	non-zero value.  The &man.mac.portacl.4; module
+	has now been set up to behave the same way &unix;-like systems
+	behave by default.</para>
+
+      <screen>&prompt.root; <userinput>sysctl security.mac.portacl.rules=uid:80:tcp:80</userinput></screen>
+
+      <para>Allow the user with <acronym>UID</acronym> 80 (normally
+	the <username>www</username> user) to bind to port 80.
+	This can be used to allow the <username>www</username>
+	user to run a web server without ever having
+	<username>root</username> privilege.</para>
+
+      <screen>&prompt.root; <userinput>sysctl security.mac.portacl.rules=uid:1001:tcp:110,uid:1001:tcp:995</userinput></screen>
+
+      <para>Permit the user with the <acronym>UID</acronym> of
+	1001 to	bind to the <acronym>TCP</acronym> ports 110
+	(<quote>pop3</quote>) and 995 (<quote>pop3s</quote>).
+	This will permit this user to start a server that accepts
+	connections on ports 110 and 995.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-partition">
+    <title>The MAC partition Module</title>
+
+    <indexterm>
+      <primary>MAC Process Partition Policy</primary>
+    </indexterm>
+    <para>Module name: <filename>mac_partition.ko</filename></para>
+
+    <para>Kernel configuration line:
+      <literal>options MAC_PARTITION</literal></para>
+
+    <para>Boot option:
+      <literal>mac_partition_load="YES"</literal></para>
+
+    <para>The &man.mac.partition.4; policy will drop processes into
+      specific <quote>partitions</quote> based on their
+      <acronym>MAC</acronym> label.  Think of it as a special
+      type of &man.jail.8;, though that is hardly a worthy
+      comparison.</para>
+
+    <para>This is one module that should be added to the
+      &man.loader.conf.5; file so that it loads
+      and enables the policy during the boot process.</para>
+
+    <para>Most configuration for this policy is done using
+      the &man.setpmac.8; utility which will be explained below.
+      The following <command>sysctl</command> tunable is
+      available for this policy:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>security.mac.partition.enabled</literal> will
+	  enable the enforcement of <acronym>MAC</acronym> process
+	  partitions.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>When this policy is enabled, users will only be permitted
+      to see their processes, and any others within their partition,
+      but will not be permitted to work with
+      utilities outside the scope of this partition.  For instance, a user in the
+      <literal>insecure</literal> class above will not be permitted
+      to access the <command>top</command> command as well as many
+      other commands that must spawn a process.</para>
+
+    <para>To set or drop utilities into a partition label, use the
+      <command>setpmac</command> utility:</para>
+
+    <screen>&prompt.root; <userinput>setpmac partition/13 top</userinput></screen>
+
+    <para>This will add the <command>top</command> command to the
+      label set on users in the <literal>insecure</literal> class.
+      Note that all processes spawned by users
+      in the <literal>insecure</literal> class will stay in the
+      <literal>partition/13</literal> label.</para>
+
+    <sect2>
+      <title>Examples</title>
+
+      <para>The following command will show you the partition label
+	and the process list:</para>
+
+      <screen>&prompt.root; <userinput>ps Zax</userinput></screen>
+
+      <para>This next command will allow the viewing of another
+	user's process partition label and that user's currently
+	running processes:</para>
+
+      <screen>&prompt.root; <userinput>ps -ZU trhodes</userinput></screen>
+
+      <note>
+	<para>Users can see processes in <username>root</username>'s
+	  label unless the &man.mac.seeotheruids.4; policy is
+	  loaded.</para>
+      </note>
+
+      <para>A really crafty implementation could have all of the
+	services disabled in <filename>/etc/rc.conf</filename> and
+	started by a script that starts them with the proper
+	labeling set.</para>
+
+      <note>
+	<para>The following policies support integer settings
+	  in place of the three default labels offered.  These options,
+	  including their limitations, are further explained in
+	  the module manual pages.</para>
+      </note>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-mls">
+    <title>The MAC Multi-Level Security Module</title>
+
+    <indexterm>
+      <primary>MAC Multi-Level Security Policy</primary>
+    </indexterm>
+    <para>Module name: <filename>mac_mls.ko</filename></para>
+
+    <para>Kernel configuration line:
+      <literal>options MAC_MLS</literal></para>
+
+    <para>Boot option: <literal>mac_mls_load="YES"</literal></para>
+
+    <para>The &man.mac.mls.4; policy controls access between subjects
+      and objects in the system by enforcing a strict information
+      flow policy.</para>
+
+    <para>In <acronym>MLS</acronym> environments, a
+      <quote>clearance</quote> level is set in each subject or objects
+      label, along with compartments.  Since these clearance or
+      sensibility levels can reach numbers greater than six thousand;
+      it would be a daunting task for any system administrator to
+      thoroughly configure each subject or object.  Thankfully, three
+      <quote>instant</quote> labels are already included in this
+      policy.</para>
+
+    <para>These labels are <literal>mls/low</literal>,
+      <literal>mls/equal</literal> and <literal>mls/high</literal>.
+      Since these labels are described in depth in the manual page,
+      they will only get a brief description here:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The <literal>mls/low</literal> label contains a low
+	  configuration which permits it to be dominated by all other
+	  objects.  Anything labeled with <literal>mls/low</literal>
+	  will have a low clearance level and not be permitted to access
+	  information of a higher level.  In addition, this label will
+	  prevent objects of a higher clearance level from writing or
+	  passing information on to them.</para>
+      </listitem>
+
+      <listitem>
+	<para>The <literal>mls/equal</literal> label should be
+	  placed on objects considered to be exempt from the
+	  policy.</para>
+      </listitem>
+
+      <listitem>
+	<para>The <literal>mls/high</literal> label is the highest level
+	  of clearance possible.  Objects assigned this label will
+	  hold dominance over all other objects in the system; however,
+	  they will not permit the leaking of information to objects
+	  of a lower class.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para><acronym>MLS</acronym> provides for:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>A hierarchical security level with a set of non
+	  hierarchical categories;</para>
+      </listitem>
+
+      <listitem>
+	<para>Fixed rules: no read up, no write down (a subject can
+	  have read access to objects on its own level or below, but
+	  not above.  Similarly, a subject can have write access to
+	  objects on its own level or above but not beneath.);</para>
+      </listitem>
+
+      <listitem>
+	<para>Secrecy (preventing inappropriate disclosure
+	  of data);</para>
+      </listitem>
+
+      <listitem>
+	<para>Basis for the design of systems that concurrently handle
+	  data at multiple sensitivity levels (without leaking
+	  information between secret and confidential).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>The following <command>sysctl</command> tunables are
+      available for the configuration of special services and
+      interfaces:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>security.mac.mls.enabled</literal> is used to
+	  enable/disable the <acronym>MLS</acronym> policy.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.mls.ptys_equal</literal> will label
+	  all &man.pty.4; devices as <literal>mls/equal</literal> during
+	  creation.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.mls.revocation_enabled</literal> is
+	  used to revoke access to objects after their label changes
+	  to a label of a lower grade.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.mls.max_compartments</literal> is
+	  used to set the maximum number of compartment levels with
+	  objects; basically the maximum compartment number allowed
+	  on a system.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>To manipulate the <acronym>MLS</acronym> labels, the
+      &man.setfmac.8; command has been provided.  To assign a label
+      to an object, issue the following command:</para>
+
+    <screen>&prompt.root; <userinput>setfmac mls/5 test</userinput></screen>
+
+    <para>To get the <acronym>MLS</acronym> label for the file
+      <filename>test</filename> issue the following command:</para>
+
+    <screen>&prompt.root; <userinput>getfmac test</userinput></screen>
+
+    <para>This is a summary of the <acronym>MLS</acronym>
+      policy's features.  Another approach is to create a master policy
+      file in <filename class="directory">/etc</filename> which
+      specifies the <acronym>MLS</acronym> policy information and to
+      feed that file into the <command>setfmac</command> command.  This
+      method will be explained after all policies are covered.</para>
+
+    <sect2>
+      <title>Planning Mandatory Sensitivity</title>
+
+      <para>With the Multi-Level Security Policy Module, an
+	administrator plans for controlling the flow of sensitive
+	information.  By default, with its block read up block write
+	down nature, the system defaults everything to a low state.
+	Everything is accessible and an administrator
+	slowly changes this during the configuration stage; augmenting
+	the confidentiality of the information.</para>
+
+      <para>Beyond the three basic label options above, an administrator
+	may group users and groups as required to block the information
+	flow between them.  It might be easier to look at the
+	information in clearance levels familiarized with words, for
+	instance classifications such as
+	<literal>Confidential</literal>, <literal>Secret</literal>,
+	and <literal>Top Secret</literal>.  Some administrators might
+	just create different groups based on project levels.
+	Regardless of classification method, a well thought out plan
+	must exist before implementing such a restrictive policy.</para>
+
+      <para>Some example situations for this security policy module
+	could be an e-commerce web server, a file server holding critical
+	company information, and financial institution environments.
+	The most unlikely place would be a personal workstation with
+	only two or three users.</para>
+  </sect1>
+
+  <sect1 id="mac-biba">
+    <title>The MAC Biba Module</title>
+
+    <indexterm>
+      <primary>MAC Biba Integrity Policy</primary>
+    </indexterm>
+    <para>Module name: <filename>mac_biba.ko</filename></para>
+
+    <para>Kernel configuration line: <literal>options MAC_BIBA</literal></para>
+
+    <para>Boot option: <literal>mac_biba_load="YES"</literal></para>
+
+    <para>The &man.mac.biba.4; module loads the <acronym>MAC</acronym>
+      Biba policy.  This policy works much like that of the
+      <acronym>MLS</acronym> policy with the exception that the rules
+      for information flow
+      are slightly reversed.  This is said to prevent the downward
+      flow of sensitive information whereas the <acronym>MLS</acronym>
+      policy prevents the upward flow of sensitive information; thus,
+      much of this section can apply to both policies.</para>
+
+    <para>In Biba environments, an <quote>integrity</quote> label is
+      set on each subject or object.  These labels are made up of
+      hierarchal grades, and non-hierarchal components.  As an object's
+      or subject's grade ascends, so does its integrity.</para>
+
+    <para>Supported labels are <literal>biba/low</literal>,
+      <literal>biba/equal</literal>, and <literal>biba/high</literal>;
+      as explained below:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The <literal>biba/low</literal> label is considered the
+	  lowest integrity an object or subject may have.  Setting
+	  this on objects or subjects will block their write access
+	  to objects or subjects marked high.  They still have read
+	  access though.</para>
+      </listitem>
+
+      <listitem>
+	<para>The <literal>biba/equal</literal> label should only be
+	  placed on objects considered to be exempt from the
+	  policy.</para>
+      </listitem>
+
+      <listitem>
+	<para>The <literal>biba/high</literal> label will permit
+	  writing to objects set at a lower label, but not
+	  permit reading that object.  It is recommended that this
+	  label be placed on objects that affect the integrity of
+	  the entire system.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Biba provides for:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Hierarchical integrity level with a set of non
+	  hierarchical integrity categories;</para>
+      </listitem>
+
+      <listitem>
+	<para>Fixed rules: no write up, no read down (opposite of
+	  <acronym>MLS</acronym>).  A subject can have write access
+	  to objects on its own level or below, but not above.  Similarly, a
+	  subject can have read access to objects on its own level
+	  or above, but not below;</para>
+      </listitem>
+
+      <listitem>
+	<para>Integrity (preventing inappropriate modification of
+	  data);</para>
+      </listitem>
+
+      <listitem>
+	<para>Integrity levels (instead of MLS sensitivity
+	  levels).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>The following <command>sysctl</command> tunables can
+      be used to manipulate the Biba policy.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><literal>security.mac.biba.enabled</literal> may be used
+	  to enable/disable enforcement of the Biba policy on the
+	  target machine.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.biba.ptys_equal</literal> may be
+	  used to disable the Biba policy on &man.pty.4;
+	  devices.</para>
+      </listitem>
+
+      <listitem>
+	<para><literal>security.mac.biba.revocation_enabled</literal>
+	  will force the revocation of access to objects if the label
+	  is changed to dominate the subject.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>To access the Biba policy setting on system objects, use
+      the <command>setfmac</command> and <command>getfmac</command>
+      commands:</para>
+
+    <screen>&prompt.root; <userinput>setfmac biba/low test</userinput>
+&prompt.root; <userinput>getfmac test</userinput>
+test: biba/low</screen>
+
+    <sect2>
+      <title>Planning Mandatory Integrity</title>
+
+      <para>Integrity, different from sensitivity, guarantees that the
+	information will never be manipulated by untrusted parties.
+	This includes information passed between subjects, objects,
+	and both.  It ensures that users will only be able to modify
+	and in some cases even access information they explicitly need
+	to.</para>
+
+      <para>The &man.mac.biba.4; security policy module permits an
+ 	administrator to address which files and programs a user or
+	users may see and invoke while assuring that the programs and
+	files are free from threats and trusted by the system for that
+	user, or group of users.</para>
+
+      <para>During the initial planning phase, an administrator must be
+	prepared to partition users into grades, levels, and areas.
+	Users will be blocked access not only to data but programs
+	and utilities both before and after they start.  The system will
+	default to a high label once this policy module is enabled, and
+	it is up to the administrator to configure the different grades
+	and levels for users.  Instead of using clearance levels as
+	described above, a good planning method could include topics.
+	For instance, only allow developers modification access to the source code
+	repository, source code compiler, and other development
+	utilities.  While other users would be grouped into other
+	categories such as testers, designers, or just ordinary
+	users and would only be permitted read access.</para>
+	
+      <para>With its natural security control, a lower integrity subject
+	is unable to write to a higher integrity subject; a higher
+	integrity subject cannot observe or read a lower integrity
+	object.  Setting a label at the lowest possible grade could make
+	it inaccessible to subjects.  Some prospective environments for
+	this security policy module would include a constrained web
+	server, development and test machine, and source code
+	repository.  A less useful implementation would be a personal
+	workstation, a machine used as a router, or a network
+	firewall.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-lomac">
+    <title>The MAC LOMAC Module</title>
+
+    <indexterm>
+      <primary>MAC LOMAC</primary>
+    </indexterm>
+    <para>Module name: <filename>mac_lomac.ko</filename></para>
+
+    <para>Kernel configuration line: <literal>options MAC_LOMAC</literal></para>
+    <para>Boot option: <literal>mac_lomac_load="YES"</literal></para>
+
+    <para>Unlike the <acronym>MAC</acronym> Biba policy, the
+      &man.mac.lomac.4; policy permits access to lower integrity
+      objects only after decreasing the integrity level to not disrupt
+      any integrity rules.</para>
+
+    <para>The <acronym>MAC</acronym> version of the Low-watermark
+      integrity policy, not to be confused with the older &man.lomac.4;
+      implementation, works almost identically to Biba, but with the
+      exception of using floating labels to support subject
+      demotion via an auxiliary grade compartment.  This secondary
+      compartment takes the form of <literal>[auxgrade]</literal>.
+      When assigning a lomac policy with an auxiliary grade, it
+      should look a little bit like: <literal>lomac/10[2]</literal>
+      where the number two (2) is the auxiliary grade.</para>
+
+    <para>The <acronym>MAC</acronym> LOMAC policy relies on the
+      ubiquitous labeling of all system objects with integrity labels,
+      permitting subjects to read from low integrity objects and then
+      downgrading the label on the subject to prevent future writes to
+      high integrity objects.  This is the
+      <literal>[auxgrade]</literal> option discussed above, thus the
+      policy may provide for greater compatibility and require less
+      initial configuration than Biba.</para>
+
+    <sect2>
+      <title>Examples</title>
+
+      <para>Like the Biba and <acronym>MLS</acronym> policies;
+	the <command>setfmac</command> and <command>setpmac</command>
+	utilities may be used to place labels on system objects:</para>
+
+      <screen>&prompt.root; <userinput>setfmac /usr/home/trhodes lomac/high[low]</userinput>
+&prompt.root; <userinput>getfmac /usr/home/trhodes</userinput> lomac/high[low]</screen>
+
+      <para>Notice the auxiliary grade here is <literal>low</literal>,
+	this is a feature provided only by the <acronym>MAC</acronym>
+	LOMAC policy.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-implementing">
+    <title>Nagios in a MAC Jail</title>
+
+    <indexterm>
+      <primary>Nagios in a MAC Jail</primary>
+    </indexterm>
+
+    <para>The following demonstration will implement a secure
+      environment using various <acronym>MAC</acronym> modules
+      with properly configured policies.  This is only a test and
+      should not be considered the complete answer to everyone's
+      security woes.  Just implementing a policy and ignoring it
+      never works and could be disastrous in a production
+      environment.</para>
+
+    <para>Before beginning this process, the
+      <literal>multilabel</literal> option must be set on each file
+      system as stated at the beginning of this chapter.  Not doing
+      so will result in errors.  While at it, ensure that the
+      <filename role="port">net-mngt/nagios-plugins</filename>,
+      <filename role="port">net-mngt/nagios</filename>, and
+      <filename role="port">www/apache13</filename> ports are all
+      installed, configured, and working correctly.</para>
+
+    <sect2>
+      <title>Create an insecure User Class</title>
+
+      <para>Begin the procedure by adding the following user class
+       to the <filename>/etc/login.conf</filename> file:</para>
+
+      <programlisting>insecure:\
+:copyright=/etc/COPYRIGHT:\
+:welcome=/etc/motd:\
+:setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\
+:path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin
+:manpath=/usr/share/man /usr/local/man:\
+:nologin=/usr/sbin/nologin:\
+:cputime=1h30m:\
+:datasize=8M:\
+:vmemoryuse=100M:\
+:stacksize=2M:\
+:memorylocked=4M:\
+:memoryuse=8M:\
+:filesize=8M:\
+:coredumpsize=8M:\
+:openfiles=24:\
+:maxproc=32:\
+:priority=0:\
+:requirehome:\
+:passwordtime=91d:\
+:umask=022:\
+:ignoretime@:\
+:label=biba/10(10-10):</programlisting>
+
+      <para>And adding the following line to the default user
+	class:</para>
+
+      <programlisting>:label=biba/high:</programlisting>
+
+      <para>Once this is completed, the following command must be
+	issued to rebuild the database:</para>
+
+      <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Boot Configuration</title>
+
+      <para>Do not reboot yet, just add the following lines to
+	<filename>/boot/loader.conf</filename> so the required
+	modules will load during system initialization:</para>
+
+      <programlisting>mac_biba_load="YES"
+mac_seeotheruids_load="YES"</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Configure Users</title>
+
+      <para>Set the <username>root</username> user to the default
+	class using:</para>
+
+      <screen>&prompt.root; <userinput>pw usermod root -L default</userinput></screen>
+
+      <para>All user accounts that are not <username>root</username>
+	or system users will now require a login class.  The login
+	class is required otherwise users will be refused access
+	to common commands such as &man.vi.1;.
+	The following <command>sh</command> script should do the
+	trick:</para>
+
+      <screen>&prompt.root; <userinput>for x in `awk -F: '($3 &gt;= 1001) &amp;&amp; ($3 != 65534) { print $1 }' \</userinput>
+	<userinput>/etc/passwd`; do pw usermod $x -L default; done;</userinput></screen>
+
+      <para>Drop the <username>nagios</username> and
+	<username>www</username> users into the insecure class:</para>
+
+      <screen>&prompt.root; <userinput>pw usermod nagios -L insecure</userinput></screen>
+      <screen>&prompt.root; <userinput>pw usermod www -L insecure</userinput></screen>      
+    </sect2>
+
+    <sect2>
+      <title>Create the Contexts File</title>
+
+      <para>A contexts file should now be created; the following example
+	file should be placed in
+	<filename>/etc/policy.contexts</filename>.</para>
+
+      <programlisting># This is the default BIBA policy for this system.
+
+# System:
+/var/run                        biba/equal
+/var/run/*                      biba/equal
+
+/dev                            biba/equal
+/dev/*                          biba/equal
+
+/var				biba/equal
+/var/spool                      biba/equal
+/var/spool/*                    biba/equal
+
+/var/log                        biba/equal
+/var/log/*                      biba/equal
+
+/tmp				biba/equal
+/tmp/*				biba/equal
+/var/tmp			biba/equal
+/var/tmp/*			biba/equal
+
+/var/spool/mqueue		biba/equal
+/var/spool/clientmqueue		biba/equal
+
+# For Nagios:
+/usr/local/etc/nagios
+/usr/local/etc/nagios/*         biba/10
+
+/var/spool/nagios               biba/10
+/var/spool/nagios/*             biba/10
+
+# For apache
+/usr/local/etc/apache           biba/10
+/usr/local/etc/apache/*         biba/10</programlisting>
+
+      <para>This policy will enforce security by setting restrictions
+	on the flow of information.  In this specific configuration,
+	users, <username>root</username> and others, should never be
+	allowed to access <application>Nagios</application>.
+	Configuration files and processes that are a part of
+	<application>Nagios</application> will be completely self
+	contained or jailed.</para>
+
+      <para>This file may now be read into our system by issuing the
+	following command:</para>
+
+      <screen>&prompt.root; <userinput>setfsmac -ef /etc/policy.contexts /</userinput>
+&prompt.root; <userinput>setfsmac -ef /etc/policy.contexts /</userinput></screen>
+
+      <note>
+	<para>The above file system layout may be different depending
+	  on environment; however, it must be run on every single file
+	  system.</para>
+      </note>
+
+      <para>The <filename>/etc/mac.conf</filename> file requires
+	the following modifications in the main section:</para>
+
+      <programlisting>default_labels file ?biba
+default_labels ifnet ?biba
+default_labels process ?biba
+default_labels socket ?biba</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Enable Networking</title>
+
+      <para>Add the following line to
+	<filename>/boot/loader.conf</filename>:</para>
+
+      <programlisting>security.mac.biba.trust_all_interfaces=1</programlisting>
+
+      <para>And the following to the network card configuration stored
+	in <filename>rc.conf</filename>.  If the primary Internet
+	configuration is done via <acronym>DHCP</acronym>, this may
+	need to be configured manually after every system boot:</para>
+
+      <programlisting>maclabel biba/equal</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Testing the Configuration</title>
+
+      <indexterm>
+	<primary>MAC Configuration Testing</primary>
+      </indexterm>
+
+      <para>Ensure that the web server and
+	<application>Nagios</application> will not be started
+	on system initialization, and reboot.  Ensure the
+	<username>root</username> user cannot access any of the files
+	in the <application>Nagios</application> configuration
+	directory.  If <username>root</username> can issue an &man.ls.1;
+	command on <filename>/var/spool/nagios</filename>, then something
+	is wrong.  Otherwise a <quote>permission denied</quote> error
+	should be returned.</para>
+
+      <para>If all seems well, <application>Nagios</application>,
+	<application>Apache</application>, and
+	<application>Sendmail</application> can now be started in a way
+	fitting of the security policy.  The following commands will
+	make this happen:</para>
+
+      <screen>&prompt.root; <userinput>cd /etc/mail &amp;&amp; make stop &amp;&amp; \
+setpmac biba/equal make start &amp;&amp; setpmac biba/10\(10-10\) apachectl start &amp;&amp; \
+setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></screen>
+
+      <para>Double check to ensure that everything is working
+	properly.  If not, check the log files or error messages.  Use
+	the &man.sysctl.8; utility to disable the &man.mac.biba.4;
+	security policy module enforcement and try starting everything
+	again, like normal.</para>
+
+      <note>
+	<para>The <username>root</username> user can change the security
+	  enforcement and edit the configuration files without fear.
+	  The following command will permit the degradation of the
+	  security policy to a lower grade for a newly spawned
+	  shell:</para>
+
+	<screen>&prompt.root; <userinput>setpmac biba/10 csh</userinput></screen>
+
+	<para>To block this from happening, force the user into a range
+	  via &man.login.conf.5;.  If &man.setpmac.8; attempts to run
+	  a command outside of the compartment's range, an error will
+	  be returned and the command will not be executed.  In this
+	  case, setting root to
+	  <literal>biba/high(high-high)</literal>.</para>
+      </note>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mac-userlocked">
+    <title>User Lock Down</title>
+
+    <para>This example considers a relatively small, fewer than fifty
+      users, storage system.  Users would have login capabilities, and
+      be permitted to not only store data but access resources as
+      well.</para>
+
+    <para>For this scenario, the &man.mac.bsdextended.4; mixed with
+      &man.mac.seeotheruids.4; could co-exist and block access not
+      only to system objects but to hide user processes as well.
+
+    <para>Begin by adding the following lines to
+      <filename>/boot/loader.conf</filename>:</para>
+
+    <programlisting>mac_seeotheruids_enabled="YES"</programlisting>
+
+    <para>The &man.mac.bsdextended.4; security policy module may be
+      activated through the use of the following rc.conf
+      variable:</para>
+
+    <programlisting>ugidfw_enable="YES"</programlisting>
+
+    <para>Default rules stored in
+      <filename>/etc/rc.bsdextended</filename> will be loaded at system
+      initialization; however, the default entries may need
+      modification.  Since this machine is expected only to service
+      users, everything may be left commented out except the last
+      two.  These will force the loading of user owned system objects
+      by default.</para>
+
+    <para>Add the required users to this machine and reboot.  For
+      testing purposes, try logging in as a different user across two
+      consoles.  Run the <command>ps aux</command> command to see if
+      processes of other users are visible.  Try to run &man.ls.1; on
+      another users home directory, it should fail.</para>
+
+    <para>Do not try to test with the <username>root</username> user
+      unless the specific <command>sysctl</command>s have been modified
+      to block super user access.</para>
+
+    <note>
+      <para>When a new user is added, their &man.mac.bsdextended.4;
+	rule will not be in the ruleset list.  To update the ruleset
+	quickly, simply unload the security policy module and reload
+	it again using the &man.kldunload.8; and &man.kldload.8;
+	utilities.</para>
+    </note>
+  </sect1>
+
+  <sect1 id="mac-troubleshoot">
+    <title>Troubleshooting the MAC Framework</title>
+
+    <indexterm>
+      <primary>MAC Troubleshooting</primary>
+    </indexterm>
+
+    <para>During the development stage, a few users reported problems
+      with normal configuration.  Some of these problems
+      are listed below:</para>
+
+    <sect2>
+      <title>The <option>multilabel</option> option cannot be enabled on
+	<filename>/</filename></title>
+
+      <para>The <option>multilabel</option> flag does not stay
+	enabled on my root (<filename>/</filename>) partition!</para>
+
+
+      <para>It seems that one out of every fifty users has this
+	problem, indeed, we had this problem during our initial
+	configuration.  Further observation of this so called
+	<quote>bug</quote> has lead me to believe that it is a
+	result of either incorrect documentation or misinterpretation
+	of the documentation.  Regardless of why it happened, the
+	following steps may be taken to resolve it:</para>
+
+      <procedure>
+	<step>
+	  <para>Edit <filename>/etc/fstab</filename> and set the root
+	    partition at <option>ro</option> for read-only.</para>
+	</step>
+
+	<step>
+	  <para>Reboot into single user mode.</para>
+	</step>
+
+	<step>
+	  <para>Run <command>tunefs</command> <option>-l enable</option>
+	    on <filename>/</filename>.</para>
+	</step>
+
+	<step>
+	  <para>Reboot the system into normal mode.</para>
+	</step>
+
+	<step>
+	  <para>Run <command>mount</command> <option>-urw</option>
+	  <filename>/</filename> and change the <option>ro</option>
+	  back to <option>rw</option> in <filename>/etc/fstab</filename>
+	  and reboot the system again.</para>
+	</step>
+
+	<step>
+	  <para>Double-check the output from the
+	  <command>mount</command> to ensure that
+	  <option>multilabel</option> has been properly set on the
+	  root file system.</para>
+	</step>
+     </procedure>
+    </sect2>
+
+    <sect2>
+      <title>Cannot start a X11 server after <acronym>MAC</acronym></title>
+
+      <para>After establishing a secure environment with
+	<acronym>MAC</acronym>, I am no longer able to start
+	X!</para>
+
+      <para>This could be caused by the <acronym>MAC</acronym>
+	<literal>partition</literal> policy or by a mislabeling in
+	one of the <acronym>MAC</acronym> labeling policies.  To
+	debug, try the following:</para>
+
+      <procedure>
+	<step>
+	  <para>Check the error message; if the user is in the
+	    <literal>insecure</literal> class, the
+	    <literal>partition</literal> policy may be the culprit.
+	    Try setting the user's class back to the
+	    <literal>default</literal> class and rebuild the database
+	    with the <command>cap_mkdb</command> command.  If this
+	    does not alleviate the problem, go to step two.</para>
+	</step>
+
+	<step>
+	  <para>Double-check the label policies.  Ensure that the
+	    policies are set correctly for the user in question, the
+	    X11 application, and
+	    the <filename class="directory">/dev</filename>
+	    entries.</para>
+	</step>
+
+	<step>
+	  <para>If neither of these resolve the problem, send the
+	    error message and a description of your environment to
+	    the TrustedBSD discussion lists located at the
+	    <ulink url="http://www.TrustedBSD.org">TrustedBSD</ulink>
+	    website or to the &a.questions;
+	    mailing list.</para>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2>
+      <title>Error: &man..secure.path.3; cannot stat <filename>.login_conf</filename></title>
+
+      <para>When I attempt to switch from the <username>root</username>
+	to another user in the system, the error message
+	<errorname>_secure_path: unable to state .login_conf</errorname>.</para>
+
+      <para>This message is usually shown when the user has a higher
+	label setting then that of the user whom they are attempting to
+	become.  For instance a user on the system,
+	<username>joe</username>, has a	default label of
+	<option>biba/low</option>.  The <username>root</username> user,
+	who has a label of <option>biba/high</option>, cannot view
+	<username>joe</username>'s home directory.  This will happen
+	regardless if <username>root</username> has used the
+	<command>su</command> command to become <username>joe</username>,
+	or not.  In this scenario, the Biba integrity model will not
+	permit <username>root</username> to view objects set at a lower
+	integrity level.</para>
+    </sect2>
+
+    <sect2>
+      <title>The <username>root</username> username is broken!</title>
+
+      <para>In normal or even single user mode, the
+	<username>root</username> is not recognized.  The
+	<command>whoami</command> command returns 0 (zero) and
+	<command>su</command> returns <errorname>who are you?</errorname>.
+	What could be going on?</para>
+
+      <para>This can happen if a labeling policy has been disabled,
+	either by a &man.sysctl.8; or the policy module was unloaded.
+	If the policy is being disabled or has been temporarily
+	disabled, then the login capabilities database needs to be
+	reconfigured with the <option>label</option> option being
+	removed.  Double check the <filename>login.conf</filename>
+	file to ensure that all <option>label</option> options have
+	been removed and rebuild the database with the
+	<command>cap_mkdb</command> command.</para>
+
+      <para>This may also happen if a policy restricts access to the
+	<filename>master.passwd</filename> file or database.  Usually
+	caused by an administrator altering the file under a label
+	which conflicts with the general policy being used by the
+	system.  In these cases, the user information would be read
+	by the system and access would be blocked as the file has
+	inherited the new label.  Disable the policy via a
+	&man.sysctl.8; and everything should return to normal.</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/pl_PL.ISO8859-2/books/handbook/mail/Makefile b/pl_PL.ISO8859-2/books/handbook/mail/Makefile
new file mode 100644
index 0000000000..538dff091f
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/mail/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	mail/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/mail/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/mail/chapter.sgml
new file mode 100644
index 0000000000..b6a04bf11d
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/mail/chapter.sgml
@@ -0,0 +1,2323 @@
+<!--
+     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 id="mail-synopsis">
+    <title>Synopsis</title>
+    <indexterm><primary>email</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 &os;, as well as an
+      introduction to sending and receiving email using &os;; 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>The difference between remote and
+	  local mailboxes.</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 use SMTP with UUCP.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up the system to send mail only.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use mail with a dialup connection.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to configure SMTP Authentication for added security.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to install and use a Mail User Agent, such as
+	  <application>mutt</application> to send and receive email.</para>
+      </listitem>
+
+      <listitem>
+
+        <para>How to download your mail from a remote <acronym>POP</acronym>
+	  or <acronym>IMAP</acronym> server.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to automatically apply filters and rules to incoming
+	  email.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Properly set up your network connection
+	  (<xref linkend="advanced-networking">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Properly set up the DNS information for your mail host
+	  (<xref linkend="network-servers">).</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
+      remote or local mailbox</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 <command>mail</command>, and <acronym>GUI</acronym> 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 <acronym>TCP</acronym>.</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>&os; ships with <application>sendmail</application> by
+	default, but also support numerous other mail server daemons,
+	just some of which include:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><application>exim</application>;</para>
+	</listitem>
+
+	<listitem>
+	  <para><application>postfix</application>;</para>
+	</listitem>
+
+	<listitem>
+	  <para><application>qmail</application>.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>The server daemon usually has two functions&mdash;it is responsible
+	for receiving incoming mail as well as delivering outgoing mail.  It is
+	<emphasis>not</emphasis> responsible for the collection of mail using protocols
+	such as <acronym>POP</acronym> or <acronym>IMAP</acronym> to
+	read your email, nor does it allow connecting to local
+	<filename>mbox</filename> or Maildir mailboxes.  You may require
+	an additional <link linkend="mail-receive">daemon</link> for
+	that.</para>
+
+      <warning>
+	<para>Older versions of <application>sendmail</application>
+	  have some serious security issues which may result in an
+	  attacker gaining local and/or remote access to your machine.
+	  Make sure that you are running a current version to avoid
+	  these problems.  Optionally, install an alternative
+	  <acronym>MTA</acronym> from the <link linkend="ports">&os;
+	  Ports Collection</link>.</para>
+      </warning>
+    </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 remote site in the DNS to determine the
+	host that will receive mail for the destination.  This process
+	also occurs when mail is sent from a remote host to your mail
+	server.</para>
+
+      <indexterm>
+	<primary>MX record</primary>
+      </indexterm>
+
+      <para><acronym>DNS</acronym> is responsible for mapping
+	hostnames to IP addresses, as well as for storing information
+	specific to mail delivery, known as MX records.  The MX (Mail
+	eXchanger) record specifies which host, or hosts, will receive
+	mail for a particular domain.  If you do not have an MX record
+	for your hostname or domain, the mail will be delivered
+	directly to your host provided you have an A record pointing
+	your hostname to your IP address.</para>
+
+      <para>You may view the MX records for any domain by using the
+	&man.host.1; command, as seen in the example below:</para>
+
+      <screen>&prompt.user; <userinput>host -t mx FreeBSD.org</userinput>
+FreeBSD.org mail is handled (pri=10) by mx1.FreeBSD.org</screen>
+    </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 all mail sent to your domain and store it
+	either in <filename>mbox</filename> (the default method for storing mail) or Maildir format, depending
+	on your configuration.
+	Once mail has been stored, it may either be read locally using
+	applications such as &man.mail.1; or
+	<application>mutt</application>, or remotely accessed and
+	collected using protocols such as 
+	<acronym>POP</acronym> or <acronym>IMAP</acronym>.
+	This means that should you only
+	wish to read mail locally, you are not required to install a
+	<acronym>POP</acronym> or <acronym>IMAP</acronym> server.</para>
+
+      <sect3 id="pop-and-imap">
+        <title>Accessing remote mailboxes using <acronym>POP</acronym> and <acronym>IMAP</acronym></title>
+
+        <indexterm><primary>POP</primary></indexterm>
+        <indexterm><primary>IMAP</primary></indexterm>
+	<para>In order to access mailboxes remotely, you are required to
+	  have access to a <acronym>POP</acronym> or <acronym>IMAP</acronym>
+	  server.  These protocols allow users to connect to their mailboxes from
+	  remote locations with ease.  Though both
+	  <acronym>POP</acronym> and <acronym>IMAP</acronym> allow users
+	  to remotely access mailboxes, <acronym>IMAP</acronym> offers
+	  many advantages, some of which are:</para>
+
+        <itemizedlist>
+          <listitem>
+	    <para><acronym>IMAP</acronym> can store messages on a remote
+	      server as well as fetch them.</para>
+          </listitem>
+
+          <listitem>
+	    <para><acronym>IMAP</acronym> supports concurrent updates.</para>
+          </listitem>
+
+          <listitem>
+	    <para><acronym>IMAP</acronym> can be extremely useful over
+	      low-speed links as it allows users to fetch the structure
+	      of messages without downloading them; it can also
+	      perform tasks such as searching on the server in
+	      order to minimize data transfer between clients and
+	      servers.</para>
+          </listitem>
+
+        </itemizedlist>
+
+        <para>In order to install a <acronym>POP</acronym> or
+	  <acronym>IMAP</acronym> server, the following steps should be
+	  performed:</para>
+
+        <procedure>
+	  <step>
+	    <para>Choose an <acronym>IMAP</acronym> or
+	      <acronym>POP</acronym> server that best suits your needs.
+	      The following <acronym>POP</acronym> and
+	      <acronym>IMAP</acronym> servers are well known and serve
+	      as some good examples:</para>
+
+	      <itemizedlist>
+	        <listitem>
+		  <para><application>qpopper</application>;</para>
+	        </listitem>
+
+	        <listitem>
+		  <para><application>teapop</application>;</para>
+	        </listitem>
+
+	        <listitem>
+		  <para><application>imap-uw</application>;</para>
+	        </listitem>
+
+	        <listitem>
+		  <para><application>courier-imap</application>;</para>
+	        </listitem>
+	      </itemizedlist>
+
+	  </step>
+
+          <step>
+	    <para>Install the <acronym>POP</acronym> or
+	      <acronym>IMAP</acronym> daemon of your choosing from the
+	      ports
+	      collection.</para>
+	  </step>
+
+	  <step>
+	    <para>Where required, modify <filename>/etc/inetd.conf</filename>
+	      to load the <acronym>POP</acronym> or
+	      <acronym>IMAP</acronym> server.</para>
+	  </step>
+        </procedure>
+
+	<warning>
+	  <para>It should be noted that both <acronym>POP</acronym> and
+	    <acronym>IMAP</acronym> transmit information, including
+	    username and password credentials in clear-text.  This means
+	    that if you wish to secure the transmission of information
+	    across these protocols, you should consider tunneling
+	    sessions over &man.ssh.1;.  Tunneling sessions is
+	    described in <xref linkend="security-ssh-tunneling">.</para>
+        </warning>
+      </sect3>
+
+      <sect3 id="local">
+        <title>Accessing local mailboxes</title>
+
+	<para>Mailboxes may be accessed locally by directly utilizing
+	  <acronym>MUA</acronym>s on the server on which the mailbox
+	  resides.  This can be done using applications such as
+	  <application>mutt</application> or &man.mail.1;.
+	</para>
+      </sect3>
+    </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 (<acronym>MUA</acronym>) 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 frame="none" pgwide="1">
+      <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 do not accept mail from spammers
+FREE.STEALTH.MAILER@            550 We do not 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 <email>user@example.com</email>.  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
+      <email>root@example.com</email> to the local mailbox <username>root</username>.  The next entry maps
+      <email>postmaster@example.com</email> 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 will not 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 id="mail-disable-sendmail">
+      <title>Disable <application>sendmail</application></title>
+
+      <para>The procedure used to start
+	<application>sendmail</application> changed significantly
+	between 4.5-RELEASE, 4.6-RELEASE, and later releases.
+	Therefore, the procedure used to disable it is subtly
+	different.</para>
+
+	<warning>
+	  <para>If you disable <application>sendmail</application>'s
+	    outgoing mail service, it is important that you replace it
+	    with an 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 to send
+	    e-mail after you have disabled them, mail could go into an
+	    inactive <application>sendmail</application> queue, and
+	    never be delivered.</para>
+	</warning>
+
+      <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>, including the outgoing
+	  mail service, you must use</para>
+
+	  <programlisting>sendmail_enable="NONE"</programlisting>
+
+	  <para>in <filename>/etc/rc.conf.</filename></para>
+
+	<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>.  However, if
+	  incoming mail is disabled, local delivery will still
+	  function.  More information on 
+	  <application>sendmail</application>'s startup options is
+	  available from the &man.rc.sendmail.8; manual page.</para>
+      </sect3>
+
+      <sect3>
+	<title>FreeBSD 5.0-STABLE and Later</title>
+
+	<para>In order to completely disable
+	  <application>sendmail</application>, including the outgoing
+	  mail service, you must use</para>
+
+	  <programlisting>sendmail_enable="NO"
+sendmail_submit_enable="NO"
+sendmail_outbound_enable="NO"
+sendmail_msp_queue_enable="NO"</programlisting>
+
+	  <para>in <filename>/etc/rc.conf.</filename></para>
+
+	<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>
+
+    <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>
+
+      <indexterm>
+	<primary>MX record</primary>
+      </indexterm>
+
+      <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'm getting these error messages:
+
+553 MX list for domain.net points back to relay.domain.net
+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
+[known as /etc/sendmail.cw prior to version 8.10]
+(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>
+	<indexterm>
+	  <primary>MX record</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 <acronym>POP</acronym> server is available, 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 role="nolink">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 is 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-UUCP">
+  <title>SMTP with UUCP</title>
+
+    <para>The <application>sendmail</application> configuration that ships with FreeBSD is
+      designed for sites that connect directly to the Internet.  Sites
+      that wish to exchange their mail via UUCP must install another
+      <application>sendmail</application> configuration file.</para>
+
+    <para>Tweaking <filename>/etc/mail/sendmail.cf</filename> manually
+      is an advanced topic. <application>sendmail</application> version 8 generates config files
+      via &man.m4.1; preprocessing, where the actual configuration
+      occurs on a higher abstraction level. The &man.m4.1;
+      configuration files can be found under
+      <filename>/usr/src/usr.sbin/sendmail/cf</filename>.</para>
+
+    <para>If you did not install your system with full sources, the
+      <application>sendmail</application> configuration set has been broken out into a separate source
+      distribution tarball. Assuming you have your FreeBSD source code
+      CDROM mounted, do:</para>
+
+    <screen>&prompt.root; <userinput>cd /cdrom/src</userinput>
+&prompt.root; <userinput>cat scontrib.?? | tar xzf - -C /usr/src/contrib/sendmail</userinput></screen>
+
+    <para>This extracts to only a few hundred kilobytes.  The file
+      <filename>README</filename> in the <filename>cf</filename>
+      directory can serve as a basic introduction to &man.m4.1;
+      configuration.</para>
+
+    <para>The best way to support UUCP delivery is to use the
+      <literal>mailertable</literal> feature.  This creates a database
+      that <application>sendmail</application> can use to make routing decisions.</para>
+
+    <para>First, you have to create your <filename>.mc</filename>
+      file.  The directory
+      <filename>/usr/src/usr.sbin/sendmail/cf/cf</filename> contains a
+      few examples.  Assuming you have named your file
+      <filename>foo.mc</filename>, all you need to do in order to
+      convert it into a valid <filename>sendmail.cf</filename>
+      is:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail/cf/cf</userinput>
+&prompt.root; <userinput>make foo.cf</userinput>
+&prompt.root; <userinput>cp foo.cf /etc/mail/sendmail.cf</userinput></screen>
+
+    <para>A typical <filename>.mc</filename> file might look
+        like:</para>
+
+    <programlisting>VERSIONID(`<replaceable>Your version number</replaceable>') OSTYPE(bsd4.4)
+
+FEATURE(accept_unresolvable_domains)
+FEATURE(nocanonify)
+FEATURE(mailertable, `hash -o /etc/mail/mailertable')
+
+define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>)
+define(`UUCP_MAX_SIZE', 200000)
+define(`confDONT_PROBE_INTERFACES')
+
+MAILER(local)
+MAILER(smtp)
+MAILER(uucp)
+
+Cw    <replaceable>your.alias.host.name</replaceable>
+Cw    <replaceable>youruucpnodename.UUCP</replaceable></programlisting>
+
+    <para>The lines containing
+      <literal>accept_unresolvable_domains</literal>,
+      <literal>nocanonify</literal>, and
+      <literal>confDONT_PROBE_INTERFACES</literal> features will
+      prevent any usage of the DNS during mail delivery.  The
+      <literal>UUCP_RELAY</literal> clause is needed to support UUCP
+      delivery.  Simply put an Internet hostname there that is able to
+      handle .UUCP pseudo-domain addresses; most likely, you will
+      enter the mail relay of your ISP there.</para>
+
+    <para>Once you have this, you need an
+      <filename>/etc/mail/mailertable</filename> file.  If you have
+      only one link to the outside that is used for all your mails,
+      the following file will suffice:</para>
+
+    <programlisting>#
+# makemap hash /etc/mail/mailertable.db &lt; /etc/mail/mailertable
+.                             uucp-dom:<replaceable>your.uucp.relay</replaceable></programlisting>
+
+    <para>A more complex example might look like this:</para>
+
+    <programlisting>#
+# makemap hash /etc/mail/mailertable.db &lt; /etc/mail/mailertable
+#
+horus.interface-business.de   uucp-dom:horus
+.interface-business.de        uucp-dom:if-bus
+interface-business.de         uucp-dom:if-bus
+.heep.sax.de                  smtp8:%1
+horus.UUCP                    uucp-dom:horus
+if-bus.UUCP                   uucp-dom:if-bus
+.                             uucp-dom:</programlisting>
+
+
+    <para>The first three lines handle special cases where
+      domain-addressed mail should not be sent out to the default
+      route, but instead to some UUCP neighbor in order to
+      <quote>shortcut</quote> the delivery path. The next line handles
+      mail to the local Ethernet domain that can be delivered using
+      SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP
+      pseudo-domain notation, to allow for a
+      <literal><replaceable>uucp-neighbor
+      </replaceable>!<replaceable>recipient</replaceable></literal>
+      override of the default rules. The last line is always a single
+      dot, matching everything else, with UUCP delivery to a UUCP
+      neighbor that serves as your universal mail gateway to the
+      world. All of the node names behind the
+      <literal>uucp-dom:</literal> keyword must be valid UUCP
+      neighbors, as you can verify using the command
+      <literal>uuname</literal>.</para>
+
+    <para>As a reminder that this file needs to be converted into a
+      DBM database file before use.  The command line to accomplish
+      this is best placed as a comment at the top of the <filename>mailertable</filename> file.
+      You always have to execute this command each time you change
+      your <filename>mailertable</filename> file.</para>
+
+    <para>Final hint: if you are uncertain whether some particular
+      mail routing would work, remember the <option>-bt</option>
+      option to <application>sendmail</application>. It starts <application>sendmail</application> in <emphasis>address test
+      mode</emphasis>; simply enter <literal>3,0</literal>, followed
+      by the address you wish to test for the mail routing.  The last
+      line tells you the used internal mail agent, the destination
+      host this agent will be called with, and the (possibly
+      translated) address. Leave this mode by typing <keycombo
+      action="simul"><keycap>Ctrl</keycap><keycap>D</keycap></keycombo>.</para>
+
+    <screen>&prompt.user; <userinput>sendmail -bt</userinput>
+ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
+Enter &lt;ruleset&gt; &lt;address&gt;
+<prompt>&gt;</prompt> <userinput>3,0 foo@example.com</userinput>
+canonify           input: foo @ example . com
+...
+parse            returns: $# uucp-dom $@ <replaceable>your.uucp.relay</replaceable> $: foo &lt; @ example . com . &gt;
+<prompt>&gt;</prompt> <userinput>^D</userinput></screen>
+  </sect1>
+
+  <sect1 id="outgoing-only">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Bill</firstname>
+          <surname>Moran</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Setting Up to Send Only</title>
+
+    <para>There are many instances where you may only want to send
+      mail through a relay.  Some examples are:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Your computer is a desktop machine, but you want
+	  to use programs such as &man.send-pr.1;.  To do so, you should use
+	  your ISP's mail relay.</para>
+      </listitem>
+
+      <listitem>
+	<para>The computer is a server that does not handle mail
+	  locally, but needs to pass off all mail to a relay for
+	  processing.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Just about any <acronym>MTA</acronym> is capable of filling
+      this particular niche.  Unfortunately, it can be very difficult
+      to properly configure a full-featured <acronym>MTA</acronym>
+      just to handle offloading mail.  Programs such as
+      <application>sendmail</application> and
+      <application>postfix</application> are largely overkill for
+      this use.</para>
+
+    <para>Additionally, if you are using a typical Internet access
+      service, your agreement may forbid you from running a
+      <quote>mail server</quote>.</para>
+
+    <para>The easiest way to fulfill those needs is to install the
+      <filename role="package">mail/ssmtp</filename> port.  Execute
+      the following commands as <username>root</username>:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/ports/mail/ssmtp</userinput>
+&prompt.root; <userinput>make install replace clean</userinput></screen>
+
+    <para>Once installed,
+      <filename role="package">mail/ssmtp</filename> can be configured
+      with a four-line file located at
+      <filename>/usr/local/etc/ssmtp/ssmtp.conf</filename>:</para>
+
+    <programlisting>root=yourrealemail@example.com
+mailhub=mail.example.com
+rewriteDomain=example.com
+hostname=_HOSTNAME_</programlisting>
+
+    <para>Make sure you use your real email address for
+      <username>root</username>.  Enter your ISP's outgoing mail relay
+      in place of <hostid role="fqdn">mail.example.com</hostid> (some ISPs call
+      this the <quote>outgoing mail server</quote> or
+      <quote>SMTP server</quote>).</para>
+
+    <para>Make sure you disable <application>sendmail</application>,
+      including the outgoing mail service. See
+      <xref linkend="mail-disable-sendmail"> for details.</para>
+
+    <para><filename role="package">mail/ssmtp</filename> has some
+      other options available.  See the example configuration file in
+      <filename>/usr/local/etc/ssmtp</filename> or the manual page of
+      <application>ssmtp</application> for some examples and more
+      information.</para>
+
+    <para>Setting up <application>ssmtp</application> in this manner
+      will allow any software on your computer that needs to send
+      mail to function properly, while not violating your ISP's usage
+      policy or allowing your computer to be hijacked for spamming.</para>
+  </sect1>
+
+  <sect1 id="SMTP-dialup">
+    <title>Using Mail with a Dialup Connection</title>
+
+    <para>If you have a static IP address, you should not need to
+      adjust anything from the defaults.  Set your host name to your
+      assigned Internet name and <application>sendmail</application> will do the rest.</para>
+
+    <para>If you have a dynamically assigned IP number and use a
+      dialup PPP connection to the Internet, you will probably have a
+      mailbox on your ISPs mail server. Let's assume your ISP's domain
+      is <hostid role="domainname">example.net</hostid>, and that your
+      user name is <username>user</username>, you have called your
+      machine <hostid role="fqdn">bsd.home</hostid>, and your ISP has
+      told you that you may use <hostid
+      role="fqdn">relay.example.net</hostid> as a mail relay.</para>
+
+    <para>In order to retrieve mail from your mailbox, you must
+      install a retrieval agent.  The
+      <application>fetchmail</application> utility is a good choice as
+      it supports many different protocols.  This program is available
+      as a package or from the Ports Collection (<filename
+      role="package">mail/fetchmail</filename>).  Usually, your <acronym>ISP</acronym> will
+      provide <acronym>POP</acronym>. If you are using user <acronym>PPP</acronym>, you can
+      automatically fetch your mail when an Internet connection is
+      established with the following entry in
+      <filename>/etc/ppp/ppp.linkup</filename>:</para>
+
+    <programlisting>MYADDR:
+!bg su user -c fetchmail</programlisting>
+
+    <para>If you are using <application>sendmail</application> (as
+      shown below) to deliver mail to non-local accounts, you probably
+      want to have <application>sendmail</application> process your
+      mailqueue as soon as your Internet connection is established.
+      To do this, put this command after the
+      <command>fetchmail</command> command in
+      <filename>/etc/ppp/ppp.linkup</filename>:</para>
+
+    <programlisting>  !bg su user -c "sendmail -q"</programlisting>
+
+    <para>Assume that you have an account for
+      <username>user</username> on <hostid
+      role="fqdn">bsd.home</hostid>. In the home directory of
+      <username>user</username> on <hostid
+      role="fqdn">bsd.home</hostid>, create a
+      <filename>.fetchmailrc</filename> file:</para>
+
+    <programlisting>poll example.net protocol pop3 fetchall pass MySecret</programlisting>
+
+    <para>This file should not be readable by anyone except
+      <username>user</username> as it contains the password
+      <literal>MySecret</literal>.</para>
+
+    <para>In order to send mail with the correct
+      <literal>from:</literal> header, you must tell
+      <application>sendmail</application> to use
+      <email>user@example.net</email> rather than
+      <email role="nolink">user@bsd.home</email>. You may also wish to tell
+      <application>sendmail</application> to send all mail via <hostid
+      role="fqdn">relay.example.net</hostid>, allowing quicker mail
+      transmission.</para>
+
+    <para>The following <filename>.mc</filename> file should
+      suffice:</para>
+
+    <programlisting>VERSIONID(`bsd.home.mc version 1.0')
+OSTYPE(bsd4.4)dnl
+FEATURE(nouucp)dnl
+MAILER(local)dnl
+MAILER(smtp)dnl
+Cwlocalhost
+Cwbsd.home
+MASQUERADE_AS(`example.net')dnl
+FEATURE(allmasquerade)dnl
+FEATURE(masquerade_envelope)dnl
+FEATURE(nocanonify)dnl
+FEATURE(nodns)dnl
+define(`SMART_HOST', `relay.example.net')
+Dmbsd.home
+define(`confDOMAIN_NAME',`bsd.home')dnl
+define(`confDELIVERY_MODE',`deferred')dnl</programlisting>
+
+    <para>Refer to the previous section for details of how to turn
+      this <filename>.mc</filename> file into a
+      <filename>sendmail.cf</filename> file.  Also, do not forget to
+      restart <application>sendmail</application> after updating
+      <filename>sendmail.cf</filename>.</para>
+  </sect1>
+
+  <sect1 id="SMTP-Auth">
+    <sect1info>
+    <authorgroup>
+      <author>
+        <firstname>James</firstname>
+        <surname>Gorham</surname>
+        <contrib>Written by </contrib>
+      </author>
+    </authorgroup>
+    </sect1info>
+
+    <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 have used
+	  for your <filename>.mc</filename> file).  Then use the
+	  command <command>make install restart</command>, which will
+	  copy the file to <filename>sendmail.cf</filename>, and will
+	  properly restart <application>sendmail</application>.
+	  For more information about this process, you should refer
+	  to <filename>/etc/mail/Makefile</filename>.</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 <option>LogLevel</option> of
+      <application>sendmail</application> to 13 and watch
+      <filename>/var/log/maillog</filename> for any errors.</para>
+
+    <para>You may wish to add the following line to <filename>/etc/rc.conf</filename>
+      so this service will be available after every system boot:</para>
+
+    <programlisting>cyrus_pwcheck_enable="YES"</programlisting>
+
+    <para>This will ensure the initialization of <acronym>SMTP_AUTH</acronym> upon system
+      boot.</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>
+
+  <sect1 id="mail-agents">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Silver</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Mail User Agents</title>
+
+    <indexterm>
+      <primary>Mail User Agents</primary>
+    </indexterm>
+
+    <para>A Mail User Agent (<acronym>MUA</acronym>) is an application
+      that is used to send and receive email.  Furthermore, as email
+      <quote>evolves</quote> and becomes more complex,
+      <acronym>MUA</acronym>'s are becoming increasingly powerful in the
+      way they interact with email; this gives users increased
+      functionality and flexibility.  &os; contains support for
+      numerous mail user agents, all of which can be easily installed
+      using the <link linkend="ports">FreeBSD Ports Collection</link>.
+      Users may choose between graphical email clients such as
+      <application>evolution</application> or
+      <application>balsa</application>, console based clients such as
+      <application>mutt</application>, <application>pine</application>
+      or <command>mail</command>, or the web interfaces used by some
+      large organizations.</para>
+
+    <sect2 id="mail-command">
+      <title>mail</title>
+
+      <para>&man.mail.1; is the default Mail User Agent
+	(<acronym>MUA</acronym>) in &os;.  It is a
+	console based <acronym>MUA</acronym> that offers all the basic
+	functionality required to send and receive text-based email,
+	though it is limited in interaction abilities with attachments
+	and can only support local mailboxes.</para>
+
+      <para>Although <command>mail</command> does not natively support
+	interaction with <acronym>POP</acronym> or
+	<acronym>IMAP</acronym> servers, these mailboxes may be
+	downloaded to a local <filename>mbox</filename> file using an
+	application such as <application>fetchmail</application>, which
+	will be discussed later in this chapter (<xref
+	linkend="mail-fetchmail">).</para>
+
+      <para>In order to send and receive email, simply invoke the
+	<command>mail</command> command as per the following
+	example:</para>
+
+      <screen>&prompt.user; <userinput>mail</userinput></screen>
+
+      <para>The contents of the user mailbox in
+	<filename class="directory">/var/mail</filename> are
+	automatically read by the <command>mail</command> utility.
+	Should the mailbox be empty, the utility exits with a
+	message indicating that no mails could be found.  Once the
+	mailbox has been read, the application interface is started, and
+	a list of messages will be displayed.  Messages are automatically
+	numbered, as can be seen in the following example:</para>
+
+      <screen>Mail version 8.1 6/6/93.  Type ? for help.
+"/var/mail/marcs": 3 messages 3 new
+>N  1 root@localhost        Mon Mar  8 14:05  14/510   "test"
+ N  2 root@localhost        Mon Mar  8 14:05  14/509   "user account"
+ N  3 root@localhost        Mon Mar  8 14:05  14/509   "sample"</screen>
+
+      <para>Messages can now be read by using the <keycap>t</keycap>
+	<command>mail</command> command, suffixed by the message number
+	that should be displayed.  In this example, we will read the
+	first email:</para>
+
+      <screen>&amp; <userinput>t 1</userinput>
+Message 1:
+From root@localhost  Mon Mar  8 14:05:52 2004
+X-Original-To: marcs@localhost
+Delivered-To: marcs@localhost
+To: marcs@localhost
+Subject: test
+Date: Mon,  8 Mar 2004 14:05:52 +0200 (SAST)
+From: root@localhost (Charlie Root)
+
+This is a test message, please reply if you receive it.</screen>
+
+      <para>As can be seen in the example above, the <keycap>t</keycap>
+	key will cause the message to be displayed with full headers.
+	To display the list of messages again, the <keycap>h</keycap>
+	key should be used.</para>
+
+      <para>If the email requires a response, you may use
+	<command>mail</command> to reply, by using either the
+	<keycap>R</keycap> or <keycap>r</keycap> <command>mail</command>
+	keys.  The <keycap>R</keycap> key instructs
+	<command>mail</command> to reply only to the sender of the
+	email, while <keycap>r</keycap> replies not only to the sender,
+	but also to other recipients of the message.  You may also
+	suffix these commands with the mail number which you would like
+	make a reply to.  Once this has been done, the response should
+	be entered, and the end of the message should be marked by a
+	single <keycap>.</keycap> on a new line.  An example can be seen
+	below:</para>
+
+      <screen>&amp; <userinput>R 1</userinput>
+To: root@localhost
+Subject: Re: test
+
+<userinput>Thank you, I did get your email.
+.</userinput>
+EOT</screen>
+
+      <para>In order to send new email, the <keycap>m</keycap>
+	key should be used, followed by the
+	recipient email address.  Multiple recipients may also be
+	specified by separating each address with the <keycap>,</keycap>
+	delimiter.  The subject of the message may then be entered,
+	followed by the message contents.  The end of the message should
+	be specified by putting a single <keycap>.</keycap> on a new
+	line.</para>
+
+      <screen>&amp; <userinput>mail root@localhost</userinput>
+Subject: <userinput>I mastered mail
+
+Now I can send and receive email using mail ... :)
+.</userinput>
+EOT</screen>
+
+      <para>While inside the <command>mail</command> utility, the
+	<keycap>?</keycap> command may be used to display help at any
+	time, the &man.mail.1; manual page should also be consulted for
+	more help with <command>mail</command>.</para>
+
+      <note>
+        <para>As previously mentioned, the &man.mail.1; command was not
+	  originally designed to handle attachments, and thus deals with
+	  them very poorly.  Newer <acronym>MUA</acronym>s such as
+	  <application>mutt</application> handle attachments in a much
+	  more intelligent way.  But should you still wish to use the
+	  <command>mail</command> command, the <filename
+	  role="package">converters/mpack</filename> port may be of
+	  considerable use.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="mutt-command">
+      <title>mutt</title>
+
+      <para><application>mutt</application> is a small yet very
+	 powerful Mail User Agent, with excellent features,
+	 just some of which include:</para>
+
+      <itemizedlist>
+        <listitem>
+	  <para>The ability to thread messages;</para>
+        </listitem>
+
+        <listitem>
+	  <para>PGP support for digital signing and encryption of
+	    email;</para>
+        </listitem>
+
+        <listitem>
+	  <para>MIME Support;</para>
+        </listitem>
+
+        <listitem>
+	  <para>Maildir Support;</para>
+        </listitem>
+
+        <listitem>
+	  <para>Highly customizable.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>All of these features help to make
+	<application>mutt</application> one of the most advanced mail
+	user agents available.  See <ulink
+	url="http://www.mutt.org"></ulink> for more
+	information on <application>mutt</application>.</para>
+
+      <para>The stable version of <application>mutt</application> may be
+	installed using the <filename
+	role="package">mail/mutt</filename> port, while the current
+	development version may be installed via the <filename
+	role="package">mail/mutt-devel</filename> port.  After the port
+	has been installed, <application>mutt</application> can be
+	started by issuing the following command:</para>
+
+      <screen>&prompt.user; <userinput>mutt</userinput></screen>
+
+      <para><application>mutt</application> will automatically read the
+	contents of the user mailbox in <filename
+	class="directory">/var/mail</filename> and display the contents
+	if applicable.  If no mails are found in the user mailbox, then
+	<application>mutt</application> will wait for commands from the
+	user.  The example below shows <application>mutt</application>
+	displaying a list of messages:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/mutt1" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>In order to read an email, simply select it using the cursor
+	keys, and press the <keycap>Enter</keycap> key.  An example of
+	<application>mutt</application> displaying email can be seen
+	below:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/mutt2" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>As with the &man.mail.1; command,
+	<application>mutt</application> allows users to reply only to
+	the sender of the message as well as to all recipients.  To
+	reply only to the sender of the email, use the
+	<keycap>r</keycap> keyboard shortcut.  To send a group reply,
+	which will be sent to the original sender as well as all the
+	message recipients, use the <keycap>g</keycap> shortcut.</para>
+
+      <note>
+	<para><application>mutt</application> makes use of the
+	  &man.vi.1; command as an editor for creating and replying to
+	  emails.  This may be customized by the user by creating or
+	  editing their own <filename>.muttrc</filename> file in their home directory and setting the
+	  <literal>editor</literal> variable.</para>
+      </note>
+
+      <para>In order to compose a new mail message, press
+	<keycap>m</keycap>.  After a valid subject has been given,
+	<application>mutt</application> will start &man.vi.1; and the
+	mail can be written.  Once the contents of the mail are
+	complete, save and quit from <command>vi</command> and
+	<application>mutt</application> will resume, displaying a
+	summary screen of the mail that is to be delivered.  In order to
+	send the mail, press <keycap>y</keycap>.  An example of the
+	summary screen can be seen below:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/mutt3" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para><application>mutt</application> also contains extensive
+	help, which can be accessed from most of the menus by pressing
+	the <keycap>?</keycap> key.  The top line also displays the
+	keyboard shortcuts where appropriate.</para>
+    </sect2>
+
+    <sect2 id="pine-command">
+      <title>pine</title>
+
+      <para><application>pine</application> is aimed at a beginner
+	user, but also includes some advanced features.</para>
+
+      <warning>
+	<para>The <application>pine</application> software has had several remote vulnerabilities
+	  discovered in the past, which allowed remote attackers to
+	  execute arbitrary code as users on the local system, by the
+	  action of sending a specially-prepared email. All such
+	  <emphasis>known</emphasis> problems have been fixed, but the
+	  <application>pine</application> code is written in a very insecure style and the &os;
+	  Security Officer believes there are likely to be other
+	  undiscovered vulnerabilities. You install
+	  <application>pine</application> at your own risk.</para>
+      </warning>
+
+      <para>The current version of <application>pine</application> may
+	be installed using the <filename
+	role="package">mail/pine4</filename> port.  Once the port has
+	installed, <application>pine</application> can be started by
+	issuing the following command:</para>
+
+      <screen>&prompt.user; <userinput>pine</userinput></screen>
+
+      <para>The first time that <application>pine</application> is run
+	it displays a greeting page with a brief introduction, as well
+	as a request from the <application>pine</application>
+	development team to send an anonymous email message allowing
+	them to judge how many users are using their client.  To send
+	this anonymous message, press <keycap>Enter</keycap>, or
+	alternatively press <keycap>E</keycap> to exit the greeting
+	without sending an anonymous message.  An example of the
+	greeting page can be seen below:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/pine1" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>Users are then presented with the main menu, which can be
+	easily navigated using the cursor keys.  This main menu provides
+	shortcuts for the composing new mails, browsing of mail directories,
+	and even the administration of address book entries.  Below the
+	main menu, relevant keyboard shortcuts to perform functions
+	specific to the task at hand are shown.</para>
+
+      <para>The default directory opened by <application>pine</application>
+	is the <filename class="directory">inbox</filename>.  To view the message index, press
+	<keycap>I</keycap>, or select the <guimenuitem>MESSAGE INDEX</guimenuitem>
+	option as seen below:</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/pine2" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>The message index shows messages in the current directory,
+	and can be navigated by using the cursor keys.  Highlighted
+	messages can be read by pressing the
+	<keycap>Enter</keycap> key.</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/pine3" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>In the screenshot below, a sample message is displayed by
+	<application>pine</application>.  Keyboard shortcuts are
+	displayed as a reference at the bottom of the screen.  An
+	example of one of these shortcuts is the <keycap>r</keycap> key,
+	which tells the <acronym>MUA</acronym> to reply to the current
+	message being displayed.</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/pine4" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>Replying to an email in <application>pine</application> is
+	done using the <application>pico</application> editor, which is
+	installed by default with <application>pine</application>.
+	The <application>pico</application> utility makes it easy to
+	navigate around the message and is slightly more forgiving on
+	novice users than &man.vi.1; or &man.mail.1;.  Once the reply
+	is complete, the message can be sent by pressing
+	<keycombo action="simul"><keycap>Ctrl</keycap><keycap>X</keycap>
+	</keycombo>. The <application>pine</application> application
+	will ask for confirmation.</para>
+
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="mail/pine5" format="PNG">
+	</imageobject>
+      </mediaobject>
+
+      <para>The <application>pine</application> application can be
+	customized using the <guimenuitem>SETUP</guimenuitem> option from the main
+	menu.  Consult <ulink url="http://www.washington.edu/pine/"></ulink>
+	for more information.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="mail-fetchmail">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Silver</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Using fetchmail</title>
+
+    <indexterm>
+      <primary>fetchmail</primary>
+    </indexterm>
+
+    <para><application>fetchmail</application> is a full-featured
+      <acronym>IMAP</acronym> and <acronym>POP</acronym> client which
+      allows users to automatically download mail from remote
+      <acronym>IMAP</acronym> and <acronym>POP</acronym> servers and
+      save it into local mailboxes; there it can be accessed more easily.
+      <application>fetchmail</application> can be installed using the
+      <filename role="package">mail/fetchmail</filename> port, and
+      offers various features, some of which include:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Support of <acronym>POP3</acronym>,
+	  <acronym>APOP</acronym>, <acronym>KPOP</acronym>,
+	  <acronym>IMAP</acronym>, <acronym>ETRN</acronym> and
+	  <acronym>ODMR</acronym> protocols.</para>
+      </listitem>
+
+      <listitem>
+	<para>Ability to forward mail using <acronym>SMTP</acronym>, which
+	  allows filtering, forwarding, and aliasing to function
+	  normally.</para>
+      </listitem>
+
+      <listitem>
+	<para>May be run in daemon mode to check periodically for new
+	  messages.</para>
+      </listitem>
+
+      <listitem>
+	<para>Can retrieve multiple mailboxes and forward them based
+	  on configuration, to different local users.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>While it is outside the scope of this document to explain
+      all of <application>fetchmail</application>'s features, some
+      basic features will be explained.  The
+      <application>fetchmail</application> utility requires a
+      configuration file known as <filename>.fetchmailrc</filename>,
+      in order to run correctly.  This file includes server information
+      as well as login credentials.  Due to the sensitive nature of the
+      contents of this file, it is advisable to make it readable only by the owner,
+      with the following command:</para>
+
+    <screen>&prompt.user; <userinput>chmod 600 .fetchmailrc</userinput></screen>
+
+    <para>The following <filename>.fetchmailrc</filename> serves as an
+      example for downloading a single user mailbox using
+      <acronym>POP</acronym>.  It tells
+      <application>fetchmail</application> to connect to <hostid
+      role="fqdn">example.com</hostid> using a username of
+      <username>joesoap</username> and a password of
+      <literal>XXX</literal>.  This example assumes that the user
+      <username>joesoap</username> is also a user on the local
+      system.</para>
+
+    <programlisting>poll example.com protocol pop3 username "joesoap" password "XXX"</programlisting>
+
+    <para>The next example connects to multiple <acronym>POP</acronym>
+      and <acronym>IMAP</acronym> servers and redirects to different
+      local usernames where applicable:</para>
+
+    <programlisting>poll example.com proto pop3:
+user "joesoap", with password "XXX", is "jsoap" here;
+user "andrea", with password "XXXX";
+poll example2.net proto imap:
+user "john", with password "XXXXX", is "myth" here;</programlisting>
+
+    <para>The <application>fetchmail</application> utility can be run in daemon
+      mode by running it with the <option>-d</option> flag, followed
+      by the interval (in seconds) that
+      <application>fetchmail</application> should poll servers listed
+      in the <filename>.fetchmailrc</filename> file.  The following
+      example would cause <application>fetchmail</application> to poll
+      every 600 seconds:</para>
+
+    <screen>&prompt.user; <userinput>fetchmail -d 600</userinput></screen>
+
+    <para>More information on <application>fetchmail</application> can
+      be found at <ulink
+      url="http://fetchmail.berlios.de/"></ulink>.</para>
+  </sect1>
+
+  <sect1 id="mail-procmail">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Silver</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Using procmail</title>
+
+    <indexterm>
+      <primary>procmail</primary>
+    </indexterm>
+
+    <para>The <application>procmail</application> utility is an
+      incredibly powerful application used to filter incoming mail.
+      It allows users to define <quote>rules</quote> which can be
+      matched to incoming mails to perform specific functions or to
+      reroute mail to alternative mailboxes and/or email addresses.
+      <application>procmail</application> can be installed using the
+      <filename role="package">mail/procmail</filename> port.  Once
+      installed, it can be directly integrated into most
+      <acronym>MTA</acronym>s; consult your <acronym>MTA</acronym>
+      documentation for more information.  Alternatively,
+      <application>procmail</application> can be integrated by adding
+      the following line to a <filename>.forward</filename> in the home
+      directory of the user utilizing
+      <application>procmail</application> features:</para>
+
+    <programlisting>"|exec /usr/local/bin/procmail || exit 75"</programlisting>
+
+    <para>The following section will display some basic
+      <application>procmail</application> rules, as well as brief
+      descriptions on what they do.  These rules, and others must be
+      inserted into a <filename>.procmailrc</filename> file, which
+      must reside in the user's home directory.</para>
+
+    <para>The majority of these rules can also be found in the
+      &man.procmailex.5; manual page.</para>
+
+    <para>Forward all mail from <email>user@example.com</email> to an
+      external address of <email role="nolink">goodmail@example2.com</email>:</para>
+
+    <programlisting>:0
+* ^From.*user@example.com
+! goodmail@example2.com</programlisting>
+
+    <para>Forward all mails shorter than 1000 bytes to an external
+      address of <email role="nolink">goodmail@example2.com</email>:</para>
+
+    <programlisting>:0
+* &lt; 1000
+! goodmail@example2.com</programlisting>
+
+    <para>Send all mail sent to <email>alternate@example.com</email>
+      into a mailbox called <filename>alternate</filename>:</para>
+
+    <programlisting>:0
+* ^TOalternate@example.com
+alternate</programlisting>
+
+    <para>Send all mail with a subject of <quote>Spam</quote> to
+      <filename>/dev/null</filename>:</para>
+
+    <programlisting>:0
+^Subject:.*Spam
+/dev/null</programlisting>
+
+    <para>A useful recipe that parses incoming <hostid role="domainname">&os;.org</hostid> mailing lists
+      and places each list in its own mailbox:</para>
+
+    <programlisting>:0
+* ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG
+{
+	LISTNAME=${MATCH}
+	:0
+	* LISTNAME??^\/[^@]+
+	FreeBSD-${MATCH}
+}</programlisting>
+  </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/pl_PL.ISO8859-2/books/handbook/mirrors/Makefile b/pl_PL.ISO8859-2/books/handbook/mirrors/Makefile
new file mode 100644
index 0000000000..ad5c0e2abe
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/mirrors/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	mirrors/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/mirrors/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/mirrors/chapter.sgml
new file mode 100644
index 0000000000..51a8e71664
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/mirrors/chapter.sgml
@@ -0,0 +1,3207 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<appendix id="mirrors">
+  <title>Obtaining FreeBSD</title>
+
+  <sect1 id="mirrors-cdrom">
+    <title>CDROM and DVD Publishers</title>
+
+    <sect2>
+      <title>Retail Boxed Products</title>
+
+      <para>FreeBSD is available as a boxed product (FreeBSD CDs,
+	additional software, and printed documentation) from several
+	retailers:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <address>
+	    <otheraddr>CompUSA</otheraddr>
+	    WWW: <otheraddr><ulink url="http://www.compusa.com/"></ulink></otheraddr>
+	  </address>
+	</listitem>
+
+	<listitem>
+	  <address>
+	    <otheraddr>Frys Electronics</otheraddr>
+	    WWW: <otheraddr><ulink url="http://www.frys.com/"></ulink></otheraddr>
+	  </address>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>CD and DVD Sets</title>
+
+      <para>FreeBSD CD and DVD sets are available from many online
+	retailers:</para>
+
+    <itemizedlist>
+      <listitem>
+        <address>
+	  <otheraddr>BSD Mall by Daemon News</otheraddr>
+	  <street>PO Box 161</street>
+	  <city>Nauvoo</city>, <state>IL</state> <postcode>62354</postcode>
+	  <country>USA</country>
+	  Phone: <phone>+1 866 273-6255</phone>
+	  Fax: <fax>+1 217 453-9956</fax>
+	  Email: <email>sales@bsdmall.com</email>
+	  WWW: <otheraddr><ulink url="http://www.bsdmall.com/freebsd1.html"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+        <address>
+	  <otheraddr>BSD-Systems</otheraddr>
+	  Email: <email>info@bsd-systems.co.uk</email>
+	  WWW: <otheraddr><ulink url="http://www.bsd-systems.co.uk"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+        <address>
+	  <otheraddr>FreeBSD Mall, Inc.</otheraddr>
+	  <street>3623 Sanford Street</street>
+	  <city>Concord</city>, <state>CA</state>  <postcode>94520-1405</postcode>
+	  <country>USA</country>
+	  Phone: <phone>+1 925 674-0783</phone>
+	  Fax: <fax>+1 925 674-0821</fax>
+	  Email: <email>info@freebsdmall.com</email>
+	  WWW: <otheraddr><ulink url="http://www.freebsdmall.com/"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>Hinner EDV</otheraddr>
+	  <street>St. Augustinus-Str. 10</street>
+	  <postcode>D-81825</postcode> <city>M&uuml;nchen</city>
+	  <country>Germany</country>
+	  Phone: <phone>(089) 428 419</phone>
+	  WWW: <otheraddr><ulink url="http://www.hinner.de/linux/freebsd.html"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>Ikarios</otheraddr>
+	  <street>22-24 rue Voltaire</street>
+	  <postcode>92000</postcode> <city>Nanterre</city>
+	  <country>France</country>
+	  WWW: <otheraddr><ulink url="http://ikarios.com/form/#freebsd"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>JMC Software</otheraddr>
+	  <country>Ireland</country>
+	  Phone: <phone>353 1 6291282</phone>
+	  WWW: <otheraddr><ulink url="http://www.thelinuxmall.com"></ulink></otheraddr>
+	</address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>Linux CD Mall</otheraddr>
+	  <street>Private Bag MBE N348</street>
+	  <city>Auckland 1030</city>
+	  <country>New Zealand</country>
+	  Phone: <phone>+64 21 866529</phone>
+	  WWW: <otheraddr><ulink url="http://www.linuxcdmall.co.nz/"></ulink></otheraddr>
+	</address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>The Linux Emporium</otheraddr>
+	  <street>Hilliard House, Lester Way</street>
+	  <city>Wallingford</city>
+	  <postcode>OX10 9TA</postcode>
+	  <country>United Kingdom</country>
+	  Phone: <phone>+44 1491 837010</phone>
+	  Fax: <fax>+44 1491 837016</fax>
+	  WWW: <otheraddr><ulink url="http://www.linuxemporium.co.uk/products/freebsd/"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>Linux+ DVD Magazine</otheraddr>
+	  <street>Lewartowskiego 6</street>
+	  <city>Warsaw</city>
+	  <postcode>00-190</postcode>
+	  <country>Poland</country>
+	  Phone: <phone>+48 22 860 18 18</phone>
+	  Email: <email>editors@lpmagazine.org</email>
+	  WWW: <otheraddr><ulink url="http://www.lpmagazine.org/"></ulink></otheraddr>
+	</address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>Linux System Labs Australia</otheraddr>
+	  <street>21 Ray Drive</street>
+	  <city>Balwyn North</city>
+	  <postcode>VIC - 3104</postcode>
+	  <country>Australia</country>
+	  Phone: <phone>+61 3 9857 5918</phone>
+	  Fax: <fax>+61 3 9857 8974</fax>
+	  WWW: <otheraddr><ulink url="http://www.lsl.com.au"></ulink></otheraddr>
+        </address>
+      </listitem>
+
+      <listitem>
+	<address>
+	  <otheraddr>LinuxCenter.Ru</otheraddr>
+	  <street>Galernaya Street, 55</street>
+	  <city>Saint-Petersburg</city>
+	  <postcode>190000</postcode>
+	  <country>Russia</country>
+	  Phone: <phone>+7-812-3125208</phone>
+	  Email: <email>info@linuxcenter.ru</email>
+	  WWW: <otheraddr><ulink url="http://linuxcenter.ru/freebsd"></ulink></otheraddr>
+	</address>
+      </listitem>
+
+    </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Distributors</title>
+
+      <para>If you are a reseller and want to carry FreeBSD CDROM products,
+	please contact a distributor:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <address>
+	    <otheraddr>Cylogistics</otheraddr>
+	    <street>809B Cuesta Dr., #2149</street>
+	    <city>Mountain View</city>, <state>CA</state> <postcode>94040</postcode>
+	    <country>USA</country>
+	    Phone: <phone>+1 650 694-4949</phone>
+	    Fax: <fax>+1 650 694-4953</fax>
+	    Email: <email>sales@cylogistics.com</email>
+	    WWW: <otheraddr><ulink url="http://www.cylogistics.com/"></ulink></otheraddr>
+	  </address>
+	</listitem>
+
+        <listitem>
+	  <address>
+	    <otheraddr>Ingram Micro</otheraddr>
+	    <street>1600 E. St. Andrew Place</street>
+	    <city>Santa Ana</city>, <state>CA</state>  <postcode>92705-4926</postcode>
+	    <country>USA</country>
+	    Phone: <phone>1 (800) 456-8000</phone>
+	    WWW: <otheraddr><ulink url="http://www.ingrammicro.com/"></ulink></otheraddr>
+          </address>
+        </listitem>
+
+	<listitem>
+	  <address>
+	    <otheraddr>Kudzu, LLC</otheraddr>
+	    <street>7375 Washington Ave. S.</street>
+	    <city>Edina</city>, <state>MN</state> <postcode>55439</postcode>
+	    <country>USA</country>
+	    Phone: <phone>+1 952 947-0822</phone>
+	    Fax: <fax>+1 952 947-0876</fax>
+	    Email: <email>sales@kudzuenterprises.com</email>
+	  </address>
+	</listitem>
+
+	<listitem>
+	  <address>
+	    <otheraddr>LinuxCenter.Ru</otheraddr>
+	    <street>Galernaya Street, 55</street>
+	    <city>Saint-Petersburg</city>
+	    <postcode>190000</postcode>
+	    <country>Russia</country>
+	    Phone: <phone>+7-812-3125208</phone>
+	    Email: <email>info@linuxcenter.ru</email>
+	    WWW: <otheraddr><ulink url="http://linuxcenter.ru/freebsd"></ulink></otheraddr>
+	  </address>
+	</listitem>
+
+	<listitem>
+	  <address>
+	    <otheraddr>Navarre Corp</otheraddr>
+	    <street>7400 49th Ave South</street>
+	    <city>New Hope</city>, <state>MN</state> <postcode>55428</postcode>
+	    <country>USA</country>
+	    Phone: <phone>+1 763 535-8333</phone>
+	    Fax: <fax>+1 763 535-0341</fax>
+	    WWW: <otheraddr><ulink url="http://www.navarre.com/"></ulink></otheraddr>
+	  </address>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mirrors-ftp">
+    <title>FTP Sites</title>
+
+    <para>The official sources for FreeBSD are available via anonymous FTP
+      from a worldwide set of mirror sites.  The site
+      <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"></ulink> is well
+      connected and allows a large number of connections to it, but
+      you are probably better off finding a <quote>closer</quote>
+      mirror site (especially if you decide to set up some sort of
+      mirror site).</para>
+
+    <para>The <ulink
+	url="http://mirrorlist.FreeBSD.org/">FreeBSD mirror
+	sites database</ulink> is more accurate than the mirror listing in the
+      Handbook, as it gets its information from the DNS rather than relying on
+      static lists of hosts.</para>
+
+    <para>Additionally, FreeBSD is available via anonymous FTP from the
+      following mirror sites.  If you choose to obtain FreeBSD via anonymous
+      FTP, please try to use a site near you.  The mirror sites listed as
+      <quote>Primary Mirror Sites</quote> typically have the entire FreeBSD archive (all
+      the currently available versions for each of the architectures) but
+      you will probably have faster download times from a site that is
+      in your country or region.  The regional sites carry the most recent
+      versions for the most popular architecture(s) but might not carry
+      the entire FreeBSD archive.  All sites provide access via anonymous
+      FTP but some sites also provide access via other methods.  The access
+      methods available for each site are provided in parentheses
+      after the hostname.</para>
+
+    &chap.mirrors.ftp.inc;
+  </sect1>
+
+    <sect1 id="anoncvs">
+      <title>Anonymous CVS</title>
+
+      <sect2>
+	<title><anchor id="anoncvs-intro">Introduction</title>
+
+	<indexterm>
+	  <primary>CVS</primary>
+	  <secondary>anonymous</secondary>
+	</indexterm>
+
+	<para>Anonymous CVS (or, as it is otherwise known,
+	  <emphasis>anoncvs</emphasis>) is a feature provided by the CVS
+	  utilities bundled with FreeBSD for synchronizing with a remote
+	  CVS repository.  Among other things, it allows users of FreeBSD
+	  to perform, with no special privileges, read-only CVS operations
+	  against one of the FreeBSD project's official anoncvs servers.
+	  To use it, one simply sets the <envar>CVSROOT</envar>
+	  environment variable to point at the appropriate anoncvs server,
+	  provides the well-known password <quote>anoncvs</quote> with the
+	  <command>cvs login</command> command, and then uses the
+	  &man.cvs.1; command to access it like any local
+	  repository.</para>
+
+	<note>
+	  <para>The <command>cvs login</command> command, stores the passwords
+	    that are used for authenticating to the CVS server in a file
+	    called <filename>.cvspass</filename> in your
+	    <envar>HOME</envar> directory.  If this file does not exist,
+	    you might get an error when trying to use <command>cvs
+	    login</command> for the first time.  Just make an empty
+	    <filename>.cvspass</filename> file, and retry to login.</para>
+	</note>
+
+	<para>While it can also be said that the <link
+	  linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis>
+	  services both perform essentially the same function, there are
+	  various trade-offs which can influence the user's choice of
+	  synchronization methods.  In a nutshell,
+	  <application>CVSup</application> is much more efficient in its
+	  usage of network resources and is by far the most technically
+	  sophisticated of the two, but at a price.  To use
+	  <application>CVSup</application>, a special client must first be
+	  installed and configured before any bits can be grabbed, and
+	  then only in the fairly large chunks which
+	  <application>CVSup</application> calls
+	  <emphasis>collections</emphasis>.</para>
+
+	<para><application>Anoncvs</application>, by contrast, can be used
+	  to examine anything from an individual file to a specific
+	  program (like <command>ls</command> or <command>grep</command>)
+	  by referencing the CVS module name.  Of course,
+	  <application>anoncvs</application> is also only good for
+	  read-only operations on the CVS repository, so if it is your
+	  intention to support local development in one repository shared
+	  with the FreeBSD project bits then
+	  <application>CVSup</application> is really your only
+	  option.</para>
+      </sect2>
+
+      <sect2>
+	<title><anchor id="anoncvs-usage">Using Anonymous CVS</title>
+
+	<para>Configuring &man.cvs.1; to use an Anonymous CVS repository
+	  is a simple matter of setting the <envar>CVSROOT</envar>
+	  environment variable to point to one of the FreeBSD project's
+	  <emphasis>anoncvs</emphasis> servers.  At the time of this
+	  writing, the following servers are available:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para><emphasis>Austria</emphasis>:
+	      :pserver:anoncvs@anoncvs.at.FreeBSD.org:/home/ncvs
+	      (Use <command>cvs login</command> and enter any
+	      password when prompted.)</para>
+	  </listitem>
+	  <listitem>
+	    <para><emphasis>France</emphasis>:
+	      :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs
+	      (pserver (password <quote>anoncvs</quote>), ssh (no password))
+	    </para>
+	  </listitem>
+	  <listitem>
+	    <para><emphasis>Germany</emphasis>:
+	      :pserver:anoncvs@anoncvs.de.FreeBSD.org:/home/ncvs
+	      (Use <command>cvs login</command> and enter the password
+	      <quote>anoncvs</quote> when prompted.)</para>
+	  </listitem>
+	  <listitem>
+	    <para><emphasis>Germany</emphasis>:
+	      :pserver:anoncvs@anoncvs2.de.FreeBSD.org:/home/ncvs
+	      (rsh, pserver, ssh, ssh/2022)
+	      </para>
+	  </listitem>
+	  <listitem>
+	    <para><emphasis>Japan</emphasis>:
+	      :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs
+	      (Use <command>cvs login</command> and enter the password
+	      <quote>anoncvs</quote> when prompted.)</para>
+	  </listitem>
+	  <listitem>
+	    <para><emphasis>USA</emphasis>:
+	      freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs
+	      (ssh only - no password)</para>
+
+	    <programlisting>SSH HostKey: 1024 a1:e7:46:de:fb:56:ef:05:bc:73:aa:91:09:da:f7:f4 root@sanmateo.ecn.purdue.edu
+SSH2 HostKey: 1024 52:02:38:1a:2f:a8:71:d3:f5:83:93:8d:aa:00:6f:65 ssh_host_dsa_key.pub</programlisting>
+
+	  </listitem>
+	  <listitem>
+	    <para><emphasis>USA</emphasis>:
+	      anoncvs@anoncvs1.FreeBSD.org:/home/ncvs (ssh only - no
+	      password)</para>
+
+	    <programlisting>SSH HostKey: 1024 8b:c4:6f:9a:7e:65:8a:eb:50:50:29:7c:a1:47:03:bc root@ender.liquidneon.com
+SSH2 HostKey: 2048 4d:59:19:7b:ea:9b:76:0b:ca:ee:da:26:e2:3a:83:b8 ssh_host_dsa_key.pub</programlisting>
+
+	  </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;):</title>
+
+	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.jp.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>
+	  </screen>
+	</example>
+
+	<example>
+	  <title>Using SSH to check out the <filename>src/</filename>
+	    tree:</title>
+	  <screen>&prompt.user; <userinput>cvs -d freebsdanoncvs@anoncvs.FreeBSD.org:/home/ncvs co src</userinput>
+The authenticity of host 'anoncvs.freebsd.org (128.46.156.46)' can't be established.
+DSA key fingerprint is 52:02:38:1a:2f:a8:71:d3:f5:83:93:8d:aa:00:6f:65.
+Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput>
+Warning: Permanently added 'anoncvs.freebsd.org' (DSA) to the list of known hosts.</screen>
+	</example>
+
+	<example>
+	  <title>Checking Out the Version of &man.ls.1; in the 6-STABLE
+	    Branch:</title>
+
+	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.jp.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_6 ls</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.jp.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_5_3_0_RELEASE -rRELENG_5_4_0_RELEASE ls</userinput>
+	  </screen>
+	</example>
+
+	<example>
+	  <title>Finding Out What Other Module Names Can Be Used:</title>
+
+	  <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.jp.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>
+	  </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://ximbiot.com/cvs/wiki/">CVS Home</ulink>,
+	      the CVS development and support community.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para><ulink
+		url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSweb</ulink> is
+	      the FreeBSD Project web interface for CVS.</para>
+	  </listitem>
+	</itemizedlist>
+      </sect2>
+    </sect1>
+    
+    
+  <sect1 id="ctm">
+    <title>Using CTM</title>
+
+      <indexterm>
+	<primary>CTM</primary>
+      </indexterm>
+
+      <para><application>CTM</application> is a method for keeping a
+	remote directory tree in sync with a central one.  It has been
+	developed for usage with FreeBSD's source trees, though other
+	people may find it useful for other purposes as time goes by.
+	Little, if any, documentation currently exists at this time on the
+	process of creating deltas, so contact the &a.ctm-users.name; mailing list for more
+	information and if you wish to use <application>CTM</application>
+	for other things.</para>
+
+      <sect2>
+	<title>Why Should I Use <application>CTM</application>?</title>
+
+	<para><application>CTM</application> will give you a local copy of
+	  the FreeBSD source trees.  There are a number of
+	  <quote>flavors</quote> of the tree available.  Whether you wish
+	  to track the entire CVS tree or just one of the branches,
+	  <application>CTM</application> can provide you the information.
+	  If you are an active developer on FreeBSD, but have lousy or
+	  non-existent TCP/IP connectivity, or simply wish to have the
+	  changes automatically sent to you,
+	  <application>CTM</application> was made for you.  You will need
+	  to obtain up to three deltas per day for the most  active
+	  branches.  However, you should consider having them sent by
+	  automatic email.  The sizes of the updates are always kept as
+	  small as possible.  This is typically less than 5K, with an
+	  occasional (one in ten) being 10-50K and every now and then a
+	  large 100K+ or more coming around.</para>
+
+	<para>You will also need to make yourself aware of the various
+	  caveats related to working directly from the development sources
+	  rather than a pre-packaged release.  This is particularly true
+	  if you choose the <quote>current</quote> sources.  It is
+	  recommended that you read <link linkend="current">Staying
+	  current with FreeBSD</link>.</para>
+      </sect2>
+
+      <sect2>
+	<title>What Do I Need to Use
+	  <application>CTM</application>?</title>
+
+	<para>You will need two things: The <application>CTM</application>
+	  program, and the initial deltas to feed it (to get up to
+	  <quote>current</quote> levels).</para>
+	    
+	<para>The <application>CTM</application> program has been part of
+	  FreeBSD ever since version 2.0 was released, and lives in
+	  <filename>/usr/src/usr.sbin/ctm</filename> if you have a copy
+	  of the source available.</para>
+
+	<para>The <quote>deltas</quote> you feed
+	  <application>CTM</application> can be had two ways, FTP or
+	  email.  If you have general FTP access to the Internet then the
+	  following FTP sites support access to
+	  <application>CTM</application>:</para>
+
+	<para><ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para>
+
+	<para>or see section <link
+	  linkend="mirrors-ctm">mirrors</link>.</para>
+
+	<para>FTP the relevant directory and fetch the
+	  <filename>README</filename> file, starting from there.</para>
+
+	<para>If you wish to get your deltas via email:</para>
+
+	<para>Subscribe to one of the
+	  <application>CTM</application> distribution lists.
+	  &a.ctm-cvs-cur.name; supports the entire CVS tree.
+	  &a.ctm-src-cur.name; supports the head of the development
+	  branch.  &a.ctm-src-4.name; supports the 4.X release
+	  branch, etc..  (If you do not know how to subscribe yourself
+	  to a list, click on the list name above or go to
+	  &a.mailman.lists.link; and click on the list that you
+	  wish to subscribe to.  The list page should contain all of
+	  the necessary subscription instructions.)</para>
+
+	<para>When you begin receiving your <application>CTM</application>
+	  updates in the mail, you may use the
+	  <command>ctm_rmail</command> program to unpack and apply them.
+	  You can actually use the <command>ctm_rmail</command> program
+	  directly from a entry in <filename>/etc/aliases</filename> if
+	  you want to have the process run in a fully automated fashion.
+	  Check the <command>ctm_rmail</command> manual page for more
+	  details.</para>
+
+	<note>
+	  <para>No matter what method you use to get the
+	    <application>CTM</application> deltas, you should subscribe to
+	    the &a.ctm-announce.name; mailing list.  In
+	    the future, this will be the only place where announcements
+	    concerning the operations of the
+	    <application>CTM</application> system will be posted.  Click
+	    on the list name above and follow the instructions
+	    to subscribe to the
+	    list.</para>
+	</note>
+      </sect2>
+
+      <sect2>
+	<title>Using <application>CTM</application> for the First
+	  Time</title>
+
+	<para>Before you can start using <application>CTM</application>
+	  deltas, you will need to get to a starting point for the deltas
+	  produced subsequently to it.</para>
+
+	<para>First you should determine what you already have.  Everyone
+	  can start from an <quote>empty</quote> directory.  You must use
+	  an initial <quote>Empty</quote> delta to start off your
+	  <application>CTM</application> supported tree.  At some point it
+	  is intended that one of these <quote>started</quote> deltas be
+	  distributed on the CD for your convenience, however, this does
+	  not currently happen.</para>
+
+	<para>Since the trees are many tens of megabytes, you should
+	  prefer to start from something already at hand.  If you have a
+	  -RELEASE CD, you can copy or extract an initial source from it.
+	  This will save a significant transfer of data.</para>
+
+	<para>You can recognize these <quote>starter</quote> deltas by the
+	  <literal>X</literal> appended to the number
+	  (<filename>src-cur.3210XEmpty.gz</filename> for instance).  The
+	  designation following the <literal>X</literal> corresponds to
+	  the origin of your initial <quote>seed</quote>.
+	  <filename>Empty</filename> is an empty directory.  As a rule a
+	  base transition from <literal>Empty</literal> is produced
+	  every 100 deltas.  By the way, they are large! 70 to 80
+	  Megabytes of <command>gzip</command>'d data is common for the
+	  <filename>XEmpty</filename> deltas.</para>
+
+	<para>Once you have picked a base delta to start from, you will also
+	  need all deltas with higher numbers following it.</para>
+      </sect2>
+
+      <sect2>
+	<title>Using <application>CTM</application> in Your Daily
+	  Life</title>
+
+	<para>To apply the deltas, simply say:</para>
+
+	<screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput>
+&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen>
+
+	<para><application>CTM</application> understands deltas which have
+	  been put through <command>gzip</command>, so you do not need to
+	  <command>gunzip</command> them first, this saves disk space.</para>
+
+	<para>Unless it feels very secure about the entire process,
+	  <application>CTM</application> will not touch your tree.  To
+	  verify a delta you can also use the <option>-c</option> flag and
+	  <application>CTM</application> will not actually touch your
+	  tree; it will merely verify the integrity of the delta and see
+	  if it would apply cleanly to your current tree.</para>
+
+	<para>There are other options to <application>CTM</application>
+	  as well, see the manual pages or look in the sources for more
+	  information.</para>
+
+	<para>That is really all there is to it.  Every time you get a new
+	  delta, just run it through <application>CTM</application> to
+	  keep your sources up to date.</para>
+
+	<para>Do not remove the deltas if they are hard to download again.
+	  You just might want to keep them around in case something bad
+	  happens.  Even if you only have floppy disks, consider using
+	  <command>fdwrite</command> to make a copy.</para>
+      </sect2>
+
+      <sect2>
+	<title>Keeping Your Local Changes</title>
+
+	<para>As a developer one would like to experiment with and change
+	  files in the source tree.  <application>CTM</application>
+	  supports local modifications in a limited way: before checking
+	  for the presence of a file <filename>foo</filename>, it first
+	  looks for <filename>foo.ctm</filename>.  If this file exists,
+	  <application>CTM</application> will operate on it instead of
+	  <filename>foo</filename>.</para>
+
+	<para>This behavior gives us a simple way to maintain local
+	  changes:  simply copy the files you plan to modify to the
+	  corresponding file names with a <filename>.ctm</filename>
+	  suffix.  Then you can freely hack  the code, while <application>CTM</application> keeps the
+	  <filename>.ctm</filename> file up-to-date.</para>
+      </sect2>
+
+      <sect2>
+	<title>Other Interesting <application>CTM</application> Options</title>
+
+	<sect3>
+	  <title>Finding Out Exactly What Would Be Touched by an
+	    Update</title>
+
+	  <para>You can determine the list of changes that
+	    <application>CTM</application> will make on your source
+	    repository using the <option>-l</option> option to
+	    <application>CTM</application>.</para>
+
+	  <para>This is useful if you would like to keep logs of the
+	    changes, pre- or post- process the modified files in any
+	    manner, or just are feeling a tad paranoid.</para>
+	</sect3>
+
+	<sect3>
+	  <title>Making Backups Before Updating</title>
+
+	  <para>Sometimes you may want to backup all the files that would
+	    be changed by a <application>CTM</application> update.</para>
+
+	  <para>Specifying the <option>-B backup-file</option> option
+	    causes <application>CTM</application> to backup all files that
+	    would be touched by a given <application>CTM</application>
+	    delta to <filename>backup-file</filename>.</para>
+	</sect3>
+
+	<sect3>
+	  <title>Restricting the Files Touched by an Update</title>
+
+	  <para>Sometimes you would be interested in restricting the scope
+	    of a given <application>CTM</application> update, or may be
+	    interested in extracting just a few files from a sequence of
+	    deltas.</para>
+
+	  <para>You can control the list of files that
+	    <application>CTM</application> would operate on by specifying
+	    filtering regular expressions using the <option>-e</option>
+	    and <option>-x</option> options.</para>
+
+	  <para>For example, to extract an up-to-date copy of
+	    <filename>lib/libc/Makefile</filename> from your collection of
+	    saved <application>CTM</application> deltas, run the commands:</para>
+
+	  <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput>
+&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen>
+
+	  <para>For every file specified in a
+	    <application>CTM</application> delta, the <option>-e</option>
+	    and <option>-x</option> options are applied in the order given
+	    on the command line.  The file is processed by
+	    <application>CTM</application> only if it is marked as
+	    eligible after all the <option>-e</option> and
+	    <option>-x</option> options are applied to it.</para>
+	</sect3>
+      </sect2>
+
+      <sect2>
+	<title>Future Plans for <application>CTM</application></title>
+
+	<para>Tons of them:</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>Use some kind of authentication into the <application>CTM</application> system, so
+	      as to allow detection of spoofed <application>CTM</application> updates.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Clean up the options to <application>CTM</application>,
+	      they became confusing and counter intuitive.</para>
+	  </listitem>
+	</itemizedlist>
+      </sect2>
+
+      <sect2>
+	<title>Miscellaneous Stuff</title>
+
+	<para>There is a sequence of deltas for the
+	  <literal>ports</literal> collection too, but interest has not
+	  been all that high yet.</para>
+      </sect2>
+
+    <sect2 id="mirrors-ctm">
+      <title>CTM Mirrors</title>
+      
+    <para><link linkend="ctm">CTM</link>/FreeBSD is available via anonymous
+      FTP from the following mirror sites.  If you choose to obtain <application>CTM</application> via
+      anonymous FTP, please try to use a site near you.</para>
+
+    <para>In case of problems, please contact the &a.ctm-users.name;
+      mailing list.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>California, Bay Area, official source</term>
+
+	<listitem>
+	  <itemizedlist>
+	    <listitem>
+	      <para><ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
+	    </listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>South Africa, backup server for old deltas</term>
+
+	<listitem>
+	  <itemizedlist>
+	    <listitem>
+	      <para><ulink url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para>
+	    </listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Taiwan/R.O.C.</term>
+
+	<listitem>
+	  <itemizedlist>
+	    <listitem>
+	      <para><ulink url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
+	    </listitem>
+
+	    <listitem>
+	      <para><ulink url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para>
+	    </listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>If you did not find a mirror near to you or the mirror is
+      incomplete, try to use a search engine such as
+      <ulink url="http://www.alltheweb.com/">alltheweb</ulink>.</para>
+  </sect2></sect1>
+
+  <sect1 id="cvsup">
+    <title>Using CVSup</title>
+    
+    <sect2 id="cvsup-intro">
+      <title>Introduction</title>
+      
+      <para><application>CVSup</application> is a software package for
+	distributing and updating source trees from a master CVS
+	repository on a remote server host.  The FreeBSD sources are
+	maintained in a CVS repository on a central development machine
+	in California.  With <application>CVSup</application>, FreeBSD
+	users can easily keep their own source trees up to date.</para>
+      
+      <para><application>CVSup</application> uses the so-called
+	<emphasis>pull</emphasis> model of updating.  Under the pull
+	model, each client asks the server for updates, if and when they
+	are wanted.  The server waits passively for update requests from
+	its clients.  Thus all updates are instigated by the client.
+	The server never sends unsolicited updates.  Users must either
+	run the <application>CVSup</application> client manually to get
+	an update, or they must set up a <command>cron</command> job to
+	run it automatically on a regular basis.</para>
+      
+      <para>The term <application>CVSup</application>, capitalized just
+	so, refers to the entire software package.  Its main components
+	are the client <command>cvsup</command> which runs on each
+	user's machine, and the server <command>cvsupd</command> which
+	runs at each of the FreeBSD mirror sites.</para>
+
+      <para>As you read the FreeBSD documentation and mailing lists, you
+	may see references to <application>sup</application>.
+	<application>Sup</application> was the predecessor of
+	<application>CVSup</application>, and it served a similar
+	purpose.  <application>CVSup</application> is used much in the
+	same way as sup and, in fact, uses configuration files which are
+	backward-compatible with <command>sup</command>'s.
+	<application>Sup</application> is no longer used in the FreeBSD
+	project, because <application>CVSup</application> is both faster
+	and more flexible.</para>
+    </sect2>
+
+    <sect2 id="cvsup-install">
+      <title>Installation</title>
+      
+      <para>The easiest way to install <application>CVSup</application>
+	is to use the precompiled <filename role="package">net/cvsup</filename> package
+	from the FreeBSD <link linkend="ports">packages collection</link>.
+	If you prefer to build <application>CVSup</application> from
+	source, you can use the <filename role="package">net/cvsup</filename>
+	port instead.  But be forewarned: the
+	<filename role="package">net/cvsup</filename> port depends on the Modula-3
+	system, which takes a substantial amount of time and
+	disk space to download and build.</para>
+
+	<note>
+	  <para>If you are going to be using
+	  <application>CVSup</application> on a machine which will not have
+	  <application>&xfree86;</application> or <application>&xorg;</application> installed, such as a server, be
+	  sure to use the port which does not include the
+	  <application>CVSup</application> <acronym>GUI</acronym>,
+	  <filename role="package">net/cvsup-without-gui</filename>.</para>
+	</note>
+    </sect2>
+
+    <sect2 id="cvsup-config">
+      <title>CVSup Configuration</title>
+      
+      <para><application>CVSup</application>'s operation is controlled
+	by a configuration file called the <filename>supfile</filename>.
+	There are some sample <filename>supfiles</filename> in the
+	directory <ulink type="html"
+	  url="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></ulink>.</para>
+      
+      <para>The information in a <filename>supfile</filename> answers
+	the following questions for <application>CVSup</application>:</para>
+      
+      <itemizedlist>
+	<listitem>
+	  <para><link linkend="cvsup-config-files">Which files do you
+	      want to receive?</link></para>
+	</listitem>
+	
+	<listitem>
+	  <para><link linkend="cvsup-config-vers">Which versions of them
+	      do you want?</link></para>
+	</listitem>
+	
+	<listitem>
+	  <para><link linkend="cvsup-config-where">Where do you want to
+	      get them from?</link></para>
+	</listitem>
+	
+	<listitem>
+	  <para><link linkend="cvsup-config-dest">Where do you want to
+	      put them on your own machine?</link></para>
+	</listitem>
+	
+	<listitem>
+	  <para><link linkend="cvsup-config-status">Where do you want to
+	      put your status files?</link></para>
+	</listitem>
+      </itemizedlist>
+
+      <para>In the following sections, we will construct a typical
+	<filename>supfile</filename> by answering each of these
+	questions in turn.  First, we describe the overall structure of
+	a <filename>supfile</filename>.</para>
+
+      <para>A <filename>supfile</filename> is a text file.  Comments
+	begin with <literal>#</literal> and extend to the end of the
+	line.  Lines that are blank and lines that contain only
+	comments are ignored.</para>
+      
+      <para>Each remaining line describes a set of files that the user
+	wishes to receive.  The line begins with the name of a
+	<quote>collection</quote>, a logical grouping of files defined by
+	the server. The name of the collection tells the server which
+	files you want.  After the collection name come zero or more
+	fields, separated by white space.  These fields answer the
+	questions listed above.  There are two types of fields: flag
+	fields and value fields.  A flag field consists of a keyword
+	standing alone, e.g., <literal>delete</literal> or
+	<literal>compress</literal>.  A value field also begins with a
+	keyword, but the keyword is followed without intervening white
+	space by <literal>=</literal> and a second word.  For example,
+	<literal>release=cvs</literal> is a value field.</para>
+      
+      <para>A <filename>supfile</filename> typically specifies more than
+	one collection to receive.  One way to structure a
+	<filename>supfile</filename> is to specify all of the relevant
+	fields explicitly for each collection.  However, that tends to
+	make the <filename>supfile</filename> lines quite long, and it
+	is inconvenient because most fields are the same for all of the
+	collections in a <filename>supfile</filename>.
+	<application>CVSup</application> provides a defaulting mechanism
+	to avoid these problems.  Lines beginning with the special
+	pseudo-collection name <literal>*default</literal> can be used
+	to set flags and values which will be used as defaults for the
+	subsequent collections in the <filename>supfile</filename>.  A
+	default value can be overridden for an individual collection, by
+	specifying a different value with the collection itself.
+	Defaults can also be changed or augmented in mid-supfile by
+	additional <literal>*default</literal> lines.</para>
+
+      <para>With this background, we will now proceed to construct a
+	<filename>supfile</filename> for receiving and updating the main
+	source tree of <link
+	  linkend="current">FreeBSD-CURRENT</link>.</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><anchor id="cvsup-config-files">Which files do you want
+	    to receive?</para>
+	  
+	  <para>The files available via <application>CVSup</application>
+	    are organized into named groups called
+	    <quote>collections</quote>.  The collections that are
+	    available are described in the <link
+	      linkend="cvsup-collec">following section</link>.  In this
+	    example, we
+	    wish to receive the entire main source tree for the FreeBSD
+	    system.  There is a single large collection
+	    <literal>src-all</literal> which will give us all of that.
+	    As a first step toward constructing our
+	    <filename>supfile</filename>, we
+	    simply list the collections, one per line (in this case,
+	    only one line):</para>
+
+	  <programlisting>src-all</programlisting>
+	</listitem>
+
+	<listitem>
+	  <para><anchor id="cvsup-config-vers">Which version(s) of them
+	    do you want?</para>
+
+	  <para>With <application>CVSup</application>, you can receive
+	    virtually any version of the sources that ever existed.
+	    That is possible because the
+	    <application>cvsupd</application> server works directly from
+	    the CVS repository, which contains all of the versions.  You
+	    specify which one of them you want using the
+	    <literal>tag=</literal> and <option>date=</option> value
+	    fields.</para>
+	  
+	  <warning>
+	    <para>Be very careful to specify any <literal>tag=</literal>
+	      fields correctly.  Some tags are valid only for certain
+	      collections of files.  If you specify an incorrect or
+	      misspelled tag, <application>CVSup</application>
+	      will delete files which you probably
+	      do not want deleted.  In particular, use <emphasis>only
+	      </emphasis> <literal>tag=.</literal> for the
+	      <literal>ports-*</literal> collections.</para>
+	  </warning>
+
+	  <para>The <literal>tag=</literal> field names a symbolic tag
+	    in the repository.  There are two kinds of tags, revision
+	    tags and branch tags.  A revision tag refers to a specific
+	    revision.  Its meaning stays the same from day to day.  A
+	    branch tag, on the other hand, refers to the latest revision
+	    on a given line of development, at any given time.  Because
+	    a branch tag does not refer to a specific revision, it may
+	    mean something different tomorrow than it means
+	    today.</para>
+	  
+	  <para><xref linkend="cvs-tags"> contains branch tags that
+	    users might be interested in.  When specifying a tag in
+	    <application>CVSup</application>'s configuration file, it
+	    must be preceded with <literal>tag=</literal>
+	    (<literal>RELENG_4</literal> will become
+	    <literal>tag=RELENG_4</literal>).
+	    Keep in mind that only the <literal>tag=.</literal> is
+	    relevant for the Ports Collection.</para>
+
+	  <warning>
+	    <para>Be very careful to type the tag name exactly as shown.
+	      <application>CVSup</application> cannot distinguish
+	      between valid and invalid tags.  If you misspell the tag,
+	      <application>CVSup</application> will behave as though you
+	      had specified a valid tag which happens to refer to no
+	      files at all.  It will delete your existing sources in
+	      that case.</para>
+	  </warning>
+
+	  <para>When you specify a branch tag, you normally receive the
+	    latest versions of the files on that line of development.
+	    If you wish to receive some past version, you can do so by
+	    specifying a date with the <option>date=</option> value
+	    field. The &man.cvsup.1; manual page explains how to do
+	    that.</para>
+
+	  <para>For our example, we wish to receive FreeBSD-CURRENT.  We
+	    add this line at the beginning of our
+	    <filename>supfile</filename>:</para>
+	  
+	  <programlisting>*default tag=.</programlisting>
+
+	  <para>There is an important special case that comes into play
+	    if you specify neither a <literal>tag=</literal> field nor a
+	    <literal>date=</literal> field.  In that case, you receive
+	    the actual RCS files directly from the server's CVS
+	    repository, rather than receiving a particular version.
+	    Developers generally prefer this mode of operation.  By
+	    maintaining a copy of the repository itself on their
+	    systems, they gain the ability to browse the revision
+	    histories and examine past versions of files.  This gain is
+	    achieved at a large cost in terms of disk space,
+	    however.</para>
+	</listitem>
+
+	<listitem>
+	  <para><anchor id="cvsup-config-where">Where do you want to get
+	    them from?</para>
+	  
+	  <para>We use the <literal>host=</literal> field to tell
+	    <command>cvsup</command> where to obtain its updates.  Any
+	    of the <link linkend="cvsup-mirrors">CVSup mirror
+	      sites</link> will do, though you should try to select one
+	    that is close to you in cyberspace.  In this example we will
+	    use a fictional FreeBSD distribution site,
+	    <hostid role="fqdn">cvsup99.FreeBSD.org</hostid>:</para>
+
+	  <programlisting>*default host=cvsup99.FreeBSD.org</programlisting>
+	  
+	  <para>You will need to change the host to one that actually
+	    exists before running <application>CVSup</application>.
+	    On any particular run of
+	    <command>cvsup</command>, you can override the host  setting
+	    on the command line, with <option>-h
+	      <replaceable>hostname</replaceable></option>.</para>
+	</listitem>
+	
+	<listitem>
+	  <para><anchor id="cvsup-config-dest">Where do you want to put
+	    them on your own machine?</para>
+	  
+	  <para>The <literal>prefix=</literal> field tells
+	    <command>cvsup</command> where to put the files it receives.
+	    In this example, we will put the source files directly into
+	    our main source tree, <filename>/usr/src</filename>.  The
+	    <filename>src</filename> directory is already implicit in
+	    the collections we have chosen to receive, so this is the
+	    correct specification:</para>
+	  
+	  <programlisting>*default prefix=/usr</programlisting>
+	</listitem>
+
+	<listitem>
+	  <para><anchor id="cvsup-config-status">Where should
+	    <command>cvsup</command> maintain its status files?</para>
+
+	  <para>The <application>CVSup</application> client maintains
+	    certain status files in what
+	    is called the <quote>base</quote> directory.  These files
+	    help <application>CVSup</application> to work more
+	    efficiently, by keeping track of which updates you have
+	    already received.  We will use the standard base directory,
+	    <filename>/var/db</filename>:</para>
+
+	  <programlisting>*default base=/var/db</programlisting>
+
+	  <para>If your base directory does not already exist, now would
+	    be a good time to create it.  The <command>cvsup</command>
+	    client will refuse to run if the base directory does not
+	    exist.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Miscellaneous <filename>supfile</filename>
+	    settings:</para>
+	  
+	  <para>There is one more line of boiler plate that normally
+	    needs to be present in the
+	    <filename>supfile</filename>:</para>
+
+	  <programlisting>*default release=cvs delete use-rel-suffix compress</programlisting>
+
+	  <para><literal>release=cvs</literal> indicates that the server
+	    should get its information out of the main FreeBSD CVS
+	    repository.  This is virtually always the case, but there
+	    are other possibilities which are beyond the scope of this
+	    discussion.</para>
+	  
+	  <para><literal>delete</literal> gives
+	    <application>CVSup</application> permission to delete files.
+	    You should always specify this, so that
+	    <application>CVSup</application> can keep your source tree
+	    fully up-to-date.  <application>CVSup</application> is
+	    careful to delete only those files for which it is
+	    responsible.  Any extra files you happen to have will be
+	    left strictly alone.</para>
+	  
+	  <para><literal>use-rel-suffix</literal> is ... arcane.  If you
+	    really want to know about it, see the &man.cvsup.1; manual
+	    page.  Otherwise, just specify it and do not worry about
+	    it.</para>
+
+	  <para><literal>compress</literal> enables the use of
+	    gzip-style compression on the communication channel.  If
+	    your network link is T1 speed or faster, you probably should
+	    not use compression.  Otherwise, it helps
+	    substantially.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Putting it all together:</para>
+
+	  <para>Here is the entire <filename>supfile</filename> for our
+	    example:</para>
+
+	  <programlisting>*default tag=.
+*default host=cvsup99.FreeBSD.org
+*default prefix=/usr
+*default base=/var/db
+*default release=cvs delete use-rel-suffix compress
+
+src-all</programlisting>
+	</listitem>
+      </itemizedlist>
+      <sect3 id="cvsup-refuse-file">
+       <title>The <filename>refuse</filename> File</title>
+
+       <para>As mentioned above, <application>CVSup</application> uses
+       a <emphasis>pull method</emphasis>. Basically, this means that
+       you connect to the <application>CVSup</application> server, and
+       it says, <quote>Here is what you can download from
+       me...</quote>, and your client responds <quote>OK, I will take
+       this, this, this, and this.</quote> In the default
+       configuration, the <application>CVSup</application> client will
+       take every file associated with the collection and tag you
+       chose in the configuration file. However, this is not always
+       what you want, especially if you are synching the <filename>doc</filename>, <filename>ports</filename>, or
+       <filename>www</filename> trees &mdash; most people cannot read four or five
+       languages, and therefore they do not need to download the
+       language-specific files. If you are
+       <application>CVSup</application>ing the Ports Collection, you
+       can get around this by specifying each collection individually
+       (e.g., <emphasis>ports-astrology</emphasis>,
+       <emphasis>ports-biology</emphasis>, etc instead of simply
+       saying <emphasis>ports-all</emphasis>). However, since the <filename>doc</filename>
+       and <filename>www</filename> trees do not have language-specific collections, you
+       must use one of <application>CVSup</application>'s many nifty
+       features: the <filename>refuse</filename> file.</para>
+
+       <para>The <filename>refuse</filename> file essentially tells
+       <application>CVSup</application> that it should not take every
+       single file from a collection; in other words, it tells the
+       client to <emphasis>refuse</emphasis> certain files from the
+       server. The <filename>refuse</filename> file can be found (or, if you do not yet
+       have one, should be placed) in
+       <filename><replaceable>base</replaceable>/sup/</filename>.
+       <replaceable>base</replaceable> is defined in your <filename>supfile</filename>;
+       our defined <replaceable>base</replaceable> is
+       <filename>/var/db</filename>, 
+       which means that by default the <filename>refuse</filename> file is
+       <filename>/var/db/sup/refuse</filename>.</para>
+
+       <para>The <filename>refuse</filename> file has a very simple format; it simply
+       contains the names of files or directories that you do not wish
+       to download.  For example, if you cannot speak any languages other
+       than English and some German, and you do not feel the need to read
+       the German translation of documentation, you can put the following in your
+       <filename>refuse</filename> file:</para>
+
+       <screen>doc/bn_*
+doc/da_*
+doc/de_*
+doc/el_*
+doc/es_*
+doc/fr_*
+doc/it_*
+doc/ja_*
+doc/nl_*
+doc/no_*
+doc/pl_*
+doc/pt_*
+doc/ru_*
+doc/sr_*
+doc/tr_*
+doc/zh_*</screen>
+
+       <para>and so forth for the other languages (you can find the
+       full list by browsing the <ulink
+       url="http://www.FreeBSD.org/cgi/cvsweb.cgi/">FreeBSD
+       CVS repository</ulink>).</para>
+
+       <para>With this very useful feature, those users who are on
+       slow links or pay by the minute for their Internet connection
+       will be able to save valuable time as they will no longer need
+       to download files that they will never use. For more
+       information on <filename>refuse</filename> files and other neat
+       features of <application>CVSup</application>, please view its
+       manual page.</para> 
+      </sect3>
+    </sect2>
+    
+    <sect2>
+      <title>Running <application>CVSup</application></title>
+      
+      <para>You are now ready to try an update.  The command line for
+	doing this is quite simple:</para>
+
+      <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen>
+
+      <para>where <filename><replaceable>supfile</replaceable></filename>
+	is of course the name of the <filename>supfile</filename> you have just created. 
+	Assuming you are running under X11, <command>cvsup</command>
+	will display a GUI window with some buttons to do the usual
+	things.  Press the <guibutton>go</guibutton> button, and watch it
+	run.</para>
+      
+      <para>Since you are updating your actual
+	<filename>/usr/src</filename> tree in this example, you will
+	need to run the program as <username>root</username> so that
+	<command>cvsup</command> has the permissions it needs to update
+	your files.  Having just created your configuration file, and
+	having never used this program before, that might
+	understandably make you nervous. There is an easy way to do a
+	trial run without touching your precious files.  Just create an
+	empty directory somewhere convenient, and name it as an extra
+	argument on the command line:</para>
+
+      <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput>
+&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen>
+      
+      <para>The directory you specify will be used as the destination
+	directory for all file updates.
+	<application>CVSup</application> will examine your usual files
+	in <filename>/usr/src</filename>, but it will not modify or
+	delete any of them.  Any file updates will instead land in
+	<filename>/var/tmp/dest/usr/src</filename>.
+	<application>CVSup</application> will also leave its base
+	directory status files untouched when run this way.  The new
+	versions of those files will be written into the specified
+	directory.  As long as you have read access to
+	<filename>/usr/src</filename>, you do not even need to be
+	<username>root</username> to perform this kind of trial run.</para>
+      
+      <para>If you are not running X11 or if you just do not like GUIs,
+	you should add a couple of options to the command line when you
+	run <command>cvsup</command>:</para>
+      
+      <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>supfile</replaceable></userinput></screen>
+	    
+      <para>The <option>-g</option> tells
+	<application>CVSup</application> not to use its GUI.  This is
+	automatic if you are not running X11, but otherwise you have to
+	specify it.</para>
+      
+      <para>The <option>-L 2</option> tells 
+	<application>CVSup</application> to print out the
+	details of all the file updates it is doing.  There are three
+	levels of verbosity, from <option>-L 0</option> to
+	<option>-L 2</option>.  The default is 0, which means total
+	silence except for error messages.</para>
+      
+      <para>There are plenty of other options available.  For a brief
+	list of them, type <command>cvsup -H</command>.  For more
+	detailed descriptions, see the manual page.</para>
+
+      <para>Once you are satisfied with the way updates are working, you
+	can arrange for regular runs of <application>CVSup</application>
+	using &man.cron.8;.
+	Obviously, you should not let <application>CVSup</application>
+	use its GUI when running it from &man.cron.8;.</para>
+    </sect2>
+
+    <sect2 id="cvsup-collec">
+      <title><application>CVSup</application> File Collections</title>
+	    
+      <para>The file collections available via
+	<application>CVSup</application> are organized hierarchically.
+	There are a few large collections, and they are divided into
+	smaller sub-collections.  Receiving a large collection is
+	equivalent to receiving each of its sub-collections.  The
+	hierarchical relationships among collections are reflected by
+	the use of indentation in the list below.</para>
+      
+      <para>The most commonly used collections are
+	<literal>src-all</literal>, and
+	<literal>ports-all</literal>.  The other collections are used
+	only by small groups of people for specialized purposes, and
+	some mirror sites may not carry all of them.</para>
+      
+      <variablelist>
+	<varlistentry>
+	  <term><literal>cvs-all release=cvs</literal></term>
+	  
+	  <listitem>
+	    <para>The main FreeBSD CVS repository, including the
+	      cryptography code.</para>
+	    
+	    <variablelist>
+	      <varlistentry>
+		<term><literal>distrib release=cvs</literal></term>
+		
+		<listitem>
+		  <para>Files related to the distribution and mirroring
+		    of FreeBSD.</para>
+		</listitem>
+	      </varlistentry>
+	      
+	      <varlistentry>
+		<term><literal>doc-all release=cvs</literal></term>
+		<listitem>
+		  <para>Sources for the FreeBSD Handbook and other
+		    documentation.  This does not include files for
+		    the FreeBSD web site.</para>
+		</listitem>
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><literal>ports-all release=cvs</literal></term>
+
+		<listitem>
+		  <para>The FreeBSD Ports Collection.</para>
+
+		  <important id="cvsup-collec-pbase-warn">
+		    <para>If you do not want to update the whole of
+		      <literal>ports-all</literal> (the whole ports tree),
+		      but use one of the subcollections listed below,
+		      make sure that you <emphasis>always</emphasis> update
+		      the <literal>ports-base</literal> subcollection!
+		      Whenever something changes in the ports build
+		      infrastructure represented by
+		      <literal>ports-base</literal>, it is virtually certain
+		      that those changes will be used by <quote>real</quote>
+		      ports real soon.  Thus, if you only update the
+		      <quote>real</quote> ports and they use some of the new
+		      features, there is a very high chance that their build
+		      will fail with some mysterious error message.  The
+		      <emphasis>very first</emphasis> thing to do in this
+		      case is to make sure that your
+		      <literal>ports-base</literal> subcollection is up to
+		      date.</para>
+		  </important>
+
+		  <important id="cvsup-collec-index-warn">
+		    <para>If you are going to be building your own local
+		      copy of <filename>ports/INDEX</filename>, you
+		      <emphasis>must</emphasis> accept 
+		      <literal>ports-all</literal> (the whole ports tree).
+		      Building <filename>ports/INDEX</filename> with
+		      a partial tree is not supported.  See the
+		      <ulink url="&url.books.faq;/applications.html#MAKE-INDEX">
+		      FAQ</ulink>.</para>
+		  </important>
+
+		  <variablelist>
+		    <varlistentry>
+		      <term><literal>ports-accessibility
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Software to help disabled users.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-arabic
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Arabic language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-archivers
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Archiving tools.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-astro
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Astronomical ports.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-audio
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Sound support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-base
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>The Ports Collection build infrastructure -
+			  various files located in the
+			  <filename>Mk/</filename> and
+			  <filename>Tools/</filename> subdirectories of
+			  <filename>/usr/ports</filename>.</para>
+
+			<note>
+			  <para>Please see the <link
+			    linkend="cvsup-collec-pbase-warn">important
+			    warning above</link>: you should
+			    <emphasis>always</emphasis> update this
+			    subcollection, whenever you update any part of
+			    the FreeBSD Ports Collection!</para>
+			</note>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-benchmarks
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Benchmarks.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-biology
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Biology.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-cad
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Computer aided design tools.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-chinese
+			  release=cvs</literal></term>
+			
+		      <listitem>
+			<para>Chinese language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-comms
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Communication software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-converters
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>character code converters.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-databases
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Databases.</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>ports-deskutils
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Things that used to be on the desktop
+			  before computers were invented.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-devel
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Development utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-dns
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>DNS related software.</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>ports-editors
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Editors.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-emulators
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Emulators for other operating
+			  systems.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-finance
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Monetary, financial and related applications.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-ftp
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>FTP client and server utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-games
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Games.</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>ports-german
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>German language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-graphics
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Graphics utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-hebrew
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Hebrew language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-hungarian
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Hungarian language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-irc
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Internet Relay Chat utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-japanese
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Japanese language support.</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>ports-java
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>&java; utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-korean
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Korean language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-lang
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Programming languages.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-mail
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Mail software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-math
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Numerical computation software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-mbone
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>MBone applications.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-misc
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Miscellaneous utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-multimedia
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Multimedia software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-net
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Networking software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-net-im
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Instant messaging software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-net-mgmt
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Network management software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-net-p2p
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Peer to peer networking.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-news
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>USENET news software.</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>ports-palm
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Software support for <trademark class="trade">Palm</trademark>
+			  series.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-polish
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Polish language support.</para>
+		      </listitem>
+		    </varlistentry>
+	
+		    <varlistentry>
+		      <term><literal>ports-portuguese
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Portuguese language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-print
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Printing software.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-russian
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Russian language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-science
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Science.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-security
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Security utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-shells
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Command line shells.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-sysutils
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>System utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-textproc
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>text processing utilities (does not
+			  include desktop publishing).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-ukrainian
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Ukrainian language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-vietnamese
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Vietnamese language support.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-www
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Software related to the World Wide
+			  Web.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Ports to support the X window
+			  system.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-clocks
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>X11 clocks.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-fm
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>X11 file managers.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-fonts
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>X11 fonts and font utilities.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-toolkits
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>X11 toolkits.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-servers
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>X11 servers.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-themes
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>X11 themes.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>ports-x11-wm
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>X11 window managers.</para>
+		      </listitem>
+		    </varlistentry>
+		  </variablelist>
+		</listitem>
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><literal>projects-all release=cvs</literal></term>
+		<listitem>
+		  <para>Sources for the FreeBSD projects repository.</para>
+		</listitem>
+	      </varlistentry>
+
+	      <varlistentry>
+		<term><literal>src-all release=cvs</literal></term>
+		
+		<listitem>
+		  <para>The main FreeBSD sources, including the
+		    cryptography code.</para>
+
+		  <variablelist>
+		    <varlistentry>
+		      <term><literal>src-base
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Miscellaneous files at the top of
+			  <filename>/usr/src</filename>.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-bin
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>User utilities that may be needed in
+			  single-user mode
+			  (<filename>/usr/src/bin</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-contrib
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Utilities and libraries from outside the
+			  FreeBSD project, used relatively unmodified
+			  (<filename>/usr/src/contrib</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-crypto release=cvs</literal></term>
+
+		      <listitem>
+			<para>Cryptography utilities and libraries from
+			  outside the FreeBSD project, used relatively
+			  unmodified
+			  (<filename>/usr/src/crypto</filename>).</para>
+			  </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-eBones release=cvs</literal></term>
+		
+		      <listitem>
+			<para>Kerberos and DES
+			  (<filename>/usr/src/eBones</filename>).  Not
+			  used in current releases of FreeBSD.</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-etc
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>System configuration files
+			  (<filename>/usr/src/etc</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-games
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Games
+			  (<filename>/usr/src/games</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-gnu
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Utilities covered by the GNU Public
+			  License (<filename>/usr/src/gnu</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-include
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Header files
+			  (<filename>/usr/src/include</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-kerberos5
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Kerberos5 security package
+			  (<filename>/usr/src/kerberos5</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-kerberosIV
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>KerberosIV security package
+			  (<filename>/usr/src/kerberosIV</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-lib
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Libraries
+			  (<filename>/usr/src/lib</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-libexec
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>System programs normally executed by other
+			  programs
+			  (<filename>/usr/src/libexec</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>src-release
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>Files required to produce a FreeBSD
+			  release
+			  (<filename>/usr/src/release</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-sbin release=cvs</literal></term>
+
+		      <listitem>
+			<para>System utilities for single-user mode
+			  (<filename>/usr/src/sbin</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+		    
+		    <varlistentry>
+		      <term><literal>src-secure
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Cryptographic libraries and commands
+			  (<filename>/usr/src/secure</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-share
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Files that can be shared across multiple
+			  systems
+			  (<filename>/usr/src/share</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-sys
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>The kernel
+			  (<filename>/usr/src/sys</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-sys-crypto
+			release=cvs</literal></term>
+		
+		      <listitem>
+			<para>Kernel cryptography code
+			  (<filename>/usr/src/sys/crypto</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-tools
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>Various tools for the maintenance of
+			  FreeBSD
+			  (<filename>/usr/src/tools</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-usrbin
+			  release=cvs</literal></term>
+
+		      <listitem>
+			<para>User utilities
+			  (<filename>/usr/src/usr.bin</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+
+		    <varlistentry>
+		      <term><literal>src-usrsbin
+			  release=cvs</literal></term>
+		      
+		      <listitem>
+			<para>System utilities
+			  (<filename>/usr/src/usr.sbin</filename>).</para>
+		      </listitem>
+		    </varlistentry>
+		  </variablelist>
+		</listitem>
+	      </varlistentry>
+	      
+	      <varlistentry>
+		<term><literal>www release=cvs</literal></term>
+		
+		<listitem>
+		  <para>The sources for the FreeBSD WWW site.</para>
+		</listitem>
+	      </varlistentry>
+	    </variablelist>
+	  </listitem>
+	</varlistentry>
+	
+	<varlistentry>
+	  <term><literal>distrib release=self</literal></term>
+
+	  <listitem>
+	    <para>The <application>CVSup</application> server's own 
+	      configuration files.  Used by <application>CVSup</application>
+	      mirror sites.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>gnats release=current</literal></term>
+
+	  <listitem>
+	    <para>The GNATS bug-tracking database.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>mail-archive release=current</literal></term>
+	  
+	  <listitem>
+	    <para>FreeBSD mailing list archive.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>www release=current</literal></term>
+
+	  <listitem>
+	    <para>The pre-processed FreeBSD WWW site files (not the
+	      source files).  Used by WWW mirror sites.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>For More Information</title>
+
+      <para>For the <application>CVSup</application> FAQ and other 
+	information about <application>CVSup</application>, see
+	<ulink url="http://www.polstra.com/projects/freeware/CVSup/">The
+	  CVSup Home Page</ulink>.</para>
+
+      <para>Most FreeBSD-related discussion of
+	<application>CVSup</application> takes place on the
+	&a.hackers;.  New versions of the software are announced there,
+	as well as on the &a.announce;.</para>
+      
+      <para>Questions and bug reports should be addressed to the author
+	of the program at <email>cvsup-bugs@polstra.com</email>.</para>
+    </sect2>
+
+    <sect2 id="cvsup-mirrors">
+    <title>CVSup Sites</title>
+
+    <para><link linkend="cvsup">CVSup</link> servers for FreeBSD are running
+      at the following sites:</para>
+
+    &chap.mirrors.cvsup.inc;
+    </sect2>
+  </sect1>
+  
+  <sect1 id="portsnap">
+    <title>Using Portsnap</title>
+
+    <sect2 id="portsnap-intro">
+      <title>Introduction</title>
+
+      <para><application>Portsnap</application> is a system for securely
+	distributing the &os; ports tree.  Approximately once an hour,
+	a <quote>snapshot</quote> of the ports tree is generated,
+	repackaged, and cryptographically signed.  The resulting files
+	are then distributed via HTTP.</para>
+
+      <para>Like <application>CVSup</application>,
+	<application>Portsnap</application> uses a
+	<emphasis>pull</emphasis> model of updating: The packaged and
+	signed ports trees are placed on a web server which waits
+	passively for clients to request files.  Users must either run
+	&man.portsnap.8; manually to download updates
+	or set up a &man.cron.8; job to download updates
+	automatically on a regular basis.</para>
+
+      <para>For technical reasons, <application>Portsnap</application>
+	does not update the <quote>live</quote> ports tree in
+	<filename>/usr/ports/</filename> directly; instead, it works
+	via a compressed copy of the ports tree stored in
+	<filename>/var/db/portsnap/</filename> by default.  This
+	compressed copy is then used to update the live ports tree.</para>
+
+      <note>
+	<para>If <application>Portsnap</application> is installed from
+	the &os; Ports Collection, then the default location for its
+	compressed snapshot will be <filename>/usr/local/portsnap/</filename>
+	instead of <filename>/var/db/portsnap/</filename>.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="portsnap-install">
+      <title>Installation</title>
+
+      <para>On &os; 6.0 and more recent versions,
+	<application>Portsnap</application> is contained in the &os;
+	base system.  On older versions of &os;, it can be installed
+	using the <filename role="package">sysutils/portsnap</filename>
+	port.</para>
+    </sect2>
+
+    <sect2 id="portsnap-config">
+      <title>Portsnap Configuration</title>
+
+      <para><application>Portsnap</application>'s operation is controlled
+	by the <filename>/etc/portsnap.conf</filename> configuration
+	file.  For most users, the default configuration file will
+	suffice; for more details, consult the &man.portsnap.conf.5;
+	manual page.</para>
+
+      <note>
+	<para>If <application>Portsnap</application> is installed from
+	  the &os; Ports Collection, it will use the configuration file
+	  <filename>/usr/local/etc/portsnap.conf</filename> instead of
+	  <filename>/etc/portsnap.conf</filename>.  This configuration
+	  file is not created when the port is installed, but a sample
+	  configuration file is distributed; to copy it into place, run
+	  the following command:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/local/etc &amp;&amp; cp portsnap.conf.sample portsnap.conf</userinput></screen>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Running <application>Portsnap</application> for the First
+	Time</title>
+
+      <para>The first time &man.portsnap.8; is run,
+	it will need to download a compressed snapshot of the entire
+	ports tree into <filename>/var/db/portsnap/</filename> (or
+	<filename>/usr/local/portsnap/</filename> if
+	<application>Portsnap</application> was installed from the
+	Ports Collection).  For the beginning of 2006 this is approximately a 41&nbsp;MB
+	download.</para>
+
+      <screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
+
+      <para>Once the compressed snapshot has been downloaded, a
+	<quote>live</quote> copy of the ports tree can be extracted into
+	<filename>/usr/ports/</filename>.  This is necessary even if a
+	ports tree has already been created in that directory (e.g., by
+	using <application>CVSup</application>), since it establishes a
+	baseline from which <command>portsnap</command> can
+	determine which parts of the ports tree need to be updated
+	later.</para>
+
+      <screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
+
+      <note>
+	<para>In the default installation
+	  <filename role="directory">/usr/ports</filename> is not
+	  created.  If you run &os;&nbsp;6.0-RELEASE, it should be created before
+	  <command>portsnap</command> is used.  On more recent
+	  versions of &os; or <application>Portsnap</application>,
+	  this operation will be done automatically at first use
+	  of the <command>portsnap</command> command.<para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Updating the Ports Tree</title>
+
+      <para>After an initial compressed snapshot of the ports tree has
+	been downloaded and extracted into <filename>/usr/ports/</filename>,
+	updating the ports tree consists of two steps:
+	<emphasis>fetch</emphasis>ing updates to the compressed
+	snapshot, and using them to <emphasis>update</emphasis> the
+	live ports tree.  These two steps can be specified to
+	<command>portsnap</command> as a single command:</para>
+
+      <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
+
+      <note>
+	<para>Some older versions of <command>portsnap</command>
+	  do not support this syntax; if it fails, try instead the
+	  following:</para>
+
+        <screen>&prompt.root; <userinput>portsnap fetch</userinput>
+&prompt.root; <userinput>portsnap update</userinput></screen>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Running Portsnap from cron</title>
+
+      <para>In order to avoid problems with <quote>flash crowds</quote>
+	accessing the <application>Portsnap</application> servers,
+	<command>portsnap fetch</command> will not run from
+	a &man.cron.8; job.  Instead, a special
+	<command>portsnap cron</command> command exists, which
+	waits for a random duration up to 3600 seconds before fetching
+	updates.</para>
+
+      <para>In addition, it is strongly recommended that
+	<command>portsnap update</command> not be run from a
+	<command>cron</command> job, since it is liable to cause
+	major problems if it happens to run at the same time as a port
+	is being built or installed.  However, it is safe to update
+	the ports' <filename>INDEX</filename> files, and this can be done by passing the
+	<option>-I</option> flag to
+	<command>portsnap</command>.  (Obviously, if
+	<command>portsnap -I update</command> is run from
+	<command>cron</command>, then it will be necessary to run
+	<command>portsnap update</command> without the <option>-I</option>
+	flag at a later time in order to update the rest of the tree.)</para>
+
+      <para>Adding the following line to <filename>/etc/crontab</filename>
+	will cause <command>portsnap</command> to update its
+	compressed snapshot and the <filename>INDEX</filename> files in
+	<filename>/usr/ports/</filename>, and will send an email if any
+	installed ports are out of date:</para>
+
+      <programlisting>0 3 * * * root portsnap -I cron update &amp;&amp; pkg_version -vIL=</programlisting>
+
+      <note>
+	<para>If the system clock is not set to the local time zone,
+	  please replace <literal>3</literal> with a random
+	  value between 0 and 23, in order to spread the load on the
+	  <application>Portsnap</application> servers more evenly.</para>
+      </note>
+      <note>
+	<para>Some older versions of <command>portsnap</command>
+	  do not support listing multiple commands (e.g., <literal>cron update</literal>)
+	  in the same invocation of <command>portsnap</command>.  If
+	  the line above fails, try replacing
+	  <command>portsnap -I cron update</command> with
+	  <command>portsnap cron &amp;&amp; portsnap -I update</command>.</para>
+      </note>
+    </sect2>
+  </sect1>
+
+  <sect1 id="cvs-tags">
+    <title>CVS Tags</title>
+
+    <para>When obtaining or updating sources using
+      <application>cvs</application> or
+      <application>CVSup</application>, a revision tag must be specified.
+      A revision tag refers to either a particular line of &os;
+      development, or a specific point in time.  The first type are called
+      <quote>branch tags</quote>, and the second type are called
+      <quote>release tags</quote>.</para>
+
+    <sect2>
+      <title>Branch Tags</title>
+
+      <para>All of these, with the exception of <literal>HEAD</literal> (which
+	is always a valid tag), only apply to the <filename>src/</filename>
+	tree.  The <filename>ports/</filename>, <filename>doc/</filename>, and
+	<filename>www/</filename> trees are not branched.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>HEAD</term>
+
+	<listitem>
+	  <para>Symbolic name for the main line, or FreeBSD-CURRENT.
+	    Also the default when no revision is specified.</para>
+
+	  <para>In <application>CVSup</application>, this tag is represented
+	    by a <literal>.</literal> (not punctuation, but a literal
+	    <literal>.</literal> character).</para>
+
+	  <note>
+	    <para>In CVS, this is the default when no revision tag is
+	      specified.  It is usually <emphasis>not</emphasis>
+	      a good idea to checkout or update to CURRENT sources
+	      on a STABLE machine, unless that is your intent.</para>
+	  </note>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_6</term>
+
+	<listitem>
+	  <para>The line of development for FreeBSD-6.X, also known
+	    as FreeBSD 6-STABLE</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_6_1</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-6.1, used only for
+	    security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_6_0</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-6.0, used only for
+	    security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5</term>
+
+	<listitem>
+	  <para>The line of development for FreeBSD-5.X, also known
+	    as FreeBSD 5-STABLE.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_5</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-5.5, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_4</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-5.4, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_3</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-5.3, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_2</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-5.2 and FreeBSD-5.2.1, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_1</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-5.1, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_0</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-5.0, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4</term>
+
+	<listitem>
+	  <para>The line of development for FreeBSD-4.X, also known
+	    as FreeBSD 4-STABLE.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_11</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.11, used only
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_10</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.10, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_9</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.9, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_8</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.8, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_7</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.7, used only 
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_6</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.6 and FreeBSD-4.6.2,
+            used only for security advisories and other
+            critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_5</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.5, used only
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_4</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.4, used only
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_3</term>
+
+	<listitem>
+	  <para>The release branch for FreeBSD-4.3, used only
+	    for security advisories and other critical fixes.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_3</term>
+
+	<listitem>
+	  <para>The line of development for FreeBSD-3.X, also known
+	    as 3.X-STABLE.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2</term>
+
+	<listitem>
+	  <para>The line of development for FreeBSD-2.2.X, also known
+	    as 2.2-STABLE.  This branch is mostly obsolete.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Release Tags</title>
+
+      <para>These tags refer to a specific point in time when a particular
+	version	of &os; was released.  The release engineering process is
+	documented in more detail by the
+	<ulink url="&url.base;/releng/">Release Engineering
+	  Information</ulink> and
+        <ulink url="&url.articles.releng;/release-proc.html">Release
+	  Process</ulink> documents.
+	The <filename class="directory">src</filename> tree uses tag names that
+	start with <literal>RELENG_</literal> tags.
+	The <filename class="directory">ports</filename> and
+	<filename class="directory">doc</filename> trees use tags whose names
+	begin with <literal>RELEASE</literal> tags.
+	Finally, the <filename class="directory">www</filename> tree is not
+	tagged with any special name for releases.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>RELENG_6_1_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 6.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_6_0_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 6.0</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_5_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.5</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_4_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.4</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_11_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.11</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_3_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.3</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_10_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.10</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_2_1_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.2.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_2_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.2</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_9_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.9</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_1_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_8_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.8</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_5_0_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 5.0</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_7_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.7</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_6_2_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.6.2</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_6_1_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.6.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_6_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.6</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_5_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.5</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_4_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.4</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_3_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.3</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_2_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.2</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_1_1_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.1.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_1_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_4_0_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD 4.0</para>
+	</listitem>
+      </varlistentry>
+	  
+      <varlistentry>
+	<term>RELENG_3_5_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-3.5</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_3_4_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-3.4</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_3_3_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-3.3</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_3_2_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-3.2</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_3_1_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-3.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_3_0_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-3.0</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_8_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.8</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_7_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.7</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_6_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.6</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_5_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.5</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_2_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.2</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_1_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.1</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>RELENG_2_2_0_RELEASE</term>
+
+	<listitem>
+	  <para>FreeBSD-2.2.0</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="mirrors-afs">
+    <title>AFS Sites</title>
+
+    <para>AFS servers for FreeBSD are running at the following sites:</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>Sweden</term>
+
+	<listitem>
+	  <para>The path to the files are:
+  	    <filename>/afs/stacken.kth.se/ftp/pub/FreeBSD/</filename></para>
+
+	  <programlisting>stacken.kth.se         # Stacken Computer Club, KTH, Sweden
+130.237.234.43         #hot.stacken.kth.se
+130.237.237.230        #fishburger.stacken.kth.se
+130.237.234.3          #milko.stacken.kth.se</programlisting>
+
+	  <para>Maintainer <email>ftp@stacken.kth.se</email></para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </sect1>
+
+  <sect1 id="mirrors-rsync">
+    <title>rsync Sites</title>
+
+    <para>The following sites make FreeBSD available through the rsync
+      protocol.  The <application>rsync</application> utility works in
+      much the same way as the &man.rcp.1; command,
+      but has more options and uses the rsync remote-update protocol
+      which transfers only the differences between two sets of files,
+      thus greatly speeding up the synchronization over the network.  
+      This is most useful if you are a mirror site for the
+      FreeBSD FTP server, or the CVS repository.  The
+      <application>rsync</application> suite is available for many
+      operating systems, on FreeBSD, see the
+      <filename role="package">net/rsync</filename>
+      port or use the package.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>Czech Republic</term>
+
+	<listitem>
+	  <para>rsync://ftp.cz.FreeBSD.org/</para>
+
+	  <para>Available collections:</para>
+	  <itemizedlist>
+	    <listitem><para>ftp: A partial mirror of the FreeBSD FTP
+	      server.</para></listitem>
+	    <listitem><para>FreeBSD: A full mirror of the FreeBSD FTP
+	      server.</para></listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Germany</term>
+
+	<listitem>
+	  <para>rsync://grappa.unix-ag.uni-kl.de/</para>
+
+	  <para>Available collections:</para>
+	  <itemizedlist>
+	    <listitem><para>freebsd-cvs: The full FreeBSD CVS
+	      repository.</para></listitem>
+	  </itemizedlist>
+	  <para>This machine also mirrors the CVS repositories of the
+	    NetBSD and the OpenBSD projects, among others.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Netherlands</term>
+
+	<listitem>
+	  <para>rsync://ftp.nl.FreeBSD.org/</para>
+
+	  <para>Available collections:</para>
+	  <itemizedlist>
+	    <listitem><para>vol/4/freebsd-core: A full mirror of the
+	      FreeBSD FTP server.</para></listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>United Kingdom</term>
+
+	<listitem>
+	  <para>rsync://rsync.mirror.ac.uk/</para>
+
+	  <para>Available collections:</para>
+	  <itemizedlist>
+	    <listitem><para>ftp.FreeBSD.org: A full mirror of the
+	      FreeBSD FTP server.</para></listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>United States of America</term>
+
+	<listitem>
+	  <para>rsync://ftp-master.FreeBSD.org/</para>
+
+	  <para>This server may only be used by FreeBSD primary mirror
+	    sites.</para>
+	  <para>Available collections:</para>
+	  <itemizedlist>
+	    <listitem><para>FreeBSD: The master archive of the FreeBSD
+	      FTP server.</para></listitem>
+	    <listitem><para>acl: The FreeBSD master ACL
+	      list.</para></listitem>  
+	  </itemizedlist>
+
+	  <para>rsync://ftp13.FreeBSD.org/</para>
+
+	  <para>Available collections:</para>
+	  <itemizedlist>
+	    <listitem><para>FreeBSD: A full mirror of the FreeBSD FTP
+	      server.</para></listitem>
+	  </itemizedlist>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+  </sect1>  
+</appendix>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../appendix.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "appendix")
+     End:
+-->
+
diff --git a/pl_PL.ISO8859-2/books/handbook/multimedia/Makefile b/pl_PL.ISO8859-2/books/handbook/multimedia/Makefile
new file mode 100644
index 0000000000..f90e1cd2b0
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/multimedia/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	multimedia/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/multimedia/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/multimedia/chapter.sgml
new file mode 100644
index 0000000000..3b22f16cb9
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/multimedia/chapter.sgml
@@ -0,0 +1,1798 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="multimedia">
+ <chapterinfo>
+  <authorgroup>
+   <author>
+    <firstname>Ross</firstname>
+    <surname>Lippert</surname>
+    <contrib>Edited by </contrib>
+   </author>
+  </authorgroup>
+ </chapterinfo>
+
+ <title>Multimedia</title>
+  <sect1 id="multimedia-synopsis">
+  <title>Synopsis</title>
+
+    <para>FreeBSD supports a wide variety of sound cards, allowing you
+      to enjoy high fidelity output from your computer.  This includes
+      the ability to record and playback audio in the MPEG Audio Layer
+      3 (MP3), WAV, and Ogg Vorbis formats as well as many other
+      formats.  The FreeBSD Ports Collection also contains
+      applications allowing you to edit your recorded audio, add sound
+      effects, and control attached MIDI devices.</para>
+
+    <para>With some willingness to experiment, FreeBSD can support
+      playback of video files and DVD's.  The number of applications
+      to encode, convert, and playback various video media is more
+      limited than the number of sound applications.  For example as
+      of this writing, there is no good re-encoding application in the
+      FreeBSD Ports Collection, which could be use to convert
+      between formats, as there is with <filename
+      role="package">audio/sox</filename>.  However, the software
+      landscape in this area is changing rapidly.</para>
+
+    <para>This chapter will describe the necessary steps to configure
+      your sound card.  The configuration and installation of X11
+      (<xref linkend="x11">) has already taken care of the
+      hardware issues for your video card, though there may be some
+      tweaks to apply for better playback.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>How to configure your system so that your sound card is
+          recognized.</para>
+      </listitem>
+
+      <listitem>
+        <para>Methods to test that your card is working using
+          sample applications.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to troubleshoot your sound setup.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to playback and encode MP3s and other audio.</para>
+      </listitem>
+
+      <listitem>
+        <para>How video is supported by the X server.</para>
+      </listitem>
+
+      <listitem>
+        <para>Some video player/encoder ports which give good results.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to playback DVD's, <filename>.mpg</filename> and
+          <filename>.avi</filename> files.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to rip CD and DVD information into files.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure a TV card.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure an image scanner.</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>
+
+    <warning>
+      <para>Trying to mount audio CDs
+        with the &man.mount.8; command will
+        result in an error, at least, and a <emphasis>kernel
+        panic</emphasis>, at worst.  These media have specialized
+        encodings which differ from the usual ISO-filesystem.</para>
+    </warning>
+
+  </sect1>
+
+  <sect1 id="sound-setup">
+    <sect1info>
+      <authorgroup>
+        <author>
+	 <firstname>Moses</firstname>
+	 <surname>Moore</surname>
+	 <contrib>Contributed by </contrib>
+	 <!-- 20 November 2000 -->
+        </author>
+      </authorgroup>
+      <authorgroup>
+        <author>
+	 <firstname>Marc</firstname>
+	 <surname>Fonvieille</surname>
+	 <contrib>Enhanced for &os;&nbsp;5.X by </contrib>
+	 <!-- 13 September 2004 -->
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Setting Up the Sound Card</title>
+    
+  <sect2 id="sound-device">
+    <title>Configuring the System</title>
+
+    <indexterm><primary>PCI</primary></indexterm>
+    <indexterm><primary>ISA</primary></indexterm>
+    <indexterm><primary>sound cards</primary></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 supported audio devices list of the <ulink
+      url="&rel.current.hardware;">Hardware Notes</ulink> to see if
+      your card is supported.  This document will also mention which
+      driver supports your card.</para>
+
+    <indexterm>
+      <primary>kernel</primary>
+      <secondary>configuration</secondary>
+    </indexterm>
+
+    <para>To use your sound device, you will need to load the proper
+      device driver.  This may be accomplished in one of two ways.
+      The easiest way is to simply load a kernel module for your sound
+      card with &man.kldload.8; which can either be done from the
+      command line:</para>
+
+    <screen>&prompt.root; <userinput>kldload snd_emu10k1</userinput></screen>
+
+    <para>or by adding the appropriate line to the file
+      <filename>/boot/loader.conf</filename> like this:</para>
+
+    <programlisting>snd_emu10k1_load="YES"</programlisting>
+
+    <para>These examples are for a Creative &soundblaster; Live! sound
+      card.  Other available loadable sound modules are listed in
+      <filename>/boot/defaults/loader.conf</filename>.
+      If you are not sure which driver to use, you may try to load
+      the <filename>snd_driver</filename> module:</para>
+
+    <screen>&prompt.root; <userinput>kldload snd_driver</userinput></screen>
+
+    <para>This is a metadriver loading the most common device drivers
+      at once.  This speeds up the search for the correct driver.  It
+      is also possible to load all sound drivers via the
+      <filename>/boot/loader.conf</filename> facility.</para>
+
+    <para>If you wish to find out the driver selected for your
+      soundcard after loading the <filename>snd_driver</filename>
+      metadriver, you may check the <filename>/dev/sndstat</filename>
+      file with the <command>cat /dev/sndstat</command>
+      command.</para>
+
+    <para>A second method is to statically
+      compile in support for your sound card in your kernel.  The
+      section below provides the information you need to add support
+      for your hardware in this manner.  For more information about
+      recompiling your kernel, please see <xref
+      linkend="kernelconfig">.</para>
+
+    <sect3>
+      <title>Configuring a Custom Kernel with Sound Support</title>
+
+      <para>The first thing to do is adding the generic audio driver
+	&man.sound.4; to the kernel, for that you will need to
+	add the following line to the kernel configuration file:</para>
+
+      <programlisting>device sound</programlisting>
+
+      <para>Then we have to add the support for our sound card.
+	Therefore, we need to know which driver supports the card.
+	Check the supported audio devices list of the <ulink
+	url="&rel.current.hardware;">Hardware Notes</ulink>, to
+	determine the correct driver for your sound card.  For
+	example, a Creative &soundblaster; Live! sound card is
+	supported by the &man.snd.emu10k1.4; driver.  To add the support
+	for this card, use the following:</para>
+
+      <programlisting>device snd_emu10k1</programlisting>
+
+      <para>Be sure to read the manual page of the driver for the
+	syntax to use.  Information regarding the syntax of sound
+	drivers in the kernel configuration can also be found in the
+	<filename>/usr/src/sys/conf/NOTES</filename> file.</para>
+
+      <para>Non-PnP ISA cards may require you to provide the kernel
+	with information on the sound card settings (IRQ, I/O port,
+	etc).  This is done via the
+	<filename>/boot/device.hints</filename> file.  At system boot,
+	the &man.loader.8; will read this file and pass the settings
+	to the kernel.  For example, an old
+	Creative &soundblaster; 16 ISA non-PnP card will use the
+	&man.snd.sbc.4; driver in conjunction with snd_sb16(4).  For this card the following lines have to be added to
+	the kernel configuration file:</para>
+
+      <programlisting>device snd_sbc
+device snd_sb16</programlisting>
+
+      <para>as well as the following in
+	<filename>/boot/device.hints</filename>:</para>
+
+      <programlisting>hint.sbc.0.at="isa"
+hint.sbc.0.port="0x220"
+hint.sbc.0.irq="5"
+hint.sbc.0.drq="1"
+hint.sbc.0.flags="0x15"</programlisting>
+
+      <para>In this case, the card uses the <literal>0x220</literal>
+	I/O port and the IRQ <literal>5</literal>.</para>
+
+      <para>The syntax used in the
+	<filename>/boot/device.hints</filename> file is covered in the
+	sound driver manual page.  On &os;&nbsp;4.X, these settings
+	are directly written in the kernel configuration file.</para>
+
+      <para>The settings shown above are the defaults.  In some
+	cases, you may need to change the IRQ or the other settings to
+	match your card.  See the &man.snd.sbc.4; manual page for more
+	information.</para>
+    </sect3>
+  </sect2>
+
+  <sect2 id="sound-testing">
+    <title>Testing the Sound Card</title>
+
+    <para>After rebooting with the modified kernel, or after loading
+      the required module, the sound card should appear in your system
+      message buffer (&man.dmesg.8;) as something like:</para>
+
+    <screen>pcm0: &lt;Intel ICH3 (82801CA)&gt; port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0
+pcm0: [GIANT-LOCKED]
+pcm0: &lt;Cirrus Logic CS4205 AC97 Codec&gt;</screen>
+
+    <para>The status of the sound card may be checked via the
+      <filename>/dev/sndstat</filename> file:</para>
+
+    <screen>&prompt.root; <userinput>cat /dev/sndstat</userinput>
+FreeBSD Audio Driver (newpcm)
+Installed devices:
+pcm0: &lt;Intel ICH3 (82801CA)&gt; at io 0xd800, 0xdc80 irq 5 bufsz 16384
+kld snd_ich (1p/2r/0v channels duplex default)</screen>
+
+    <para>The output from your system may vary.  If no
+      <devicename>pcm</devicename> devices show up, go back and review
+      what was done earlier.  Go through your kernel
+      configuration file again and make sure the correct
+      device is chosen.  Common problems are listed in <xref
+      linkend="troubleshooting">.</para>
+
+    <para>If all goes well, you should now have a functioning sound
+      card.  If your CD-ROM or DVD-ROM drive is properly coupled to
+      your sound card, you can put a CD in the drive and play it
+      with &man.cdcontrol.1;:</para>
+
+      <screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0 play 1</userinput></screen>
+
+    <para>Various applications, such as <filename
+      role="package">audio/workman</filename> can provide a friendlier
+      interface.  You may want to install an application such as
+      <filename role="package">audio/mpg123</filename> to listen to
+      MP3 audio files.  A quick way to test the card is sending data
+      to the <filename>/dev/dsp</filename>, like this:</para>
+
+    <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> &gt; /dev/dsp</userinput></screen>
+
+    <para>where <replaceable>filename</replaceable> can be any file.
+      This command line should produce some noise, confirming the
+      sound card is actually working.</para>
+
+    <para>Sound card mixer levels can be changed via the &man.mixer.8;
+      command.  More details can be found in the &man.mixer.8; manual
+      page.</para>
+
+    <sect3 id="troubleshooting">
+      <title>Common Problems</title>
+
+      <indexterm><primary>device nodes</primary></indexterm>
+      <indexterm><primary>I/O port</primary></indexterm>
+      <indexterm><primary>IRQ</primary></indexterm>
+      <indexterm><primary>DSP</primary></indexterm>
+
+      <informaltable frame="none" pgwide="1">
+         <tgroup cols="2">
+  	  <thead>
+	    <row>
+	     <entry>Error</entry>
+	      <entry>Solution</entry>
+	    </row>
+          </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><errorname>unsupported subdevice XX</errorname></entry>
+	      <entry><para>One or more of the device nodes was not created
+	        correctly.  Repeat the steps above.</para></entry>
+            </row>
+
+            <row>
+              <entry><errorname>sb_dspwr(XX) timed out</errorname></entry>
+              <entry><para>The I/O port is not set correctly.</para></entry>
+            </row>
+
+            <row>
+              <entry><errorname>bad irq XX</errorname></entry>
+	      <entry><para>The IRQ is set incorrectly.  Make sure that
+  	        the set IRQ and the sound IRQ are the same.</para></entry>
+            </row>
+
+            <row>
+              <entry><errorname>xxx: gus pcm not attached, out of memory</errorname></entry>
+              <entry><para>There is not enough available memory to use
+                the device.</para></entry>
+            </row>
+
+            <row>
+              <entry><errorname>xxx: can't open /dev/dsp!</errorname></entry>
+              <entry><para>Check with <command>fstat | grep dsp</command>
+                if another application is holding the device open.
+                Noteworthy troublemakers are <application>esound</application> and <application>KDE</application>'s sound
+                support.</para></entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </sect3>
+  </sect2>
+
+  <sect2 id="sound-multiple-sources">
+    <sect2info>
+     <authorgroup>
+      <author>
+       <firstname>Munish</firstname>
+       <surname>Chopra</surname>
+       <contrib>Contributed by </contrib>
+      </author>
+     </authorgroup>
+    </sect2info>
+    <title>Utilizing Multiple Sound Sources</title>
+
+    <para>It is often desirable to have multiple sources of sound that
+      are able to play simultaneously, such as when
+      <application>esound</application> or
+      <application>artsd</application> do not support sharing of the
+      sound device with a certain application.</para>
+
+    <para>FreeBSD lets you do this through <emphasis>Virtual Sound
+      Channels</emphasis>, which can be set with the &man.sysctl.8;
+      facility.  Virtual channels allow you to multiplex your sound
+      card's playback channels by mixing sound in the kernel.</para>
+
+    <para>To set the number of virtual channels, there are two sysctl
+      knobs which, if you are the <username>root</username> user, can
+      be set like this:</para>
+    <screen>&prompt.root; <userinput>sysctl hw.snd.pcm0.vchans=4</userinput>
+&prompt.root; <userinput>sysctl hw.snd.maxautovchans=4</userinput></screen>
+
+    <para>The above example allocates four virtual channels, which is a
+      practical number for everyday use.  <varname>hw.snd.pcm0.vchans</varname>
+      is the number of virtual channels <devicename>pcm0</devicename> has, and is configurable
+      once a device has been attached.
+      <literal>hw.snd.maxautovchans</literal> is the number of virtual channels
+      a new audio device is given when it is attached using
+      &man.kldload.8;.  Since the <devicename>pcm</devicename> module
+      can be loaded independently of the hardware drivers,
+      <varname>hw.snd.maxautovchans</varname> can store how many
+      virtual channels any devices which are attached later will be
+      given.</para>
+
+    <note>
+      <para>You cannot change the number of virtual channels for a
+	device while it is in use.  First close any programs using the
+	device, such as music players or sound daemons.</para>
+    </note>
+
+    <para>If you are not using &man.devfs.5;, you will have to point
+      your applications at
+      <filename>/dev/dsp0</filename>.<replaceable>x</replaceable>,
+      where <replaceable>x</replaceable> is 0 to 3 if
+      <varname>hw.snd.pcm.0.vchans</varname> is set to 4 as in the
+      above example.  On a system using &man.devfs.5;, the above will
+      automatically be allocated transparently to the user.</para>
+   </sect2>
+
+  <sect2>
+    <sect2info>
+      <authorgroup>
+	<author>
+	  <firstname>Josef</firstname>
+	  <surname>El-Rayes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect2info>
+
+    <title>Setting Default Values for Mixer Channels</title>
+
+    <note>
+      <para>This is only supported in &os; 5.3-RELEASE and later.</para>
+    </note>
+
+    <para>The default values for the different mixer channels are
+      hardcoded in the sourcecode of the &man.pcm.4; driver.  There are
+      a lot of different applications and daemons that allow
+      you to set values for the mixer they remember and set
+      each time they are started, but this is not a clean
+      solution, we want to have default values at the driver
+      level.  This is accomplished by defining the appropriate
+      values in <filename>/boot/device.hints</filename>. E.g.:</para>
+<programlisting>hint.pcm.0.vol="100"</programlisting>
+
+    <para>This will set the volume channel to a default value of
+      100, when the &man.pcm.4; module is loaded.</para>
+  </sect2>
+</sect1>
+
+  <sect1 id="sound-mp3">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Chern</firstname>
+	  <surname>Lee</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 11 Sept 2001 -->
+    </sect1info>
+
+    <title>MP3 Audio</title>
+
+    <para>MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound,
+      leaving no reason to let your FreeBSD workstation fall short of
+      its offerings.</para>
+
+    <sect2 id="mp3-players">
+      <title>MP3 Players</title>
+
+      <para>By far, the most popular X11 MP3 player is
+	<application>XMMS</application> (X Multimedia System).  
+	<application>Winamp</application>
+	skins can be used with <application>XMMS</application> since the
+	GUI is almost identical to that of Nullsoft's 
+	<application>Winamp</application>.
+	<application>XMMS</application> also has native plug-in
+	support.</para>
+
+      <para><application>XMMS</application> can be installed from the
+	<filename role="package">multimedia/xmms</filename> port or package.</para>
+
+      <para><application>XMMS'</application> interface is intuitive,
+	with a playlist, graphic equalizer, and more.  Those familiar
+	with <application>Winamp</application> will find
+	<application>XMMS</application> simple to use.</para>
+
+      <para>The <filename role="package">audio/mpg123</filename> port is an alternative,
+	command-line MP3 player.</para>
+
+      <para><application>mpg123</application> can be run by specifying
+	the sound device and the MP3 file on the command line, as
+	shown below:</para>
+
+      <screen>&prompt.root; <userinput>mpg123 -a <replaceable>/dev/dsp1.0</replaceable> Foobar-GreatestHits.mp3</userinput>
+High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3.
+Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp.
+Uses code from various people. See 'README' for more!
+THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK!
+
+
+
+
+
+Playing MPEG stream from Foobar-GreatestHits.mp3 ...
+MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo
+</screen>
+
+      <para><literal>/dev/dsp1.0</literal> should be replaced with the
+	<devicename>dsp</devicename> device entry on your system.</para>
+
+    </sect2>
+
+    <sect2 id="rip-cd">
+      <title>Ripping CD Audio Tracks</title>
+
+      <para>Before encoding a CD or CD track to MP3, the audio data on
+	the CD must be ripped onto the hard drive.  This is done by
+	copying the raw CDDA (CD Digital Audio) data to WAV
+	files.</para>
+
+      <para>The <command>cdda2wav</command> tool, which is a part of
+	the <filename role="package">sysutils/cdrtools</filename>
+	suite, is used for ripping audio information from CDs and the
+	information associated with them.</para>
+
+      <para>With the audio CD in the drive, the following command can
+	be issued (as <username>root</username>) to rip an entire CD
+	into individual (per track) WAV files:</para>
+
+      <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -B</userinput></screen>
+
+      <para><application>cdda2wav</application> will support
+	ATAPI (IDE) CDROM drives.  To rip from an IDE drive, specify
+	the device name in place of the SCSI unit numbers.  For
+	example, to rip track 7 from an IDE drive:</para>
+
+      <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>/dev/acd0a</replaceable> -t 7</userinput></screen>
+
+      <para>The <option>-D <replaceable>0,1,0</replaceable></option>
+	indicates the SCSI device <devicename>0,1,0</devicename>,
+	which corresponds to the output of <command>cdrecord
+	-scanbus</command>.</para>
+
+      <para>To rip individual tracks, make use of the
+	<option>-t</option> option as shown:</para>
+
+      <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 7</userinput></screen>
+
+      <para>This example rips track seven of the audio CDROM.  To rip
+	a range of tracks, for example, track one to seven, specify a
+	range:</para>
+
+      <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 1+7</userinput></screen>
+
+      <para>The utility &man.dd.1; can also be used to extract audio tracks
+	on ATAPI drives, read <xref linkend="duplicating-audiocds">
+	for more information on that possibility.</para>
+
+    </sect2>
+
+    <sect2 id="mp3-encoding">
+      <title>Encoding MP3s</title>
+
+      <para>Nowadays, the mp3 encoder of choice is
+	<application>lame</application>.
+	<application>Lame</application> can be found at
+	<filename role="package">audio/lame</filename> in the ports tree.</para>
+
+      <para>Using the ripped WAV files, the following command will
+	convert <filename>audio01.wav</filename> to
+	<filename>audio01.mp3</filename>:</para>
+
+      <screen>&prompt.root; <userinput>lame -h -b <replaceable>128</replaceable> \
+--tt "<replaceable>Foo Song Title</replaceable>" \
+--ta "<replaceable>FooBar Artist</replaceable>" \
+--tl "<replaceable>FooBar Album</replaceable>" \
+--ty "<replaceable>2001</replaceable>" \
+--tc "<replaceable>Ripped and encoded by Foo</replaceable>" \
+--tg "<replaceable>Genre</replaceable>" \
+<replaceable>audio01.wav audio01.mp3</replaceable></userinput></screen>
+
+      <para>128&nbsp;kbits seems to be the standard MP3 bitrate in use.
+	Many enjoy the higher quality 160, or 192.  The higher the
+	bitrate, the more disk space the resulting MP3 will
+	consume--but the quality will be higher.  The
+	<option>-h</option> option turns on the <quote>higher quality
+	but a little slower</quote> mode.  The options beginning with
+	<option>--t</option> indicate ID3 tags, which usually contain
+	song information, to be embedded within the MP3 file.
+	Additional encoding options can be found by consulting the
+	lame man page.</para>
+    </sect2>
+
+    <sect2 id="mp3-decoding">
+      <title>Decoding MP3s</title>
+
+      <para>In order to burn an audio CD from MP3s, they must be
+	converted to a non-compressed WAV format.  Both
+	<application>XMMS</application> and
+	<application>mpg123</application> support the output of MP3 to
+	an uncompressed file format.</para>
+
+      <para>Writing to Disk in <application>XMMS</application>:</para>
+
+      <procedure>
+	<step>
+	  <para>Launch <application>XMMS</application>.</para>
+	</step>
+
+	<step>
+	  <para>Right-click on the window to bring up the
+	    <application>XMMS</application> menu.</para>
+	</step>
+
+	<step>
+	  <para>Select <literal>Preference</literal> under
+	    <literal>Options</literal>.</para>
+	</step>
+
+	<step>
+	  <para>Change the Output Plugin to <quote>Disk Writer
+	      Plugin</quote>.</para>
+	</step>
+
+	<step>
+	  <para>Press <literal>Configure</literal>.</para>
+	</step>
+
+	<step>
+	  <para>Enter (or choose browse) a directory to write the
+	    uncompressed files to.</para>
+	</step>
+
+	<step>
+	  <para>Load the MP3 file into <application>XMMS</application>
+	    as usual, with volume at 100% and EQ settings turned
+	    off.</para>
+	</step>
+
+	<step>
+	  <para>Press <literal>Play</literal> &mdash;
+	    <application>XMMS</application> will appear as if it is
+	    playing the MP3, but no music will be heard.  It is
+	    actually playing the MP3 to a file.</para>
+	</step>
+
+	<step>
+	  <para>Be sure to set the default Output Plugin back to what
+	    it was before in order to listen to MP3s again.</para>
+	</step>
+      </procedure>
+
+      <para>Writing to stdout in <application>mpg123</application>:</para>
+
+      <procedure>
+	<step>
+	  <para>Run <command>mpg123 -s <replaceable>audio01.mp3</replaceable>
+	    &gt; audio01.pcm</command></para>
+	</step>
+      </procedure>
+
+      <para><application>XMMS</application> writes a file in the WAV
+	format, while <application>mpg123</application> converts the
+	MP3 into raw PCM audio data.  Both of these formats can be
+	used with <application>cdrecord</application> to create audio CDs.
+	You have to use raw PCM with &man.burncd.8;.
+	If you use WAV files, you will notice a small tick sound at the
+	beginning of each track, this sound is the header of the WAV
+	file.  You can simply remove the header of a WAV file with the
+	utility <application>SoX</application> (it can be installed from
+	the <filename role="package">audio/sox</filename> port or
+	package):</para>
+
+      <screen>&prompt.user; <userinput>sox -t wav -r 44100 -s -w -c 2 <replaceable>track.wav track.raw</replaceable></userinput></screen>
+
+      <para>Read <xref linkend="creating-cds"> for more information on using a
+	  CD burner in FreeBSD.</para>
+    </sect2>
+ </sect1>
+
+ <sect1 id="video-playback">
+  <sect1info>
+    <authorgroup>
+      <author>
+        <firstname>Ross</firstname>
+	<surname>Lippert</surname>
+	<contrib>Contributed by </contrib>
+      </author>
+    </authorgroup>
+    <!-- 5 June 2002 -->
+  </sect1info>
+
+  <title>Video Playback</title>
+
+    <para>Video playback is a very new and rapidly developing application
+      area.  Be patient.  Not everything is going to work as smoothly as
+      it did with sound.</para>
+
+    <para>Before you begin, you should know the model of the video
+      card you have and the chip it uses.  While <application>&xorg;</application> and <application>&xfree86;</application> support a
+      wide variety of video cards, fewer give good playback
+      performance.  To obtain a list of extensions supported by the
+      X server using your card use the command &man.xdpyinfo.1; while
+      X11 is running.</para>
+
+    <para>It is a good idea to have a short MPEG file which can be
+      treated as a test file for evaluating various players and
+      options.  Since some DVD players will look for DVD media in
+      <filename>/dev/dvd</filename> by default, or have this device
+      name hardcoded in them, you might find it useful to make
+      symbolic links to the proper devices:</para>
+
+      <screen>&prompt.root; <userinput>ln -sf /dev/acd0c /dev/dvd</userinput>
+&prompt.root; <userinput>ln -sf /dev/racd0c /dev/rdvd</userinput></screen>
+
+    <para>On FreeBSD&nbsp;5.X, which uses &man.devfs.5; there
+        is a slightly different set of recommended links:</para>
+
+      <screen>&prompt.root; <userinput>ln -sf /dev/acd0 /dev/dvd</userinput>
+&prompt.root; <userinput>ln -sf /dev/acd0 /dev/rdvd</userinput></screen>
+
+    <para>Note that due to the nature of &man.devfs.5;,
+      manually created links like these will not persist if you reboot
+      your system.  In order to create the symbolic links
+      automatically whenever you boot your system, add the following
+      lines to <filename>/etc/devfs.conf</filename>:</para>
+
+    <programlisting>link acd0 dvd
+link acd0 rdvd</programlisting>
+
+    <para>Additionally, DVD decryption, which requires invoking
+      special DVD-ROM functions, requires write permission on the DVD
+      devices.</para>
+
+    <indexterm>
+      <primary>kernel options</primary>
+      <secondary>CPU_ENABLE_SSE</secondary>
+    </indexterm>
+
+    <para>Some of the ports discussed rely on the following kernel
+      options to build correctly.  Before attempting to build, add
+      this option to the kernel configuration file, build a new kernel, and reboot:</para>
+
+      <programlisting>options CPU_ENABLE_SSE</programlisting>
+
+    <para>To enhance the shared memory X11 interface, it is
+      recommended that the values of some &man.sysctl.8; variables
+      should be increased:</para>
+
+      <programlisting>kern.ipc.shmmax=67108864
+kern.ipc.shmall=32768</programlisting>
+
+  <sect2 id="video-interface">
+    <title>Determining Video Capabilities</title>
+
+    <indexterm><primary>XVideo</primary></indexterm>
+    <indexterm><primary>SDL</primary></indexterm>
+    <indexterm><primary>DGA</primary></indexterm>
+
+    <para>There are several possible ways to display video under X11.
+      What will really work is largely hardware dependent.  Each
+      method described below will have varying quality across
+      different hardware.  Secondly, the rendering of video in X11 is
+      a topic receiving a lot of attention lately, and with each
+      version of <application>&xorg;</application>, or of <application>&xfree86;</application>, there may be significant improvement.</para>
+
+    <para>A list of common video interfaces:</para>
+
+    <orderedlist>
+    <listitem>
+      <para>X11: normal X11 output using shared memory.</para>
+    </listitem>
+    <listitem>
+      <para>XVideo: an extension to the X11
+      interface which supports video in any X11 drawable.</para>
+    </listitem>
+    <listitem>
+      <para>SDL: the Simple Directmedia Layer.</para>
+    </listitem>
+    <listitem>
+      <para>DGA: the Direct Graphics Access.</para>
+    </listitem>
+    <listitem>
+      <para>SVGAlib: low level console graphics layer.</para>
+    </listitem>
+    </orderedlist>
+
+    <sect3 id="video-interface-xvideo">
+    <title>XVideo</title>
+
+      <para><application>&xorg;</application> and <application>&xfree86; 4.X</application> have an extension called
+        <emphasis>XVideo</emphasis> (aka Xvideo, aka Xv, aka xv) which
+        allows video to be directly displayed in drawable objects
+        through a special acceleration.  This extension provides very
+        good quality playback even on low-end machines.</para>
+
+      <para>To check whether the extension is running,
+      use <command>xvinfo</command>:</para>
+
+        <screen>&prompt.user; <userinput>xvinfo</userinput></screen>
+
+      <para>XVideo is supported for your card if the result looks like:</para>
+<screen>X-Video Extension version 2.2
+screen #0
+  Adaptor #0: "Savage Streams Engine"
+    number of ports: 1
+    port base: 43
+    operations supported: PutImage 
+    supported visuals:
+      depth 16, visualID 0x22
+      depth 16, visualID 0x23
+    number of attributes: 5
+      "XV_COLORKEY" (range 0 to 16777215)
+              client settable attribute
+              client gettable attribute (current value is 2110)
+      "XV_BRIGHTNESS" (range -128 to 127)
+              client settable attribute
+              client gettable attribute (current value is 0)
+      "XV_CONTRAST" (range 0 to 255)
+              client settable attribute
+              client gettable attribute (current value is 128)
+      "XV_SATURATION" (range 0 to 255)
+              client settable attribute
+              client gettable attribute (current value is 128)
+      "XV_HUE" (range -180 to 180)
+              client settable attribute
+              client gettable attribute (current value is 0)
+    maximum XvImage size: 1024 x 1024
+    Number of image formats: 7
+      id: 0x32595559 (YUY2)
+        guid: 59555932-0000-0010-8000-00aa00389b71
+        bits per pixel: 16
+        number of planes: 1
+        type: YUV (packed)
+      id: 0x32315659 (YV12)
+        guid: 59563132-0000-0010-8000-00aa00389b71
+        bits per pixel: 12
+        number of planes: 3
+        type: YUV (planar)
+      id: 0x30323449 (I420)
+        guid: 49343230-0000-0010-8000-00aa00389b71
+        bits per pixel: 12
+        number of planes: 3
+        type: YUV (planar)
+      id: 0x36315652 (RV16)
+        guid: 52563135-0000-0000-0000-000000000000
+        bits per pixel: 16
+        number of planes: 1
+        type: RGB (packed)
+        depth: 0
+        red, green, blue masks: 0x1f, 0x3e0, 0x7c00
+      id: 0x35315652 (RV15)
+        guid: 52563136-0000-0000-0000-000000000000
+        bits per pixel: 16
+        number of planes: 1
+        type: RGB (packed)
+        depth: 0
+        red, green, blue masks: 0x1f, 0x7e0, 0xf800
+      id: 0x31313259 (Y211)
+        guid: 59323131-0000-0010-8000-00aa00389b71
+        bits per pixel: 6
+        number of planes: 3
+        type: YUV (packed)
+      id: 0x0
+        guid: 00000000-0000-0000-0000-000000000000
+        bits per pixel: 0
+        number of planes: 0
+        type: RGB (packed)
+        depth: 1
+        red, green, blue masks: 0x0, 0x0, 0x0</screen>
+
+    <para>Also note that the formats listed (YUV2, YUV12, etc) are not
+     present with every implementation of XVideo and their absence may
+     hinder some players.</para>
+
+    <para>If the result looks like:</para>
+<screen>X-Video Extension version 2.2
+screen #0
+no adaptors present</screen>
+
+    <para>Then XVideo is probably not supported for your card.</para>
+
+    <para>If XVideo is not supported for your card, this only means
+      that it will be more difficult for your display to meet the
+      computational demands of rendering video.  Depending on your
+      video card and processor, though, you might still be able to
+      have a satisfying experience.  You should probably read about
+      ways of improving performance in the advanced reading <xref
+      linkend="video-further-reading">.</para>
+
+    </sect3>
+
+    <sect3 id="video-interface-SDL">
+    <title>Simple Directmedia Layer</title>
+
+    <para>The Simple Directmedia Layer, SDL, was intended to be a
+      porting layer between &microsoft.windows;, BeOS, and &unix;,
+      allowing cross-platform applications to be developed which made
+      efficient use of sound and graphics.  The SDL layer provides a
+      low-level abstraction to the hardware which can sometimes be
+      more efficient than the X11 interface.</para>
+
+    <para>The SDL can be found at <filename role="package">devel/sdl12</filename>.</para>
+
+    </sect3>
+
+    <sect3 id="video-interface-DGA">
+    <title>Direct Graphics Access</title>
+
+    <para>Direct Graphics Access is an X11 extension which allows
+      a program to bypass the X server and directly alter the
+      framebuffer.  Because it relies on a low level memory mapping to
+      effect this sharing, programs using it must be run as
+      <username>root</username>.</para>
+
+    <para>The DGA extension can be tested and benchmarked by
+      &man.dga.1;.  When <command>dga</command> is running, it
+      changes the colors of the display whenever a key is pressed.  To
+      quit, use <keycap>q</keycap>.</para>
+
+    </sect3>
+
+  </sect2>
+
+  <sect2 id="video-ports">
+    <title>Ports and Packages Dealing with Video</title>
+
+    <indexterm><primary>video ports</primary></indexterm>
+    <indexterm><primary>video packages</primary></indexterm>
+
+    <para>This section discusses the software available from the
+      FreeBSD Ports Collection which can be used for video playback.
+      Video playback is a very active area of software development,
+      and the capabilities of various applications are bound to
+      diverge somewhat from the descriptions given here.</para>
+
+    <para>Firstly, it is important to know that many of the video
+      applications which run on FreeBSD were developed as Linux
+      applications.  Many of these applications are still
+      beta-quality.  Some of the problems that you may encounter with
+      video packages on FreeBSD include:</para>
+
+      <orderedlist>
+
+      <listitem>
+        <para>An application cannot playback a file which another
+          application produced.</para>
+      </listitem> 
+
+      <listitem>
+        <para>An application cannot playback a file which the
+          application itself produced.</para>
+      </listitem>
+
+      <listitem>
+        <para>The same application on two different machines,
+          rebuilt on each machine for that machine, plays back the same
+          file differently.</para>
+      </listitem>
+
+      <listitem>
+        <para>A seemingly trivial filter like rescaling of the image
+          size results in very bad artifacts from a buggy rescaling
+          routine.</para>
+      </listitem>
+
+      <listitem>
+        <para>An application frequently dumps core.</para>
+      </listitem>
+
+      <listitem>
+        <para>Documentation is not installed with the port and can be
+          found either on the web or under the port's <filename class='directory'>work</filename>
+          directory.</para>
+      </listitem>
+
+      </orderedlist>
+
+    <para>Many of these applications may also exhibit
+      <quote>Linux-isms</quote>.  That is, there may be
+      issues resulting from the way some standard libraries are
+      implemented in the Linux distributions, or some features of the
+      Linux kernel which have been assumed by the authors of the
+      applications.  These issues are not always noticed and worked around
+      by the port maintainers, which can lead to problems like
+      these:</para>
+       
+      <orderedlist>
+
+      <listitem>
+        <para>The use of <filename>/proc/cpuinfo</filename> to detect
+          processor characteristics.</para>
+      </listitem>
+
+      <listitem>
+        <para>A misuse of threads which causes a program to hang upon
+          completion instead of truly terminating.</para>
+      </listitem>
+
+      <listitem>
+        <para>Software not yet in the FreeBSD Ports Collection
+	  which is commonly used in conjunction with the application.</para>
+      </listitem>
+
+      </orderedlist>
+
+      <para>So far, these application developers have been cooperative with
+        port maintainers to minimize the work-arounds needed for
+        port-ing.</para>
+
+    <sect3 id="video-mplayer">
+      <title>MPlayer</title>
+
+      <para><application>MPlayer</application> is a recently developed and rapidly developing
+        video player.  The goals of the <application>MPlayer</application> team are speed and
+        flexibility on Linux and other Unices.  The project was
+        started when the team founder got fed up with bad playback
+        performance on then available players.  Some would say that
+        the graphical interface has been sacrificed for a streamlined
+        design.  However, once
+        you get used to the command line options and the key-stroke
+        controls, it works very well.</para>
+
+      <sect4 id="video-mplayer-building">
+        <title>Building MPlayer</title>
+        <indexterm><primary>MPlayer</primary>
+	           <secondary>making</secondary></indexterm>
+
+	<para><application>MPlayer</application> resides in <filename
+	  role="package">multimedia/mplayer</filename>.
+	  <application>MPlayer</application> performs a variety of
+	  hardware checks during the build process, resulting in a
+	  binary which will not be portable from one system to
+	  another.  Therefore, it is important to build it from
+	  ports and not to use a binary package.  Additionally, a
+	  number of options can be specified in the <command>make</command>
+	  command line, as described in the <filename>Makefile</filename> and at the start of the build:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mplayer</userinput>
+&prompt.root; <userinput>make</userinput>
+N - O - T - E
+
+Take a careful look into the Makefile in order
+to learn how to tune mplayer towards you personal preferences!
+For example,
+make WITH_GTK1
+builds MPlayer with GTK1-GUI support.
+If you want to use the GUI, you can either install
+/usr/ports/multimedia/mplayer-skins
+or download official skin collections from
+http://www.mplayerhq.hu/homepage/dload.html
+</screen>
+
+	<para>The default port options should be sufficient for most
+	  users.  However, if you need the XviD codec, you have to
+	  specify the <makevar>WITH_XVID</makevar> option in the
+	  command line.  The default DVD device can also be defined
+	  with the <makevar>WITH_DVD_DEVICE</makevar> option, by
+	  default <filename>/dev/acd0</filename> will be used.</para>
+
+        <para>As of this writing, the <application>MPlayer</application> port will build its HTML
+          documentation and two executables,
+          <command>mplayer</command>, and
+          <command>mencoder</command>, which is a tool for
+          re-encoding video.</para>
+
+        <para>The HTML documentation for <application>MPlayer</application> is very informative.
+          If the reader finds the information on video hardware and
+          interfaces in this chapter lacking, the <application>MPlayer</application> documentation
+          is a very thorough supplement.  You should definitely take
+          the time to read the <application>MPlayer</application>
+          documentation if you are looking for information about video
+          support in &unix;.</para>
+
+      </sect4>
+
+      <sect4 id="video-mplayer-using">
+        <title>Using MPlayer</title>
+        <indexterm><primary>MPlayer</primary>
+	           <secondary>use</secondary></indexterm>
+
+        <para>Any user of <application>MPlayer</application> must set up a
+          <filename>.mplayer</filename> subdirectory of her
+          home directory.  To create this necessary subdirectory,
+	  you can type the following:</para>
+
+<screen>&prompt.user; <userinput>cd /usr/ports/multimedia/mplayer</userinput>
+&prompt.user; <userinput>make install-user</userinput></screen>
+
+	<para>The command options for <command>mplayer</command> are
+	  listed in the manual page.  For even more detail there is HTML
+	  documentation.  In this section, we will describe only a few
+	  common uses.</para>
+
+	<para>To play a file, such as
+	  <filename><replaceable>testfile.avi</replaceable></filename>,
+	  through one of the various video interfaces set the
+	  <option>-vo</option> option:</para>
+
+	  <screen>&prompt.user; <userinput>mplayer -vo xv testfile.avi</userinput></screen>
+	  <screen>&prompt.user; <userinput>mplayer -vo sdl testfile.avi</userinput></screen>
+	  <screen>&prompt.user; <userinput>mplayer -vo x11 testfile.avi</userinput></screen>
+	  <screen>&prompt.root; <userinput>mplayer -vo dga testfile.avi</userinput></screen>
+	  <screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' testfile.avi</userinput></screen>
+
+	<para>It is worth trying all of these options, as their relative
+	  performance depends on many factors and will vary significantly
+	  with hardware.</para>
+
+	<para>To play from a DVD, replace the
+	 <filename>testfile.avi</filename> with <option>dvd://<replaceable>N</replaceable> -dvd-device
+	 <replaceable>DEVICE</replaceable></option> where <replaceable>N</replaceable> is
+	 the title number to play and
+	 <filename><replaceable>DEVICE</replaceable></filename> is the
+	 device node for the DVD-ROM.  For example, to play title 3
+	 from <filename>/dev/dvd</filename>:</para>
+
+	<screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen>
+
+	<note>
+	  <para>The default DVD device can be defined during the build
+	    of the <application>MPlayer</application> port via the
+	    <makevar>WITH_DVD_DEVICE</makevar> option.  By default,
+	    this device is <filename>/dev/acd0</filename>.  More
+	    details can be found in the port
+	    <filename>Makefile</filename>.</para>
+	</note>
+
+	<para>To stop, pause, advance and so on, consult the
+	  keybindings, which are output by running <command>mplayer
+	  -h</command> or read the manual page.</para>
+
+        <para>Additional important options for playback are:
+          <option>-fs -zoom</option> which engages the fullscreen mode
+          and <option>-framedrop</option> which helps performance.</para>
+
+	<para>In order for the mplayer command line to not become too
+	  large, the user can create a file
+	  <filename>.mplayer/config</filename> and set default options
+	  there:</para>
+<programlisting>vo=xv
+fs=yes
+zoom=yes</programlisting>
+
+	<para>Finally, <command>mplayer</command> can be used to rip a
+	  DVD title into a <filename>.vob</filename> file.  To dump
+	  out the second title from a DVD, type this:</para>
+
+	  <screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen>
+
+        <para>The output file, <filename>out.vob</filename>, will be
+	  MPEG and can be manipulated by the other packages described
+	  in this section.</para>
+
+      </sect4>
+      <sect4 id="video-mencoder">
+        <title>mencoder</title>
+        <indexterm>
+	  <primary>mencoder</primary>
+	</indexterm>
+
+	<para>Before using
+         <command>mencoder</command> it is a good idea to
+	 familiarize yourself with the options from the HTML
+	 documentation.  There is a manual page, but it is not very
+	 useful without the HTML documentation.  There are innumerable ways to
+	 improve quality, lower bitrate, and change formats, and some
+	 of these tricks may make the difference between good
+	 or bad performance.  Here are a couple of examples to get
+	 you going.  First a simple copy:</para>
+
+	 <screen>&prompt.user; <userinput>mencoder input.avi -oac copy -ovc copy -o output.avi</userinput></screen>
+
+         <para>Improper combinations of command line options can yield
+	 output files that are
+	 unplayable even by <command>mplayer</command>.  Thus, if you
+	 just want to rip to a file, stick to the <option>-dumpfile</option>
+	 in <command>mplayer</command>.</para>
+
+	 <para>To convert <filename>input.avi</filename> to the MPEG4
+	 codec with MPEG3 audio encoding (<filename role="package">audio/lame</filename> is required):</para>
+
+	 <screen>&prompt.user; <userinput>mencoder input.avi -oac mp3lame -lameopts br=192 \
+	 -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi</userinput></screen>
+
+	 <para>This has produced output playable by <command>mplayer</command>
+	 and <command>xine</command>.</para>
+
+	 <para><filename>input.avi</filename> can be replaced with
+	   <option>dvd://1 -dvd-device /dev/dvd</option> and run as
+	   <username>root</username> to re-encode a DVD title
+	   directly.  Since you are likely to be dissatisfied with
+	   your results the first time around, it is recommended you
+	   dump the title to a file and work on the file.</para>
+      </sect4>
+
+    </sect3>
+
+    <sect3 id="video-xine">
+    <title>The xine Video Player</title>
+
+    <para>The <application>xine</application> video player is a project of wide scope aiming not only at being an
+     all in one video solution, but also in producing a reusable base
+     library and a modular executable which can be extended with
+     plugins.  It comes both as a package and as a port, <filename
+     role="package">multimedia/xine</filename>.</para>
+
+    <para>The <application>xine</application> player
+     is still very rough around the edges, but it is clearly off to a
+     good start.  In practice, <application>xine</application> requires either a fast CPU with a
+     fast video card, or support for the XVideo extension.  The GUI is
+     usable, but a bit clumsy.</para>
+
+    <para>As of this writing, there is no input module shipped with
+     <application>xine</application> which will play CSS encoded DVD's.  There are third party
+     builds which do have modules for this built in them, but none
+     of these are in the FreeBSD Ports Collection.</para>
+
+    <para>Compared to <application>MPlayer</application>, <application>xine</application> does more for the user, but at the
+      same time, takes some of the more fine-grained control away from
+      the user.  The <application>xine</application> video player
+      performs best on XVideo interfaces.</para>
+     
+    <para>By default, <application>xine</application> player will
+    start up in a graphical user interface.  The menus can then be
+    used to open a specific file:</para>
+
+      <screen>&prompt.user; <userinput>xine</userinput></screen>
+
+    <para>Alternatively, it may be invoked to play a file immediately
+      without the GUI with the command:</para>
+
+      <screen>&prompt.user; <userinput>xine -g -p mymovie.avi</userinput></screen>
+
+    </sect3>
+
+    <sect3 id="video-ports-transcode">
+    <title>The transcode Utilities</title>
+
+    <para>The software <application>transcode</application> is not a player, but a suite of tools for
+      re-encoding video and audio files.  With <application>transcode</application>, one has the
+      ability to merge video files, repair broken files, using command
+      line tools with <filename>stdin/stdout</filename> stream
+      interfaces.</para>
+
+    <para>A great number of options can be specified during
+      the build from the <filename
+      role="package">multimedia/transcode</filename> port, we recommend the
+      following command line to build
+      <application>transcode</application>:</para>
+
+    <screen>&prompt.root; <userinput>make WITH_OPTIMIZED_CFLAGS=yes WITH_LIBA52=yes WITH_LAME=yes WITH_OGG=yes \
+WITH_MJPEG=yes -DWITH_XVID=yes</userinput></screen>
+
+    <para>The proposed settings should be sufficient for most users.</para>
+
+    <para>To illustrate <command>transcode</command> capacities, one
+      example to show how to convert a DivX file into a PAL MPEG-1
+      file (PAL VCD):</para>
+
+      <screen>&prompt.user; <userinput>transcode -i input.avi -V --export_prof vcd-pal -o output_vcd</userinput>
+&prompt.user; <userinput>mplex -f 1 -o output_vcd.mpg output_vcd.m1v output_vcd.mpa</userinput></screen>
+
+    <para>The resulting MPEG file,
+      <filename>output_vcd.mpg</filename>, is ready to be played with
+      <application>MPlayer</application>.  You could even burn the
+      file on a CD-R media to create a Video CD, in this case you will
+      need to install and use both <filename
+      role="package">multimedia/vcdimager</filename> and <filename
+      role="package">sysutils/cdrdao</filename> programs.</para>
+
+    <para>There is a manual page for <command>transcode</command>, but
+      you should also consult the <ulink
+      url="http://www.transcoding.org/cgi-bin/transcode">transcode
+      wiki</ulink> for further information and examples.</para>
+    </sect3>
+
+  </sect2>
+
+  <sect2 id="video-further-reading">
+    <title>Further Reading</title>
+
+    <para>The various video software packages for FreeBSD are
+      developing rapidly.  It is quite possible that in the near
+      future many of the problems discussed here will have been
+      resolved.  In the mean time, those who
+     want to get the very most out of FreeBSD's A/V capabilities will
+     have to cobble together knowledge from several FAQs and tutorials
+     and use a few different applications.  This section exists to
+      give the reader pointers to such additional information.</para>
+
+    <para>The 
+      <ulink url="http://www.mplayerhq.hu/DOCS/">MPlayer documentation</ulink>
+      is very technically informative.
+      These documents should probably be consulted by anyone wishing
+      to obtain a high level of expertise with &unix; video.  The
+      <application>MPlayer</application> mailing list is hostile to anyone who has not bothered
+      to read the documentation, so if you plan on making bug reports
+      to them, RTFM.</para>
+
+    <para>The
+      <ulink url="http://dvd.sourceforge.net/xine-howto/en_GB/html/howto.html">      xine HOWTO</ulink>
+      contains a chapter on performance improvement
+      which is general to all players.</para>
+
+    <para>Finally, there are some other promising applications which
+    the reader may try:</para>
+
+    <itemizedlist>
+
+       <listitem>
+         <para><ulink
+	   url="http://avifile.sourceforge.net/">Avifile</ulink> which
+	   is also a port <filename
+	   role='package'>multimedia/avifile</filename>.</para>
+       </listitem>
+
+       <listitem>
+         <para><ulink
+	   url="http://www.dtek.chalmers.se/groups/dvd/">Ogle</ulink>
+	   which is also a port <filename
+	   role='package'>multimedia/ogle</filename>.</para>
+       </listitem>
+
+       <listitem>
+         <para><ulink url="http://xtheater.sourceforge.net/">Xtheater</ulink></para>
+       </listitem>
+
+	<listitem>
+         <para><filename
+           role="package">multimedia/dvdauthor</filename>, an open
+           source package for authoring DVD content.</para>
+        </listitem>
+
+    </itemizedlist>
+
+  </sect2>
+ </sect1>
+
+  <sect1 id="tvcard">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Josef</firstname>
+	  <surname>El-Rayes</surname>
+	  <contrib>Original contribution by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Fonvieille</surname>
+	  <contrib>Enhanced and adapted by </contrib>
+	  <!-- 02 January 2004 -->
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Setting Up TV Cards</title>
+    <indexterm>
+      <primary>TV cards</primary>
+    </indexterm>
+
+    <sect2>
+      <title>Introduction</title>
+
+      <para>TV cards allow you to watch broadcast or cable TV on your
+	computer.  Most of them accept composite video via an RCA or
+	S-video input and some of these cards come with a FM
+	radio tuner.</para>
+
+      <para>&os; provides support for PCI-based TV cards using a
+	Brooktree Bt848/849/878/879 or a Conexant CN-878/Fusion 878a
+	Video Capture Chip with the &man.bktr.4; driver.  You must
+	also ensure the board comes with a supported tuner, consult
+	the &man.bktr.4; manual page for a list of supported
+	tuners.</para>
+    </sect2>
+
+    <sect2>
+      <title>Adding the Driver</title>
+
+      <para>To use your card, you will need to load the &man.bktr.4;
+	driver, this can be done by adding the following line to the
+	<filename>/boot/loader.conf</filename> file like this:</para>
+
+      <programlisting>bktr_load="YES"</programlisting>
+
+      <para>Alternatively, you may statically compile the support for
+	the TV card in your kernel, in that case add the following
+	lines to your kernel configuration:</para>
+	
+      <programlisting>device	 bktr
+device	iicbus
+device	iicbb
+device	smbus</programlisting>
+
+      <para>These additional device drivers are necessary because of the
+	card components being interconnected via an I2C bus.  Then build
+	and install a new kernel.</para>
+
+      <para>Once the support was added to your system, you have to
+	reboot your machine.  During the boot process, your TV card
+	should show up, like this:</para>
+
+      <programlisting>bktr0: &lt;BrookTree 848A&gt; mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0
+iicbb0: &lt;I2C bit-banging driver&gt; on bti2c0
+iicbus0: &lt;Philips I2C bus&gt; on iicbb0 master-only
+iicbus1: &lt;Philips I2C bus&gt; on iicbb0 master-only
+smbus0: &lt;System Management Bus&gt; on bti2c0
+bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting>
+
+      <para>Of course these messages can differ according to your
+	hardware.  However you should check if the tuner is correctly
+	detected; it is still possible to override some of the
+	detected parameters with &man.sysctl.8; MIBs and kernel
+	configuration file options.  For example, if you want to force
+	the tuner to a Philips SECAM tuner, you should add the
+	following line to your kernel configuration file:</para>
+
+      <programlisting>options OVERRIDE_TUNER=6</programlisting>
+
+      <para>or you can directly use &man.sysctl.8;:</para>
+
+      <screen>&prompt.root; <userinput>sysctl hw.bt848.tuner=6</userinput></screen>
+
+      <para>See the &man.bktr.4; manual page and the
+	<filename>/usr/src/sys/conf/NOTES</filename> file for more
+	details on the available options.</para>
+    </sect2>
+
+    <sect2>
+      <title>Useful Applications</title>
+
+      <para>To use your TV card you need to install one of the
+	following applications:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><filename role="package">multimedia/fxtv</filename>
+	    provides TV-in-a-window and image/audio/video capture
+	    capabilities.</para>
+	</listitem>
+	<listitem>
+	  <para><filename role="package">multimedia/xawtv</filename>
+	    is also a TV application, with the same features as
+	    <application>fxtv</application>.</para>
+	</listitem>
+	<listitem>
+	  <para><filename role="package">misc/alevt</filename> decodes
+	    and displays Videotext/Teletext.</para>
+	</listitem>
+	<listitem>
+	  <para><filename role="package">audio/xmradio</filename>, an
+	    application to use the FM radio tuner coming with some
+	    TV cards.</para>
+	</listitem>
+	<listitem>
+	  <para><filename role="package">audio/wmtune</filename>, a handy
+	    desktop application for radio tuners.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>More applications are available in the &os; Ports
+	Collection.</para>
+    </sect2>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <para>If you encounter any problem with your TV card, you should
+	check at first if the video capture chip and the tuner are
+	really supported by the &man.bktr.4; driver and if you used the right
+	configuration options.  For more support and various questions
+	about your TV card you may want to contact and use the
+	archives of the &a.multimedia.name; mailing list.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="scanners">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Marc</firstname>
+	  <surname>Fonvieille</surname>
+	  <contrib>Written by </contrib>
+	  <!-- 04 August 2004 -->
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Image Scanners</title>
+    <indexterm>
+      <primary>image scanners</primary>
+    </indexterm>
+
+    <sect2>
+      <title>Introduction</title>
+
+      <para>&os;, like any modern operating system, allows the use of
+	image scanners.  Standardized access to scanners is provided
+	by the <application>SANE</application> (Scanner Access Now
+	Easy) <acronym role="Application Programming
+	Interface">API</acronym> available through the &os; Ports
+	Collection.  <application>SANE</application> will also use
+	some &os; devices drivers to access to the scanner
+	hardware.</para>
+
+      <para>&os; supports both SCSI and USB scanners.  Be sure your
+	scanner is supported by <application>SANE</application> prior
+	to performing any configuration.
+	<application>SANE</application> has a <ulink
+	url="http://sane-project.org/sane-supported-devices.html">supported
+	devices</ulink> list that can provide you with information
+	about the support for a scanner and its status.  The
+	&man.uscanner.4; manual page also provides a list of supported
+	USB scanners.</para>
+    </sect2>
+
+    <sect2>
+      <title>Kernel Configuration</title>
+
+      <para>As mentioned above both SCSI and USB interfaces are
+	supported.  According to your scanner interface, different
+	device drivers are required.</para>
+
+      <sect3 id="scanners-kernel-usb">
+	<title>USB Interface</title>
+
+	<para>The <filename>GENERIC</filename> kernel by default
+	  includes the device drivers needed to support USB scanners.
+	  Should you decide to use a custom kernel, be sure that the
+	  following lines are present in your kernel configuration
+	  file:</para>
+
+	<programlisting>device usb
+device uhci
+device ohci
+device uscanner</programlisting>
+
+	<para>Depending upon the USB chipset on your motherboard, you
+	  will only need either <literal>device uhci</literal> or
+	  <literal>device ohci</literal>, however having both in the
+	  kernel configuration file is harmless.</para>
+
+	<para>If you do not want to rebuild your kernel and your
+	  kernel is not the <filename>GENERIC</filename> one, you can
+	  directly load the &man.uscanner.4; device driver module with
+	  the &man.kldload.8; command:</para>
+
+	<screen>&prompt.root; <userinput>kldload uscanner</userinput></screen>
+
+	<para>To load this module at each system startup, add the
+	  following line to
+	  <filename>/boot/loader.conf</filename>:</para>
+
+	<programlisting>uscanner_load="YES"</programlisting>
+
+	<para>After rebooting with the correct kernel, or after
+	  loading the required module, plug in your USB scanner.  The
+	  scanner should appear in your system message buffer
+	  (&man.dmesg.8;) as something like:</para>
+
+	<screen>uscanner0: EPSON EPSON Scanner, rev 1.10/3.02, addr 2</screen>
+
+	<para>This shows that our scanner is using the
+	  <filename>/dev/uscanner0</filename> device node.</para>
+      </sect3>
+
+      <sect3>
+	<title>SCSI Interface</title>
+
+	<para>If your scanner comes with a SCSI interface, it is
+	  important to know which SCSI controller board you will use.
+	  According to the SCSI chipset used, you will have to tune
+	  your kernel configuration file.  The
+	  <filename>GENERIC</filename> kernel supports the most common
+	  SCSI controllers.  Be sure to read the
+	  <filename>NOTES</filename> file
+	  and add the correct line to your kernel
+	  configuration file.  In addition to the SCSI adapter driver,
+	  you need to have the following lines in your kernel
+	  configuration file:</para>
+
+	<programlisting>device scbus
+device pass</programlisting>
+
+	<para>Once your kernel has been properly compiled, you should
+	  be able to see the devices in your system message buffer,
+	  when booting:</para>
+
+	<screen>pass2 at aic0 bus 0 target 2 lun 0
+pass2: &lt;AGFA SNAPSCAN 600 1.10&gt; Fixed Scanner SCSI-2 device
+pass2: 3.300MB/s transfers</screen>
+
+	<para>If your scanner was not powered-on at system boot, it is
+	  still possible to manually force the detection by performing
+	  a SCSI bus scan with the &man.camcontrol.8; command:</para>
+
+	<screen>&prompt.root; <userinput>camcontrol rescan all</userinput>
+Re-scan of bus 0 was successful
+Re-scan of bus 1 was successful
+Re-scan of bus 2 was successful
+Re-scan of bus 3 was successful</screen>
+
+	<para>Then the scanner will appear in the SCSI devices
+	  list:</para>
+
+	<screen>&prompt.root; <userinput>camcontrol devlist</userinput>
+&lt;IBM DDRS-34560 S97B&gt;              at scbus0 target 5 lun 0 (pass0,da0)
+&lt;IBM DDRS-34560 S97B&gt;              at scbus0 target 6 lun 0 (pass1,da1)
+&lt;AGFA SNAPSCAN 600 1.10&gt;           at scbus1 target 2 lun 0 (pass3)
+&lt;PHILIPS CDD3610 CD-R/RW 1.00&gt;     at scbus2 target 0 lun 0 (pass2,cd0)</screen>
+
+	<para>More details about SCSI devices, are available in the
+	  &man.scsi.4; and &man.camcontrol.8; manual pages.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>SANE Configuration</title>
+
+      <para>The <application>SANE</application> system has been
+	splitted in two parts: the backends (<filename
+	role="package">graphics/sane-backends</filename>) and the
+	frontends (<filename
+	role="package">graphics/sane-frontends</filename>).  The
+	backends part provides access to the scanner itself.  The
+	<application>SANE</application>'s <ulink
+	url="http://sane-project.org/sane-supported-devices.html">supported
+	devices</ulink> list specifies which backend will support your
+	image scanner.  It is mandatory to determine the correct
+	backend for your scanner if you want to be able to use your
+	device.  The frontends part provides the graphical scanning
+	interface (<application>xscanimage</application>).</para>
+
+      <para>The first thing to do is install the <filename
+	role="package">graphics/sane-backends</filename> port or
+	package.  Then, use the <command>sane-find-scanner</command>
+	command to check the scanner detection by the
+	<application>SANE</application> system:</para>
+
+      <screen>&prompt.root; <userinput>sane-find-scanner -q</userinput>
+found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3</screen>
+
+      <para>The output will show the interface type of the scanner and
+	the device node used to attach the scanner to the system.  The
+	vendor and the product model may not appear, it is not
+	important.</para>
+
+      <note>
+	<para>Some USB scanners require you to load a firmware, this
+	  is explained in the backend manual page.  You should also read
+	  &man.sane-find-scanner.1; and &man.sane.7; manual
+	  pages.</para>
+      </note>
+
+      <para>Now we have to check if the scanner will be identified by
+	a scanning frontend.  By default, the
+	<application>SANE</application> backends comes with a command
+	line tool called &man.scanimage.1;.  This command allows you
+	to list the devices and to perform an image acquisition from
+	the command line.  The <option>-L</option> option is used to
+	list the scanner device:</para>
+
+      <screen>&prompt.root; <userinput>scanimage -L</userinput>
+device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner</screen>
+
+      <para>No output or a message saying that no scanners were
+	identified indicates that &man.scanimage.1; is unable to
+	identify the scanner.  If this happens, you will need to edit
+	the backend configuration file and define the scanner device
+	used.  The <filename
+	class="directory">/usr/local/etc/sane.d/</filename> directory
+	contains all backends configuration files.  This
+	identification problem does appear with certain USB
+	scanners.</para>
+
+      <para>For example, with the USB scanner used in the <xref
+	linkend="scanners-kernel-usb">,
+	<command>sane-find-scanner</command> gives us the following
+	information:</para>
+
+      <screen>&prompt.root; <userinput>sane-find-scanner -q</userinput>
+found USB scanner (UNKNOWN vendor and product) at device /dev/uscanner0</screen>
+      <para>The scanner is correctly detected, it uses the USB
+	interface and is attached to the
+	<filename>/dev/uscanner0</filename> device node.  We can now
+	check if the scanner is correctly identified:</para>
+
+      <screen>&prompt.root; <userinput>scanimage -L</userinput>
+
+No scanners were identified. If you were expecting something different,
+check that the scanner is plugged in, turned on and detected by the
+sane-find-scanner tool (if appropriate). Please read the documentation
+which came with this software (README, FAQ, manpages).</screen>
+
+      <para>Since the scanner is not identified, we will need to edit
+	the <filename>/usr/local/etc/sane.d/epson.conf</filename>
+	file.  The scanner model used was the &epson.perfection; 1650,
+	so we know the scanner will use the <literal>epson</literal>
+	backend.  Be sure to read the help comments in the backends
+	configuration files.  Line changes are quite simple: comment
+	out all lines that have the wrong interface for your scanner
+	(in our case, we will comment out all lines starting with the
+	word <literal>scsi</literal> as our scanner uses the USB
+	interface), then add at the end of the file a line specifying
+	the interface and the device node used.  In this case, we add
+	the following line:</para>
+
+      <programlisting>usb /dev/uscanner0</programlisting>
+
+      <para>Please be sure to read the comments provided in the
+	backend configuration file as well as the backend manual page
+	for more details and correct syntax to use.  We can now verify
+	if the scanner is identified:</para>
+
+      <screen>&prompt.root; <userinput>scanimage -L</userinput>
+device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen>
+
+      <para>Our USB scanner has been identified.  It is not important
+	if the brand and the model do not match.  The key item to be
+	concerned with is the
+	<literal>`epson:/dev/uscanner0'</literal> field, which give us
+	the right backend name and the right device node.</para>
+
+      <para>Once the <command>scanimage -L</command> command is able
+	to see the scanner, the configuration is complete.  The device
+	is now ready to scan.</para>
+
+      <para>While &man.scanimage.1; does allow us to perform an
+	image acquisition from the command line, it is preferable to
+	use a graphical user interface to perform image scanning.
+	<application>SANE</application> offers a simple but efficient
+	graphical interface: <application>xscanimage</application>
+	(<filename
+	role="package">graphics/sane-frontends</filename>).</para>
+
+      <para><application>Xsane</application> (<filename
+	role="package">graphics/xsane</filename>) is another popular
+	graphical scanning frontend.  This frontend offers advanced
+	features such as various scanning mode (photocopy, fax, etc.),
+	color correction, batch scans, etc.  Both of these applications
+	are useable as a <application>GIMP</application>
+	plugin.</para>
+    </sect2>
+
+    <sect2>
+      <title>Allowing Scanner Access to Other Users</title>
+
+      <para>All previous operations have been done with
+	<username>root</username> privileges.  You may however, need
+	other users to have access
+	to the scanner.  The user will need read and write
+	permissions to the device node used by the scanner.  As an
+	example, our USB scanner uses the device node
+	<filename>/dev/uscanner0</filename> which is owned by the
+	<groupname>operator</groupname> group.  Adding the user
+	<username>joe</username> to the
+	<groupname>operator</groupname> group will allow him to use
+	the scanner:</para>
+
+      <screen>&prompt.root; <userinput>pw groupmod operator -m <replaceable>joe</replaceable></userinput></screen>
+
+      <para>For more details read the &man.pw.8; manual page.  You
+	also have to set the correct write permissions (0660 or 0664)
+	on the <filename>/dev/uscanner0</filename> device node, by
+	default the <groupname>operator</groupname> group can only
+	read the device node.  This is done by adding the following
+	lines to the <filename>/etc/devfs.rules</filename> file:</para>
+
+      <programlisting>[system=5]
+add path uscanner0 mode 660</programlisting>
+
+      <para>Then add the following to
+	<filename>/etc/rc.conf</filename> and reboot the
+	machine:</para>
+
+      <programlisting>devfs_system_ruleset="system"</programlisting>
+
+      <para>More information regarding these lines can be found in the
+	&man.devfs.8; manual page.</para>
+
+      <note>
+	<para>Of course, for security reasons, you should think twice
+	  before adding a user to any group, especially the
+	  <groupname>operator</groupname> group.</para>
+      </note>
+    </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/pl_PL.ISO8859-2/books/handbook/network-servers/Makefile b/pl_PL.ISO8859-2/books/handbook/network-servers/Makefile
new file mode 100644
index 0000000000..150dbe3121
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/network-servers/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	network-servers/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/network-servers/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/network-servers/chapter.sgml
new file mode 100644
index 0000000000..2013b83364
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/network-servers/chapter.sgml
@@ -0,0 +1,4764 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="network-servers">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+        <firstname>Murray</firstname>
+	<surname>Stokely</surname>
+	<contrib>Reorganized by </contrib>
+      </author>
+    </authorgroup>
+    <!-- 23 July 2004 -->
+  </chapterinfo>
+
+  <title>Network Servers</title>
+
+  <sect1 id="network-servers-synopsis">
+    <title>Synopsis</title>
+
+    <para>This chapter will cover some of the more frequently used
+      network services on &unix; systems.  We will cover how to
+      install, configure, test, and maintain many different types of
+      network services.  Example configuration files are included
+      throughout this chapter for you to benefit from.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+
+      <listitem>
+	<para>How to manage the <application>inetd</application>
+	  daemon.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up a network file system.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up a network information server for sharing
+	  user accounts.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up automatic network settings using DHCP.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up a domain name server.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up the <application>Apache</application> HTTP Server.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up a File Transfer Protocol (FTP) Server.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up a file and print server for &windows;
+	  clients using <application>Samba</application>.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to synchronize the time and date, and set up a
+	  time server, with the NTP protocol.</para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand the basics of the
+	  <filename>/etc/rc</filename> scripts.</para>
+      </listitem>
+
+      <listitem>
+	<para>Be familiar with basic network terminology.</para>
+      </listitem>
+
+      <listitem>
+      <para>Know how to install additional third-party
+        software (<xref linkend="ports">).</para>
+      </listitem>
+
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="network-inetd">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Chern</firstname>
+          <surname>Lee</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <contrib>Updated for &os; 6.1-RELEASE by </contrib>
+	  <othername>The &os; Documentation Project</othername>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title>The <application>inetd</application> <quote>Super-Server</quote></title>
+
+    <sect2 id="network-inetd-overview">
+      <title>Overview</title>
+
+      <para>&man.inetd.8; is sometimes referred to as the <quote>Internet
+	Super-Server</quote> because it manages connections for
+	several services.  When a
+	connection is received by <application>inetd</application>, it
+	determines which program the connection is destined for, spawns
+	the particular process and delegates the socket to it (the program
+	is invoked with the service socket as its standard input, output
+	and error descriptors).  Running
+	<application>inetd</application> for servers that are not heavily used can reduce the
+	overall system load, when compared to running each daemon
+	individually in stand-alone mode.</para>
+
+      <para>Primarily, <application>inetd</application> is used to
+	spawn other daemons, but several trivial protocols are handled
+	directly, such as <application>chargen</application>,
+	<application>auth</application>, and
+	<application>daytime</application>.</para>
+
+      <para>This section will cover the basics in configuring
+	<application>inetd</application> through its command-line
+	options and its configuration file,
+	<filename>/etc/inetd.conf</filename>.</para>
+    </sect2>
+
+    <sect2 id="network-inetd-settings">
+      <title>Settings</title>
+
+      <para><application>inetd</application> is initialized through
+	the &man.rc.8; system.  The
+	<literal>inetd_enable</literal> option is set to
+	<literal>NO</literal> by default, but may be turned on
+	by <application>sysinstall</application> during installation,
+	depending on the configuration chosen by the user.
+	Placing:
+	<programlisting>inetd_enable="YES"</programlisting> or
+	<programlisting>inetd_enable="NO"</programlisting> into
+	<filename>/etc/rc.conf</filename> will enable or disable
+	<application>inetd</application> starting at boot time.
+	The command:
+	<programlisting>/etc/rc.d/inetd rcvar</programlisting>
+	can be run to display the current effective setting.</para>
+
+      <para>Additionally, different command-line options can be passed
+	to <application>inetd</application> via the
+	<literal>inetd_flags</literal> option.</para>
+    </sect2>
+
+    <sect2 id="network-inetd-cmdline">
+      <title>Command-Line Options</title>
+
+      <para>Like most server daemons, <application>inetd</application>
+	has a number of options that it can be passed in order to
+	modify its behaviour.  The full list of options reads:</para>
+
+      <para><command>inetd</command> <option>[-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
+           [-p filename] [-R rate] [-s maximum] [configuration file]</option></para>
+
+      <para>Options can be passed to <application>inetd</application> using the
+	<literal>inetd_flags</literal> option in
+	<filename>/etc/rc.conf</filename>.  By default,
+	<literal>inetd_flags</literal> is set to
+	<literal>-wW -C 60</literal>, which turns on TCP wrapping for
+	<application>inetd</application>'s services, and prevents any
+	single IP address from requesting any service more than 60 times
+	in any given minute.</para>
+
+      <para>Novice users may be pleased to note that
+	these parameters usually do not need to be modified,
+	although we mention the rate-limiting options below as
+	they be useful should you find that you are receiving an
+	excessive amount of connections.  A full list of options
+	can be found in the &man.inetd.8; manual.</para>
+
+      <variablelist>
+	<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>-s maximum</term>
+
+	  <listitem>
+	    <para>Specify the maximum number of times a service can be
+	      invoked from a single IP address at any one time; the
+	      default is unlimited.  May be overridden on a per-service
+	      basis with the <option>max-child-per-ip</option>
+	      parameter.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2 id="network-inetd-conf">
+      <!-- XXX This section isn't very clear, and could do with some lovin' -->
+      <title><filename>inetd.conf</filename></title>
+
+      <para>Configuration of <application>inetd</application> is
+	done via the file <filename>/etc/inetd.conf</filename>.</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 running the command:</para>
+
+      <example id="network-inetd-reread">
+	<title>Reloading the <application>inetd</application>
+	  configuration file</title>
+
+	<screen>&prompt.root; <userinput>/etc/rc.d/inetd reload</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 each entry in
+	<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[/max-child-per-ip]]]
+user[:group][/login-class]
+server-program
+server-program-arguments</programlisting>
+
+      <para>An example entry for the &man.ftpd.8; daemon
+	using IPv4 might read:</para>
+
+      <programlisting>ftp     stream  tcp     nowait  root    /usr/libexec/ftpd       ftpd -l</programlisting>
+
+      <variablelist>
+	<varlistentry>
+	  <term>service-name</term>
+
+	  <listitem>
+	    <para>This is the service name of the particular daemon.
+	      It must correspond to a service listed in
+	      <filename>/etc/services</filename>.  This determines
+	      which port <application>inetd</application> must listen
+	      to.  If a new service is being created, it must be
+	      placed in <filename>/etc/services</filename>
+	      first.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>socket-type</term>
+
+	  <listitem>
+	    <para>Either <literal>stream</literal>,
+	      <literal>dgram</literal>, <literal>raw</literal>, or
+	      <literal>seqpacket</literal>.  <literal>stream</literal>
+	      must be used for connection-based, TCP daemons, while
+	      <literal>dgram</literal> is used for daemons utilizing
+	      the <acronym>UDP</acronym> transport protocol.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>protocol</term>
+
+	  <listitem>
+	    <para>One of the following:</para>
+
+	    <informaltable frame="none" pgwide="1">
+	      <tgroup cols="2">
+		<thead>
+		  <row>
+		    <entry>Protocol</entry>
+		    <entry>Explanation</entry>
+		  </row>
+		</thead>
+		<tbody>
+		  <row>
+		    <entry>tcp, tcp4</entry>
+		    <entry>TCP IPv4</entry>
+		  </row>
+		  <row>
+		    <entry>udp, udp4</entry>
+		    <entry>UDP IPv4</entry>
+		  </row>
+		  <row>
+		    <entry>tcp6</entry>
+		    <entry>TCP IPv6</entry>
+		  </row>
+		  <row>
+		    <entry>udp6</entry>
+		    <entry>UDP IPv6</entry>
+		  </row>
+		  <row>
+		    <entry>tcp46</entry>
+		    <entry>Both TCP IPv4 and v6</entry>
+		  </row>
+		  <row>
+		    <entry>udp46</entry>
+		    <entry>Both UDP IPv4 and v6</entry>
+		  </row>
+		</tbody>
+	      </tgroup>
+	    </informaltable>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]]</term>
+
+	  <listitem>
+	    <para><option>wait|nowait</option> indicates whether the
+	      daemon invoked from <application>inetd</application> is
+	      able to handle its own socket or not.
+	      <option>dgram</option> socket types must use the
+	      <option>wait</option> option, while stream socket
+	      daemons, which are usually multi-threaded, should use
+	      <option>nowait</option>.  <option>wait</option> usually
+	      hands off multiple sockets to a single daemon, while
+	      <option>nowait</option> spawns a child daemon for each
+	      new socket.</para>
+
+	    <para>The maximum number of child daemons
+	      <application>inetd</application> may spawn can be set
+	      using the <option>max-child</option> option.  If a limit
+	      of ten instances of a particular daemon is needed, a
+	      <literal>/10</literal> would be placed after
+	      <option>nowait</option>.  Specifying <literal>/0</literal>
+	      allows an unlimited number of children</para>
+
+	    <para>In addition to <option>max-child</option>, two other
+	      options which limit the maximum connections from a single
+	      place to a particular daemon can be enabled.
+	      <option>max-connections-per-ip-per-minute</option> limits
+	      the number of connections from any particular IP address
+	      per minutes, e.g. a value of ten would limit any particular
+	      IP address connecting to a particular service to ten
+	      attempts per minute.  <option>max-child-per-ip</option>
+	      limits the number of children that can be started on
+	      behalf on any single IP address at any moment. These
+	      options are useful to prevent intentional or unintentional
+ 	      excessive resource consumption and Denial of Service (DoS)
+	      attacks to a machine.</para>
+
+	    <para>In this field, either of <option>wait</option> or
+	      <option>nowait</option> is mandatory.
+	      <option>max-child</option>,
+	      <option>max-connections-per-ip-per-minute</option> and
+	      <option>max-child-per-ip</option> are
+	      optional.</para>
+
+	    <para>A stream-type multi-threaded daemon without any
+	      <option>max-child</option>,
+	      <option>max-connections-per-ip-per-minute</option> or
+	      <option>max-child-per-ip</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>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 utilized by the default
+	      settings of the &man.fingerd.8; daemon,
+	      as seen here:</para>
+
+	    <programlisting>finger stream  tcp     nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting>
+
+	    <para>Finally, an example of this field with a maximum of
+	      100 children in total, with a maximum of 5 for any one
+	      IP address would read:
+	      <literal>nowait/100/0/5</literal>.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>user</term>
+
+	  <listitem>
+	    <para>This is the username that the particular daemon
+	      should run as.  Most commonly, daemons run as the
+	      <username>root</username> user.  For security purposes, it is
+	      common to find some servers running as the
+	      <username>daemon</username> user, or the least privileged
+	      <username>nobody</username> user.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>server-program</term>
+
+	  <listitem>
+	    <para>The full path of the daemon to be executed when a
+	      connection is received.  If the daemon is a service
+	      provided by <application>inetd</application> internally,
+	      then <option>internal</option> should be
+	      used.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>server-program-arguments</term>
+
+	  <listitem>
+	    <para>This works in conjunction with
+	      <option>server-program</option> by specifying the
+	      arguments, starting with <literal>argv[0]</literal>,
+	      passed to the daemon on invocation.  If
+	      <command>mydaemon -d</command> is the command line,
+	      <literal>mydaemon -d</literal> would be the value of
+	      <option>server-program-arguments</option>.  Again, if
+	      the daemon is an internal service, use
+	      <option>internal</option> here.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2 id="network-inetd-security">
+      <title>Security</title>
+
+      <para>Depending on the choices made at install time, many
+	of <application>inetd</application>'s services may be enabled
+	by default.  If there is no apparent need for a particular
+	daemon, consider disabling it.  Place a <quote>#</quote> in front of the
+	daemon in question in <filename>/etc/inetd.conf</filename>,
+	and then <link linkend="network-inetd-reread">reload the
+	inetd configuration</link>.  Some daemons, such as
+	<application>fingerd</application>, may not be desired at all
+	because they provide
+	information that may be useful to an attacker.</para>
+
+      <para>Some daemons are not security-conscious and have long, or
+	non-existent, timeouts for connection attempts.  This allows an
+	attacker to slowly send connections to a particular daemon,
+	thus saturating available resources.  It may be a good idea to
+	place <option>max-connections-per-ip-per-minute</option>,
+	<option>max-child</option> or <option>max-child-per-ip</option> limitations on certain
+	daemons if you find that you have too many connections.</para>
+
+      <para>By default, TCP wrapping is turned on.  Consult the
+	&man.hosts.access.5; manual page for more information on placing
+	TCP restrictions on various <application>inetd</application>
+	invoked daemons.</para>
+    </sect2>
+
+    <sect2 id="network-inetd-misc">
+      <title>Miscellaneous</title>
+
+      <para><application>daytime</application>,
+	<application>time</application>,
+	<application>echo</application>,
+	<application>discard</application>,
+	<application>chargen</application>, and
+	<application>auth</application> are all internally provided
+	services of <application>inetd</application>.</para>
+
+      <para>The <application>auth</application> service provides
+	identity
+	network services, and is
+	configurable to a certain degree, whilst the others are simply on or off.</para>
+
+      <para>Consult the &man.inetd.8; manual page for more in-depth
+	information.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-nfs">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Tom</firstname>
+          <surname>Rhodes</surname>
+          <contrib>Reorganized and enhanced by </contrib>
+        </author>
+      </authorgroup>
+      <authorgroup>
+        <author>
+          <firstname>Bill</firstname>
+      	  <surname>Swingle</surname>
+	  <contrib>Written by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>Network File System (NFS)</title>
+
+    <indexterm><primary>NFS</primary></indexterm>
+    <para>Among the many different file systems that FreeBSD supports
+      is the Network File System, also known as <acronym role="Network
+      File System">NFS</acronym>.  <acronym role="Network File
+      System">NFS</acronym> allows a system to share directories and
+      files with others over a network.  By using <acronym
+      role="Network File System">NFS</acronym>, users and programs can
+      access files on remote systems almost as if they were local
+      files.</para>
+
+    <para>Some of the most notable benefits that
+      <acronym>NFS</acronym> can provide are:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Local workstations use less disk space because commonly
+	  used data can be stored on a single machine and still remain
+	  accessible to others over the network.</para>
+      </listitem>
+
+      <listitem>
+	<para>There is no need for users to have separate home
+	  directories on every network machine.  Home directories
+	  could be set up on the <acronym>NFS</acronym> server and
+	  made available throughout the network.</para>
+      </listitem>
+
+      <listitem>
+	<para>Storage devices such as floppy disks, CDROM drives, and
+	  &iomegazip; drives can be used by other machines on the network.
+	  This may reduce the number of removable media drives
+	  throughout the network.</para>
+      </listitem>
+    </itemizedlist>
+
+    <sect2>
+      <title>How <acronym>NFS</acronym> Works</title>
+
+      <para><acronym>NFS</acronym> consists of at least two main
+        parts: a server and one or more clients.  The client remotely
+        accesses the data that is stored on the server machine.  In
+        order for this to function properly a few processes have to be
+        configured and running.</para>
+
+      <para>The server has to be running the following daemons:</para>
+      <indexterm>
+        <primary>NFS</primary>
+        <secondary>server</secondary>
+      </indexterm>
+      <indexterm>
+        <primary>file server</primary>
+        <secondary>UNIX clients</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary><application>rpcbind</application></primary>
+      </indexterm>
+      <indexterm>
+        <primary><application>mountd</application></primary>
+      </indexterm>
+      <indexterm>
+        <primary><application>nfsd</application></primary>
+      </indexterm>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <colspec colwidth="1*">
+	  <colspec colwidth="3*">
+
+	  <thead>
+	    <row>
+	      <entry>Daemon</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry><application>nfsd</application></entry>
+	      <entry>The <acronym>NFS</acronym> daemon which services
+	      requests from the <acronym>NFS</acronym>
+	      clients.</entry>
+	    </row>
+	    <row>
+	      <entry><application>mountd</application></entry>
+	      <entry>The <acronym>NFS</acronym> mount daemon which carries out
+		the requests that &man.nfsd.8; passes on to it.</entry>
+	    </row>
+	    <row>
+	      <entry><application>rpcbind</application></entry>
+	      <entry> This daemon allows
+	      <acronym>NFS</acronym> clients to discover which port
+	      the <acronym>NFS</acronym> server is using.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para>The client can also run a daemon, known as
+        <application>nfsiod</application>.  The
+        <application>nfsiod</application> daemon services the requests
+        from the <acronym>NFS</acronym> server.  This is optional, and
+        improves performance, but is not required for normal and
+        correct operation.  See the &man.nfsiod.8; manual page for
+        more information.
+      </para>
+    </sect2>
+
+    <sect2 id="network-configuring-nfs">
+      <title>Configuring <acronym>NFS</acronym></title>
+      <indexterm>
+        <primary>NFS</primary>
+        <secondary>configuration</secondary>
+      </indexterm>
+
+      <para><acronym>NFS</acronym> configuration is a relatively
+        straightforward process.  The processes that need to be
+        running can all start at boot time with a few modifications to
+        your <filename>/etc/rc.conf</filename> file.</para>
+
+      <para>On the <acronym>NFS</acronym> server, make sure that the
+        following options are configured in the
+        <filename>/etc/rc.conf</filename> file:</para>
+
+      <programlisting>rpcbind_enable="YES"
+nfs_server_enable="YES"
+mountd_flags="-r"</programlisting>
+
+      <para><application>mountd</application> runs automatically
+        whenever the <acronym>NFS</acronym> server is enabled.</para>
+
+      <para>On the client, make sure this option is present in
+        <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>nfs_client_enable="YES"</programlisting>
+
+      <para>The <filename>/etc/exports</filename> file specifies which
+        file systems <acronym>NFS</acronym> should export (sometimes
+        referred to as <quote>share</quote>).  Each line in
+        <filename>/etc/exports</filename> specifies a file system to be
+        exported and which machines have access to that file system.
+        Along with what machines have access to that file system,
+        access options may also be specified.  There are many such
+        options that can be used in this file but only a few will be
+        mentioned here.  You can easily discover other options by
+        reading over the &man.exports.5; manual page.</para>
+
+      <para>Here are a few example <filename>/etc/exports</filename>
+	entries:</para>
+
+      <indexterm>
+        <primary>NFS</primary>
+        <secondary>export examples</secondary>
+      </indexterm>
+
+      <para>The following examples give an idea of how to export
+        file systems, although the settings may be different depending
+        on your environment and network configuration.  For instance,
+        to export the <filename>/cdrom</filename> directory to three
+        example machines that have the same domain name as the server
+        (hence the lack of a domain name for each) or have entries in
+        your <filename>/etc/hosts</filename> file.  The
+        <option>-ro</option> flag makes the exported file system
+        read-only.  With this flag, the remote system will not be able
+        to write any changes to the exported file system.</para>
+
+      <programlisting>/cdrom -ro host1 host2 host3</programlisting>
+
+      <para>The following line exports <filename>/home</filename> to
+	three hosts by IP address.  This is a useful setup if you have
+	a private network without a <acronym>DNS</acronym> server
+	configured.  Optionally the <filename>/etc/hosts</filename>
+	file could be configured for internal hostnames; please review
+	&man.hosts.5; for more information.  The
+	<option>-alldirs</option> flag allows the subdirectories to be
+	mount points.  In other words, it will not mount the
+	subdirectories but permit the client to mount only the
+	directories that are required or needed.</para>
+
+      <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
+
+      <para>The following line exports <filename>/a</filename> so that
+	two clients from different domains may access the file system.
+	The <option>-maproot=root</option> flag allows the
+	<username>root</username> user on the remote system to write
+	data on the exported file system as <username>root</username>.
+	If the <literal>-maproot=root</literal> flag is not specified,
+	then even if a user has <username>root</username> access on
+	the remote system, he will not be able to modify files on
+	the exported file system.</para>
+
+      <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
+
+      <para>In order for a client to access an exported file system,
+	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 file system to one host.  A
+	remote host can only be specified once per file system, and may
+	only have one default entry.  For example, assume that
+	<filename>/usr</filename> is a single file system.  The
+	following <filename>/etc/exports</filename> would be
+	invalid:</para>
+
+      <programlisting># Invalid when /usr is one file system
+/usr/src   client
+/usr/ports client</programlisting>
+
+      <para>One file system, <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 file system 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
+	file systems, 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 file systems:</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>The <application>mountd</application> daemon must be forced to
+	recheck the <filename>/etc/exports</filename> file whenever it has
+	been modified, so the changes can take effect.  This can be
+	accomplished either by sending a HUP signal to the running daemon:</para>
+
+      <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
+
+      <para>or by invoking the <command>mountd</command> &man.rc.8; script
+        with the appropriate parameter:</para>
+
+      <screen>&prompt.root; <userinput>/etc/rc.d/mountd reload</userinput></screen>
+
+      <para>Please refer to <xref linkend="configtuning-rcd"> for more
+	information about using rc scripts.</para>
+
+      <para>Alternatively, a reboot will make FreeBSD set everything
+        up properly.  A reboot is not necessary though.
+        Executing the following commands as <username>root</username>
+        should start everything up.</para>
+
+      <para>On the <acronym>NFS</acronym> server:</para>
+
+      <screen>&prompt.root; <userinput>rpcbind</userinput>
+&prompt.root; <userinput>nfsd -u -t -n 4</userinput>
+&prompt.root; <userinput>mountd -r</userinput></screen>
+
+      <para>On the <acronym>NFS</acronym> client:</para>
+
+      <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>
+
+      <para>Now everything should be ready to actually mount a remote file
+	system.  In these examples the
+	server's name will be <hostid>server</hostid> and the client's
+	name will be <hostid>client</hostid>.  If you only want to
+	temporarily mount a remote file system or would rather test the
+	configuration, just execute a command like this as <username>root</username> on the
+        client:</para>
+      <indexterm>
+        <primary>NFS</primary>
+        <secondary>mounting</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 file system
+	each time the computer boots, add the file system to the
+	<filename>/etc/fstab</filename> file.  Here is an example:</para>
+
+      <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
+
+      <para>The &man.fstab.5; manual page lists all the available
+        options.</para>
+    </sect2>
+
+    <sect2>
+      <title>Practical Uses</title>
+
+      <para><acronym>NFS</acronym> has many practical uses.  Some of
+        the more common ones are listed below:</para>
+
+      <indexterm>
+        <primary>NFS</primary>
+        <secondary>uses</secondary>
+      </indexterm>
+      <itemizedlist>
+        <listitem>
+	  <para>Set several machines to share a CDROM or other media
+	    among them.  This is cheaper and often a more convenient
+	    method to install software on multiple machines.</para>
+	</listitem>
+
+	<listitem>
+	  <para>On large networks, it might be more convenient to
+	    configure a central <acronym>NFS</acronym> server in which
+	    to store all the user home directories.  These home
+	    directories can then be exported to the network so that
+	    users would always have the same home directory,
+	    regardless of which workstation they log in to.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Several machines could have a common
+            <filename>/usr/ports/distfiles</filename> directory.  That
+            way, when you need to install a port on several machines,
+            you can quickly access the source without downloading it
+            on each machine.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2 id="network-amd">
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Wylie</firstname>
+	    <surname>Stilwell</surname>
+	    <contrib>Contributed by </contrib>
+	  </author>
+	</authorgroup>
+	<authorgroup>
+	  <author>
+	    <firstname>Chern</firstname>
+	    <surname>Lee</surname>
+	    <contrib>Rewritten by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+      <title>Automatic Mounts with <application>amd</application></title>
+
+      <indexterm><primary>amd</primary></indexterm>
+      <indexterm><primary>automatic mounter daemon</primary></indexterm>
+
+      <para>&man.amd.8; (the automatic mounter daemon)
+	automatically mounts a
+	remote file system whenever a file or directory within that
+	file system 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
+	file system from an IP address, while <filename>/host</filename>
+	is used to mount an export from a remote hostname.</para>
+
+      <para>An access to a file within
+	<filename>/host/foobar/usr</filename> would tell
+	<application>amd</application> to attempt to mount the
+	<filename>/usr</filename> export on the host
+	<hostid>foobar</hostid>.</para>
+
+      <example>
+	<title>Mounting an Export with <application>amd</application></title>
+
+	<para>You can view the available mounts of a remote host with
+	  the <command>showmount</command> command.  For example, to
+	  view the mounts of a host named <hostid>foobar</hostid>, you
+	  can use:</para>
+
+	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
+Exports list on foobar:
+/usr                               10.10.10.0
+/a                                 10.10.10.0
+&prompt.user; <userinput>cd /host/foobar/usr</userinput></screen>
+      </example>
+
+      <para>As seen in the example, the <command>showmount</command> shows
+	<filename>/usr</filename> as an export.  When changing directories to
+	<filename>/host/foobar/usr</filename>, <application>amd</application>
+	attempts to resolve the hostname <hostid>foobar</hostid> and
+	automatically mount the desired export.</para>
+
+      <para><application>amd</application> can be started by the
+	startup scripts by placing the following lines in
+	<filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>amd_enable="YES"</programlisting>
+
+      <para>Additionally, custom flags can be passed to
+      <application>amd</application> from the
+      <varname>amd_flags</varname> option.  By default,
+      <varname>amd_flags</varname> is set to:</para>
+
+      <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>
+
+      <para>The <filename>/etc/amd.map</filename> file defines the
+	default options that exports are mounted with.  The
+	<filename>/etc/amd.conf</filename> file defines some of the more
+	advanced features of <application>amd</application>.</para>
+
+      <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more
+	information.</para>
+    </sect2>
+
+    <sect2 id="network-nfs-integration">
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>John</firstname>
+            <surname>Lind</surname>
+            <contrib>Contributed by </contrib>
+          </author>
+        </authorgroup>
+      </sect2info>
+      <title>Problems Integrating with Other Systems</title>
+
+      <para>Certain Ethernet adapters for ISA PC systems have limitations
+	which can lead to serious network problems, particularly with NFS.
+	This difficulty is not specific to FreeBSD, but FreeBSD systems
+	are affected by it.</para>
+
+      <para>The problem nearly always occurs when (FreeBSD) PC systems are
+	networked with high-performance workstations, such as those made
+	by Silicon Graphics, Inc., and Sun Microsystems, Inc.  The NFS
+	mount will work fine, and some operations may succeed, but
+	suddenly the server will seem to become unresponsive to the
+	client, even though requests to and from other systems continue to
+	be processed.  This happens to the client system, whether the
+	client is the FreeBSD system or the workstation.  On many systems,
+	there is no way to shut down the client gracefully once this
+	problem has manifested itself.  The only solution is often to
+	reset the client, because the NFS situation cannot be
+	resolved.</para>
+
+      <para>Though the <quote>correct</quote> solution is to get a
+	higher performance and capacity Ethernet adapter for the
+	FreeBSD system, there is a simple workaround that will allow
+	satisfactory operation.  If the FreeBSD system is the
+	<emphasis>server</emphasis>, include the option
+	<option>-w=1024</option> on the mount from the client.  If the
+	FreeBSD system is the <emphasis>client</emphasis>, then mount
+	the NFS file system with the option <option>-r=1024</option>.
+	These options may be specified using the fourth field of the
+	<filename>fstab</filename> entry on the client for automatic
+	mounts, or by using the <option>-o</option> parameter of the
+	&man.mount.8; command for manual mounts.</para>
+
+      <para>It should be noted that there is a different problem,
+	sometimes mistaken for this one, when the NFS servers and
+	clients are on different networks.  If that is the case, make
+	<emphasis>certain</emphasis> that your routers are routing the
+	necessary <acronym>UDP</acronym> information, or you will not get anywhere, no
+	matter what else you are doing.</para>
+
+      <para>In the following examples, <hostid>fastws</hostid> is the host
+	(interface) name of a high-performance workstation, and
+	<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
+	system with a lower-performance Ethernet adapter.  Also,
+	<filename>/sharedfs</filename> will be the exported NFS
+	file system (see &man.exports.5;), and
+	<filename>/project</filename> will be the mount point on the
+	client for the exported file system.  In all cases, note that
+	additional options, such as <option>hard</option> or
+	<option>soft</option> and <option>bg</option> may be desirable in
+	your application.</para>
+
+      <para>Examples for the FreeBSD system (<hostid>freebox</hostid>)
+	as the client in <filename>/etc/fstab</filename> on
+	<hostid>freebox</hostid>:</para>
+
+      <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
+
+      <para>As a manual mount command on <hostid>freebox</hostid>:</para>
+
+      <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
+
+      <para>Examples for the FreeBSD system as the server in
+	<filename>/etc/fstab</filename> on
+	<hostid>fastws</hostid>:</para>
+
+      <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
+
+      <para>As a manual mount command on <hostid>fastws</hostid>:</para>
+
+      <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
+
+      <para>Nearly any 16-bit Ethernet adapter will allow operation
+	without the above restrictions on the read or write size.</para>
+
+      <para>For anyone who cares, here is what happens when the
+	failure occurs, which also explains why it is unrecoverable.
+	NFS typically works with a <quote>block</quote> size of
+	8&nbsp;K (though it may do fragments of smaller sizes).  Since
+	the maximum Ethernet packet is around 1500&nbsp;bytes, the NFS
+	<quote>block</quote> gets split into multiple Ethernet
+	packets, even though it is still a single unit to the
+	upper-level code, and must be received, assembled, and
+	<emphasis>acknowledged</emphasis> as a unit.  The
+	high-performance workstations can pump out the packets which
+	comprise the NFS unit one right after the other, just as close
+	together as the standard allows.  On the smaller, lower
+	capacity cards, the later packets overrun the earlier packets
+	of the same unit before they can be transferred to the host
+	and the unit as a whole cannot be reconstructed or
+	acknowledged.  As a result, the workstation will time out and
+	try again, but it will try again with the entire 8&nbsp;K
+	unit, and the process will be repeated, ad infinitum.</para>
+
+      <para>By keeping the unit size below the Ethernet packet size
+	limitation, we ensure that any complete Ethernet packet
+	received can be acknowledged individually, avoiding the
+	deadlock situation.</para>
+
+      <para>Overruns may still occur when a high-performance
+	workstations is slamming data out to a PC system, but with the
+	better cards, such overruns are not guaranteed on NFS
+	<quote>units</quote>.  When an overrun occurs, the units
+	affected will be retransmitted, and there will be a fair
+	chance that they will be received, assembled, and
+	acknowledged.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-nis">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Bill</firstname>
+      	  <surname>Swingle</surname>
+	  <contrib>Written by </contrib>
+         </author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Eric</firstname>
+	  <surname>Ogren</surname>
+	  <contrib>Enhanced by </contrib>
+	</author>
+	<author>
+	  <firstname>Udo</firstname>
+	  <surname>Erdelhoff</surname>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Network Information System (NIS/YP)</title>
+
+    <sect2>
+      <title>What Is It?</title>
+      <indexterm><primary>NIS</primary></indexterm>
+      <indexterm><primary>Solaris</primary></indexterm>
+      <indexterm><primary>HP-UX</primary></indexterm>
+      <indexterm><primary>AIX</primary></indexterm>
+      <indexterm><primary>Linux</primary></indexterm>
+      <indexterm><primary>NetBSD</primary></indexterm>
+      <indexterm><primary>OpenBSD</primary></indexterm>
+
+      <para><acronym role="Network Information System">NIS</acronym>,
+        which stands for Network Information Services, was developed
+        by Sun Microsystems to centralize administration of &unix;
+        (originally &sunos;) systems.  It has now essentially become
+        an industry standard; all major &unix; like systems
+        (&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD,
+        etc) support <acronym role="Network Information
+        System">NIS</acronym>.</para>
+
+      <indexterm><primary>yellow pages</primary><see>NIS</see></indexterm>
+
+      <para><acronym role="Network Information System">NIS</acronym>
+	was formerly known as Yellow Pages, but because of trademark
+	issues, Sun changed the name.  The old term (and yp) is still
+	often seen and used.</para>
+
+      <indexterm>
+        <primary>NIS</primary>
+        <secondary>domains</secondary>
+      </indexterm>
+
+      <para>It is a RPC-based client/server system that allows a group
+	of machines within an NIS domain to share a common set of
+	configuration files.  This permits a system administrator to
+	set up NIS client systems with only minimal configuration data
+	and add, remove or modify configuration data from a single
+	location.</para>
+
+      <indexterm><primary>Windows NT</primary></indexterm>
+
+      <para>It is similar to the &windowsnt; domain system; although
+        the internal implementation of the two are not at all similar,
+        the basic functionality can be compared.</para>
+    </sect2>
+
+    <sect2>
+      <title>Terms/Processes You Should Know</title>
+
+      <para>There are several terms and several important user
+        processes that you will come across when attempting to
+        implement NIS on FreeBSD, whether you are trying to create an
+        NIS server or act as an NIS client:</para>
+
+      <indexterm>
+	<primary><application>rpcbind</application></primary>
+      </indexterm>
+      <indexterm>
+	<primary><application>portmap</application></primary>
+      </indexterm>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	<colspec colwidth="1*">
+	<colspec colwidth="3*">
+
+	  <thead>
+	    <row>
+	      <entry>Term</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+	  <tbody>
+	    <row>
+	      <entry>NIS domainname</entry>
+
+	      <entry>An NIS master server and all of its clients
+		(including its slave servers) have a NIS domainname.
+		Similar to an &windowsnt; domain name, the NIS
+		domainname does not have anything to do with
+		<acronym>DNS</acronym>.</entry>
+	    </row>
+	    <row>
+	      <entry><application>rpcbind</application></entry>
+
+	      <entry>Must be running in order to enable
+		<acronym>RPC</acronym> (Remote Procedure Call, a
+		network protocol used by NIS).  If
+		<application>rpcbind</application> is not running, it
+		will be impossible to run an NIS server, or to act as
+		an NIS client.</entry>
+	    </row>
+	    <row>
+	      <entry><application>ypbind</application></entry>
+
+	      <entry><quote>Binds</quote> an NIS client to its NIS
+		server.  It will take the NIS domainname from the
+		system, and using <acronym>RPC</acronym>, connect to
+		the server.  <application>ypbind</application> is the
+		core of client-server communication in an NIS
+		environment; if <application>ypbind</application> dies
+		on a client machine, it will not be able to access the
+		NIS server.</entry>
+	    </row>
+	    <row>
+	      <entry><application>ypserv</application></entry>
+	      <entry>Should only be running on NIS servers; this is
+		the NIS server process itself.  If &man.ypserv.8;
+		dies, then the server will no longer be able to
+		respond to NIS requests (hopefully, there is a slave
+		server to take over for it).  There are some
+		implementations of NIS (but not the FreeBSD one), that
+		do not try to reconnect to another server if the
+		server it used before dies.  Often, the only thing
+		that helps in this case is to restart the server
+		process (or even the whole server) or the
+		<application>ypbind</application> process on the
+		client.
+	      </entry>
+	    </row>
+	    <row>
+	      <entry><application>rpc.yppasswdd</application></entry>
+	      <entry>Another process that should only be running on
+		NIS master servers; this is a daemon that will allow NIS
+		clients to change their NIS passwords.  If this daemon
+		is not running, users will have to login to the NIS
+		master server and change their passwords there.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+      <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
+      on the master -->
+
+    </sect2>
+
+    <sect2>
+      <title>How Does It Work?</title>
+
+      <para>There are three types of hosts in an NIS environment:
+	master servers, slave servers, and clients.  Servers act as a
+	central repository for host configuration information.  Master
+	servers hold the authoritative copy of this information, while
+	slave servers mirror this information for redundancy.  Clients
+	rely on the servers to provide this information to
+	them.</para>
+
+      <para>Information in many files can be shared in this manner.
+	The <filename>master.passwd</filename>,
+	<filename>group</filename>, and <filename>hosts</filename>
+	files are commonly shared via NIS.  Whenever a process on a
+	client needs information that would normally be found in these
+	files locally, it makes a query to the NIS server that it is
+	bound to instead.</para>
+
+      <sect3>
+        <title>Machine Types</title>
+
+        <itemizedlist>
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>master server</secondary>
+	  </indexterm>
+          <listitem>
+            <para>A <emphasis>NIS master server</emphasis>.  This
+              server, analogous to a &windowsnt; primary domain
+              controller, maintains the files used by all of the NIS
+              clients.  The <filename>passwd</filename>,
+              <filename>group</filename>, and other various files used
+              by the NIS clients live on the master server.</para>
+
+            <note><para>It is possible for one machine to be an NIS
+              master server for more than one NIS domain.  However,
+              this will not be covered in this introduction, which
+              assumes a relatively small-scale NIS
+              environment.</para></note>
+          </listitem>
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>slave server</secondary>
+	  </indexterm>
+          <listitem>
+            <para><emphasis>NIS slave servers</emphasis>.  Similar to
+              the &windowsnt; backup domain controllers, NIS slave
+              servers maintain copies of the NIS master's data files.
+              NIS slave servers provide the redundancy, which is
+              needed in important environments.  They also help to
+              balance the load of the master server: NIS Clients
+              always attach to the NIS server whose response they get
+              first, and this includes slave-server-replies.</para>
+          </listitem>
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>client</secondary>
+	  </indexterm>
+          <listitem>
+            <para><emphasis>NIS clients</emphasis>.  NIS clients, like
+              most &windowsnt; workstations, authenticate against the
+              NIS server (or the &windowsnt; domain controller in the
+              &windowsnt; workstations case) to log on.</para>
+          </listitem>
+        </itemizedlist>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Using NIS/YP</title>
+
+      <para>This section will deal with setting up a sample NIS
+        environment.</para>
+
+      <note><para>This section assumes that you are running
+        FreeBSD&nbsp;3.3 or later.  The instructions given here will
+        <emphasis>probably</emphasis> work for any version of FreeBSD
+        greater than 3.0, but there are no guarantees that this is
+        true.</para></note>
+
+
+      <sect3>
+        <title>Planning</title>
+
+        <para>Let us assume that you are the administrator of a small
+          university lab.  This lab, which consists of 15 FreeBSD
+          machines, currently has no centralized point of
+          administration; each machine has its own
+          <filename>/etc/passwd</filename> and
+          <filename>/etc/master.passwd</filename>.  These files are
+          kept in sync with each other only through manual
+          intervention; currently, when you add a user to the lab, you
+          must run <command>adduser</command> on all 15 machines.
+          Clearly, this has to change, so you have decided to convert
+          the lab to use NIS, using two of the machines as
+          servers.</para>
+
+        <para>Therefore, the configuration of the lab now looks something
+          like:</para>
+
+        <informaltable frame="none" pgwide="1">
+          <tgroup cols="3">
+            <thead>
+              <row>
+                <entry>Machine name</entry>
+                <entry>IP address</entry>
+                <entry>Machine role</entry>
+              </row>
+            </thead>
+            <tbody>
+              <row>
+                <entry><hostid>ellington</hostid></entry>
+                <entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
+                <entry>NIS master</entry>
+              </row>
+              <row>
+                <entry><hostid>coltrane</hostid></entry>
+                <entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
+                <entry>NIS slave</entry>
+              </row>
+              <row>
+                <entry><hostid>basie</hostid></entry>
+                <entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
+                <entry>Faculty workstation</entry>
+              </row>
+              <row>
+                <entry><hostid>bird</hostid></entry>
+                <entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
+                <entry>Client machine</entry>
+              </row>
+              <row>
+                <entry><hostid>cli[1-11]</hostid></entry>
+                <entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
+                <entry>Other client machines</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+
+        <para>If you are setting up a NIS scheme for the first time, it
+	  is a good idea to think through how you want to go about it.  No
+	  matter what the size of your network, there are a few decisions
+	  that need to be made.</para>
+
+        <sect4>
+          <title>Choosing a NIS Domain Name</title>
+
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>domainname</secondary>
+	  </indexterm>
+          <para>This might not be the <quote>domainname</quote> that
+	    you are used to.  It is more accurately called the
+	    <quote>NIS domainname</quote>.  When a client broadcasts
+	    its requests for info, it includes the name of the NIS
+	    domain that it is part of.  This is how multiple servers
+	    on one network can tell which server should answer which
+	    request.  Think of the NIS domainname as the name for a
+	    group of hosts that are related in some way.</para>
+
+	  <para>Some organizations choose to use their Internet
+	    domainname for their NIS domainname.  This is not
+	    recommended as it can cause confusion when trying to debug
+	    network problems.  The NIS domainname should be unique
+	    within your network and it is helpful if it describes the
+	    group of machines it represents.  For example, the Art
+	    department at Acme Inc. might be in the
+	    <quote>acme-art</quote> NIS domain.  For this example,
+	    assume you have chosen the name
+	    <literal>test-domain</literal>.</para>
+
+	  <indexterm><primary>SunOS</primary></indexterm>
+          <para>However, some operating systems (notably &sunos;) use
+          their NIS domain name as their Internet domain name.  If one
+          or more machines on your network have this restriction, you
+          <emphasis>must</emphasis> use the Internet domain name as
+          your NIS domain name.</para>
+        </sect4>
+
+        <sect4>
+          <title>Physical Server Requirements</title>
+
+	  <para>There are several things to keep in mind when choosing
+	    a machine to use as a NIS server.  One of the unfortunate
+	    things about NIS is the level of dependency the clients
+	    have on the server.  If a client cannot contact the server
+	    for its NIS domain, very often the machine becomes
+	    unusable.  The lack of user and group information causes
+	    most systems to temporarily freeze up.  With this in mind
+	    you should make sure to choose a machine that will not be
+	    prone to being rebooted regularly, or one that might be
+	    used for development.  The NIS server should ideally be a
+	    stand alone machine whose sole purpose in life is to be an
+	    NIS server.  If you have a network that is not very
+	    heavily used, it is acceptable to put the NIS server on a
+	    machine running other services, just keep in mind that if
+	    the NIS server becomes unavailable, it will affect
+	    <emphasis>all</emphasis> of your NIS clients
+	    adversely.</para>
+        </sect4>
+      </sect3>
+
+      <sect3>
+        <title>NIS Servers</title>
+
+	<para> The canonical copies of all NIS information are stored
+	  on a single machine called the NIS master server.  The
+	  databases used to store the information are called NIS maps.
+	  In FreeBSD, these maps are stored in
+	  <filename>/var/yp/[domainname]</filename> where
+	  <filename>[domainname]</filename> is the name of the NIS
+	  domain being served.  A single NIS server can support
+	  several domains at once, therefore it is possible to have
+	  several such directories, one for each supported domain.
+	  Each domain will have its own independent set of
+	  maps.</para>
+
+	<para>NIS master and slave servers handle all NIS requests
+	  with the <command>ypserv</command> daemon.
+	  <command>ypserv</command> is responsible for receiving
+	  incoming requests from NIS clients, translating the
+	  requested domain and map name to a path to the corresponding
+	  database file and transmitting data from the database back
+	  to the client.</para>
+
+        <sect4>
+	  <title>Setting Up a NIS Master Server</title>
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>server configuration</secondary>
+	  </indexterm>
+	  <para>Setting up a master NIS server can be relatively
+	    straight forward, depending on your needs.  FreeBSD comes
+	    with support for NIS out-of-the-box.  All you need is to
+	    add the following lines to
+	    <filename>/etc/rc.conf</filename>, and FreeBSD will do the
+	    rest for you.</para>
+
+          <procedure>
+            <step>
+              <para><programlisting>nisdomainname="test-domain"</programlisting>
+                This line will set the NIS domainname to
+                <literal>test-domain</literal>
+                upon network setup (e.g. after reboot).</para>
+            </step>
+            <step>
+              <para><programlisting>nis_server_enable="YES"</programlisting>
+                This will tell FreeBSD to start up the NIS server processes
+                when the networking is next brought up.</para>
+            </step>
+            <step>
+              <para><programlisting>nis_yppasswdd_enable="YES"</programlisting>
+                This will enable the <command>rpc.yppasswdd</command>
+                daemon which, as mentioned above, will allow users to
+                change their NIS password from a client machine.</para>
+            </step>
+          </procedure>
+
+          <note>
+            <para>Depending on your NIS setup, you may need to add
+              further entries.  See the <link
+              linkend="network-nis-server-is-client">section about NIS
+              servers that are also NIS clients</link>, below, for
+              details.</para>
+          </note>
+
+          <para>Now, all you have to do is to run the command
+            <command>/etc/netstart</command> as superuser.  It will
+            set up everything for you, using the values you defined in
+            <filename>/etc/rc.conf</filename>.</para>
+        </sect4>
+
+        <sect4>
+          <title>Initializing the NIS Maps</title>
+          <indexterm>
+            <primary>NIS</primary>
+            <secondary>maps</secondary>
+          </indexterm>
+          <para>The <emphasis>NIS maps</emphasis> are database files,
+            that are kept in the <filename>/var/yp</filename>
+            directory.  They are generated from configuration files in
+            the <filename>/etc</filename> directory of the NIS master,
+            with one exception: the
+            <filename>/etc/master.passwd</filename> file.  This is for
+            a good reason, you do not want to propagate passwords to
+            your <username>root</username> and other administrative
+            accounts to all the servers in the NIS domain.  Therefore,
+            before we initialize the NIS maps, you should:</para>
+
+          <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput>
+&prompt.root; <userinput>cd /var/yp</userinput>
+&prompt.root; <userinput>vi master.passwd</userinput></screen>
+
+          <para>You should remove all entries regarding system
+            accounts (<username>bin</username>,
+            <username>tty</username>, <username>kmem</username>,
+            <username>games</username>, etc), as well as any accounts
+            that you do not want to be propagated to the NIS clients
+            (for example <username>root</username> and any other UID 0
+            (superuser) accounts).</para>
+
+          <note><para>Make sure the
+            <filename>/var/yp/master.passwd</filename> is neither group
+            nor world readable (mode 600)!  Use the
+            <command>chmod</command> command, if appropriate.</para></note>
+
+	  <indexterm><primary>Tru64 UNIX</primary></indexterm>
+
+          <para>When you have finished, it is time to initialize the
+            NIS maps!  FreeBSD includes a script named
+            <command>ypinit</command> to do this for you (see its
+            manual page for more information).  Note that this script
+            is available on most &unix; Operating Systems, but not on
+            all.  On Digital UNIX/Compaq Tru64 UNIX it is called
+            <command>ypsetup</command>.  Because we are generating
+            maps for an NIS master, we are going to pass the
+            <option>-m</option> option to <command>ypinit</command>.
+            To generate the NIS maps, assuming you already performed
+            the steps above, run:</para>
+
+          <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput>
+Server Type: MASTER Domain: test-domain
+Creating an YP server will require that you answer a few questions.
+Questions will all be asked at the beginning of the procedure.
+Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput>
+Ok, please remember to go back and redo manually whatever fails.
+If you don't, something might not work.
+At this point, we have to construct a list of this domains YP servers.
+rod.darktech.org is already known as master server.
+Please continue to add any slave servers, one per line. When you are
+done with the list, type a &lt;control D&gt;.
+master server   :  ellington
+next host to add:  <userinput>coltrane</userinput>
+next host to add:  <userinput>^D</userinput>
+The current list of NIS servers looks like this:
+ellington
+coltrane
+Is this correct?  [y/n: y] <userinput>y</userinput>
+
+[..output from map generation..]
+
+NIS Map update completed.
+ellington has been setup as an YP master server without any errors.</screen>
+
+          <para><command>ypinit</command> should have created
+            <filename>/var/yp/Makefile</filename> from
+            <filename>/var/yp/Makefile.dist</filename>.
+            When created, this file assumes that you are operating
+            in a single server NIS environment with only FreeBSD
+            machines.  Since <literal>test-domain</literal> has
+            a slave server as well, you must edit
+            <filename>/var/yp/Makefile</filename>:</para>
+
+          <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen>
+
+	  <para>You should comment out the line that says</para>
+
+	  <programlisting>NOPUSH = "True"</programlisting>
+
+	  <para>(if it is not commented out already).</para>
+        </sect4>
+
+        <sect4>
+	  <title>Setting up a NIS Slave Server</title>
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>slave server</secondary>
+	  </indexterm>
+	  <para>Setting up an NIS slave server is even more simple than
+	    setting up the master.  Log on to the slave server and edit the
+            file <filename>/etc/rc.conf</filename> as you did before.
+            The only difference is that we now must use the
+            <option>-s</option> option when running <command>ypinit</command>.
+            The <option>-s</option> option requires the name of the NIS
+            master be passed to it as well, so our command line looks
+            like:</para>
+
+  <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput>
+
+Server Type: SLAVE Domain: test-domain Master: ellington
+
+Creating an YP server will require that you answer a few questions.
+Questions will all be asked at the beginning of the procedure.
+
+Do you want this procedure to quit on non-fatal errors? [y/n: n]  <userinput>n</userinput>
+
+Ok, please remember to go back and redo manually whatever fails.
+If you don't, something might not work.
+There will be no further questions. The remainder of the procedure
+should take a few minutes, to copy the databases from ellington.
+Transferring netgroup...
+ypxfr: Exiting: Map successfully transferred
+Transferring netgroup.byuser...
+ypxfr: Exiting: Map successfully transferred
+Transferring netgroup.byhost...
+ypxfr: Exiting: Map successfully transferred
+Transferring master.passwd.byuid...
+ypxfr: Exiting: Map successfully transferred
+Transferring passwd.byuid...
+ypxfr: Exiting: Map successfully transferred
+Transferring passwd.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring group.bygid...
+ypxfr: Exiting: Map successfully transferred
+Transferring group.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring services.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring rpc.bynumber...
+ypxfr: Exiting: Map successfully transferred
+Transferring rpc.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring protocols.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring master.passwd.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring networks.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring networks.byaddr...
+ypxfr: Exiting: Map successfully transferred
+Transferring netid.byname...
+ypxfr: Exiting: Map successfully transferred
+Transferring hosts.byaddr...
+ypxfr: Exiting: Map successfully transferred
+Transferring protocols.bynumber...
+ypxfr: Exiting: Map successfully transferred
+Transferring ypservers...
+ypxfr: Exiting: Map successfully transferred
+Transferring hosts.byname...
+ypxfr: Exiting: Map successfully transferred
+
+coltrane has been setup as an YP slave server without any errors.
+Don't forget to update map ypservers on ellington.</screen>
+
+	  <para>You should now have a directory called
+	    <filename>/var/yp/test-domain</filename>.  Copies of the NIS
+	    master server's maps should be in this directory.  You will
+	    need to make sure that these stay updated.  The following
+	    <filename>/etc/crontab</filename> entries on your slave
+	    servers should do the job:</para>
+
+	  <programlisting>20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
+21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>
+
+	  <para>These two lines force the slave to sync its maps with
+	    the maps on the master server.  Although these entries are
+	    not mandatory, since the master server attempts to ensure
+	    any changes to its NIS maps are communicated to its slaves
+	    and because password information is vital to systems
+	    depending on the server, it is a good idea to force the
+	    updates.  This is more important on busy networks where map
+	    updates might not always complete.</para>
+
+          <para>Now, run the command <command>/etc/netstart</command> on the
+            slave server as well, which again starts the NIS server.</para>
+	</sect4>
+      </sect3>
+
+      <sect3>
+        <title>NIS Clients</title>
+
+	<para> An NIS client establishes what is called a binding to a
+	  particular NIS server using the
+	  <command>ypbind</command> daemon.
+	  <command>ypbind</command> checks the system's default
+	  domain (as set by the <command>domainname</command> command),
+	  and begins broadcasting RPC requests on the local network.
+	  These requests specify the name of the domain for which
+	  <command>ypbind</command> is attempting to establish a binding.
+	  If a server that has been configured to serve the requested
+	  domain receives one of the broadcasts, it will respond to
+	  <command>ypbind</command>,  which will record the server's
+	  address.  If there are several servers available (a master and
+	  several slaves, for example), <command>ypbind</command> will
+	  use the address of the first one to respond.  From that point
+	  on, the client system will direct all of its NIS requests to
+	  that server.  <command>ypbind</command> will
+	  occasionally <quote>ping</quote> the server to make sure it is
+	  still up and running.  If it fails to receive a reply to one of
+	  its pings within a reasonable amount of time,
+	  <command>ypbind</command> will mark the domain as unbound and
+	  begin broadcasting again in the hopes of locating another
+	  server.</para>
+
+	<sect4>
+	  <title>Setting Up a NIS Client</title>
+	  <indexterm>
+	    <primary>NIS</primary>
+	    <secondary>client configuration</secondary>
+	  </indexterm>
+	  <para>Setting up a FreeBSD machine to be a NIS client is fairly
+	    straightforward.</para>
+
+	  <procedure>
+	    <step>
+	      <para>Edit the file <filename>/etc/rc.conf</filename> and
+                add the following lines in order to set the NIS domainname
+                and start <command>ypbind</command> upon network
+                startup:</para>
+
+	      <programlisting>nisdomainname="test-domain"
+nis_client_enable="YES"</programlisting>
+	    </step>
+
+	    <step>
+	      <para>To import all possible password entries from the NIS
+		server, remove all user accounts from your
+		<filename>/etc/master.passwd</filename> file and use
+		<command>vipw</command> to add the following line to
+                the end of the file:</para>
+
+	      <programlisting>+:::::::::</programlisting>
+
+	      <note>
+		<para>This line will afford anyone with a valid account in
+		  the NIS server's password maps an account.  There are
+		  many ways to configure your NIS client by changing this
+		  line.  See the <link linkend="network-netgroups">netgroups
+		  section</link> below for more information.
+                  For more detailed reading see O'Reilly's book on
+		  <literal>Managing NFS and NIS</literal>.</para>
+	      </note>
+
+              <note>
+                <para>You should keep at least one local account (i.e.
+                  not imported via NIS) in your
+                  <filename>/etc/master.passwd</filename> and this
+                  account should also be a member of the group
+                  <groupname>wheel</groupname>.  If there is something
+                  wrong with NIS, this account can be used to log in
+                  remotely, become <username>root</username>, and fix things.</para>
+              </note>
+            </step>
+
+	    <step>
+	      <para>To import all possible group entries from the NIS
+		server, add this line to your
+		<filename>/etc/group</filename> file:</para>
+
+	      <programlisting>+:*::</programlisting>
+	    </step>
+	  </procedure>
+
+	  <para>After completing these steps, you should be able to run
+	    <command>ypcat passwd</command> and see the NIS server's
+	    passwd map.</para>
+	</sect4>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>NIS Security</title>
+
+      <para>In general, any remote user can issue an RPC to
+	&man.ypserv.8; and retrieve the contents of your NIS maps,
+	provided the remote user knows your domainname.  To prevent
+	such unauthorized transactions, &man.ypserv.8; supports a
+	feature called <quote>securenets</quote> which can be used to
+	restrict access to a given set of hosts.  At startup,
+	&man.ypserv.8; will attempt to load the securenets information
+	from a file called
+	<filename>/var/yp/securenets</filename>.</para>
+
+      <note>
+	<para>This path varies depending on the path specified with the
+	  <option>-p</option> option.  This file contains entries that
+	  consist of a network specification and a network mask separated
+	  by white space.  Lines starting with <quote>#</quote> are
+	  considered to be comments.  A sample securenets file might look
+	  like this:</para>
+      </note>
+
+      <programlisting># allow connections from local host -- mandatory
+127.0.0.1     255.255.255.255
+# allow connections from any host
+# on the 192.168.128.0 network
+192.168.128.0 255.255.255.0
+# allow connections from any host
+# between 10.0.0.0 to 10.0.15.255
+# this includes the machines in the testlab
+10.0.0.0      255.255.240.0</programlisting>
+
+      <para>If &man.ypserv.8; receives a request from an address that
+	matches one of these rules, it will process the request
+	normally.  If the address fails to match a rule, the request
+	will be ignored and a warning message will be logged.  If the
+	<filename>/var/yp/securenets</filename> file does not exist,
+	<command>ypserv</command> will allow connections from any
+	host.</para>
+
+      <para>The <command>ypserv</command> program also has support for
+	Wietse Venema's <application>TCP Wrapper</application> package.
+	This allows the administrator to use the
+	<application>TCP Wrapper</application> configuration files for
+	access control instead of
+	<filename>/var/yp/securenets</filename>.</para>
+
+      <note>
+        <para>While both of these access control mechanisms provide some
+          security, they, like the privileged port test, are
+          vulnerable to <quote>IP spoofing</quote> attacks.  All
+          NIS-related traffic should be blocked at your firewall.</para>
+
+        <para>Servers using <filename>/var/yp/securenets</filename>
+          may fail to serve legitimate NIS clients with archaic TCP/IP
+          implementations.  Some of these implementations set all
+          host bits to zero when doing broadcasts and/or fail to
+          observe the subnet mask when calculating the broadcast
+          address.  While some of these problems can be fixed by
+          changing the client configuration, other problems may force
+          the retirement of the client systems in question or the
+          abandonment of <filename>/var/yp/securenets</filename>.</para>
+
+        <para>Using <filename>/var/yp/securenets</filename> on a
+          server with such an archaic implementation of TCP/IP is a
+          really bad idea and will lead to loss of NIS functionality
+          for large parts of your network.</para>
+
+	<indexterm><primary>TCP Wrappers</primary></indexterm>
+        <para>The use of the <application>TCP Wrapper</application>
+          package increases the latency of your NIS server.  The
+          additional delay may be long enough to cause timeouts in
+          client programs, especially in busy networks or with slow
+          NIS servers.  If one or more of your client systems
+          suffers from these symptoms, you should convert the client
+          systems in question into NIS slave servers and force them
+          to bind to themselves.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Barring Some Users from Logging On</title>
+
+      <para>In our lab, there is a machine <hostid>basie</hostid> that
+        is supposed to be a faculty only workstation.  We do not want
+        to take this machine out of the NIS domain, yet the
+        <filename>passwd</filename> file on the master NIS server
+        contains accounts for both faculty and students.  What can we
+        do?</para>
+
+      <para>There is a way to bar specific users from logging on to a
+        machine, even if they are present in the NIS database.  To do
+        this, all you must do is add
+        <literal>-<replaceable>username</replaceable></literal> to the
+        end of the <filename>/etc/master.passwd</filename> file on the
+        client machine, where <replaceable>username</replaceable> is
+        the username of the user you wish to bar from logging in.
+        This should preferably be done using <command>vipw</command>,
+        since <command>vipw</command> will sanity check your changes
+        to <filename>/etc/master.passwd</filename>, as well as
+        automatically rebuild the password database when you finish
+        editing.  For example, if we wanted to bar user
+        <username>bill</username> from logging on to
+        <hostid>basie</hostid> we would:</para>
+
+        <screen>basie&prompt.root; <userinput>vipw</userinput>
+<userinput>[add -bill to the end, exit]</userinput>
+vipw: rebuilding the database...
+vipw: done
+
+basie&prompt.root; <userinput>cat /etc/master.passwd</userinput>
+
+root:[password]:0:0::0:0:The super-user:/root:/bin/csh
+toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
+daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
+operator:*:2:5::0:0:System &:/:/sbin/nologin
+bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
+tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
+kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
+games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
+news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
+man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
+bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
+uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
+xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
+pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
+nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
++:::::::::
+-bill
+
+basie&prompt.root;</screen>
+    </sect2>
+
+    <sect2 id="network-netgroups">
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>Udo</firstname>
+            <surname>Erdelhoff</surname>
+            <contrib>Contributed by </contrib>
+          </author>
+        </authorgroup>
+      </sect2info>
+
+      <title>Using Netgroups</title>
+      <indexterm><primary>netgroups</primary></indexterm>
+
+      <para>The method shown in the previous section works reasonably
+        well if you need special rules for a very small number of
+        users and/or machines.  On larger networks, you
+        <emphasis>will</emphasis> forget to bar some users from logging
+        onto sensitive machines, or you may even have to modify each
+        machine separately, thus losing the main benefit of NIS:
+        <emphasis>centralized</emphasis> administration.</para>
+
+      <para>The NIS developers' solution for this problem is called
+        <emphasis>netgroups</emphasis>.  Their purpose and semantics
+        can be compared to the normal groups used by &unix; file
+        systems.  The main differences are the lack of a numeric ID
+        and the ability to define a netgroup by including both user
+        accounts and other netgroups.</para>
+
+      <para>Netgroups were developed to handle large, complex networks
+        with hundreds of users and machines.  On one hand, this is
+        a Good Thing if you are forced to deal with such a situation.
+        On the other hand, this complexity makes it almost impossible to
+        explain netgroups with really simple examples.  The example
+        used in the remainder of this section demonstrates this
+        problem.</para>
+
+      <para>Let us assume that your successful introduction of NIS in
+        your laboratory caught your superiors' interest.  Your next
+        job is to extend your NIS domain to cover some of the other
+        machines on campus.  The two tables contain the names of the
+        new users and new machines as well as brief descriptions of
+        them.</para>
+
+      <informaltable frame="none" pgwide="1">
+        <tgroup cols="2">
+          <thead>
+            <row>
+              <entry>User Name(s)</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <entry><username>alpha</username>, <username>beta</username></entry>
+              <entry>Normal employees of the IT department</entry>
+            </row>
+
+            <row>
+              <entry><username>charlie</username>, <username>delta</username></entry>
+              <entry>The new apprentices of the IT department</entry>
+            </row>
+
+            <row>
+              <entry><username>echo</username>, <username>foxtrott</username>, <username>golf</username>, ...</entry>
+              <entry>Ordinary employees</entry>
+            </row>
+
+            <row>
+              <entry><username>able</username>, <username>baker</username>, ...</entry>
+              <entry>The current interns</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+
+      <informaltable frame="none" pgwide="1">
+        <tgroup cols="2">
+          <thead>
+            <row>
+              <entry>Machine Name(s)</entry>
+              <entry>Description</entry>
+            </row>
+          </thead>
+
+          <tbody>
+            <row>
+              <!--  Names taken from "Good Omens" by Neil Gaiman and Terry
+                    Pratchett.  Many thanks for a brilliant book.  -->
+
+              <entry><hostid>war</hostid>, <hostid>death</hostid>,
+              <hostid>famine</hostid>,
+              <hostid>pollution</hostid></entry>
+              <entry>Your most important servers.  Only the IT
+                employees are allowed to log onto these
+                machines.</entry>
+            </row>
+            <row>
+              <!-- gluttony was omitted because it was too fat -->
+
+              <entry><hostid>pride</hostid>, <hostid>greed</hostid>,
+              <hostid>envy</hostid>, <hostid>wrath</hostid>,
+              <hostid>lust</hostid>, <hostid>sloth</hostid></entry>
+              <entry>Less important servers.  All members of the IT
+              department are allowed to login onto these
+              machines.</entry>
+            </row>
+
+            <row>
+              <entry><hostid>one</hostid>, <hostid>two</hostid>,
+                <hostid>three</hostid>, <hostid>four</hostid>,
+                ...</entry>
+
+              <entry>Ordinary workstations.  Only the
+                <emphasis>real</emphasis> employees are allowed to use
+                these machines.</entry>
+            </row>
+
+            <row>
+              <entry><hostid>trashcan</hostid></entry>
+              <entry>A very old machine without any critical data.
+                Even the intern is allowed to use this box.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+
+      <para>If you tried to implement these restrictions by separately
+        blocking each user, you would have to add one
+        <literal>-<replaceable>user</replaceable></literal> line to
+        each system's <filename>passwd</filename> for each user who is
+        not allowed to login onto that system.  If you forget just one
+        entry, you could be in trouble.  It may be feasible to do this
+        correctly during the initial setup, however you
+        <emphasis>will</emphasis> eventually forget to add the lines
+        for new users during day-to-day operations.  After all, Murphy
+        was an optimist.</para>
+
+      <para>Handling this situation with netgroups offers several
+        advantages.  Each user need not be handled separately; you
+        assign a user to one or more netgroups and allow or forbid
+        logins for all members of the netgroup.  If you add a new
+        machine, you will only have to define login restrictions for
+        netgroups.  If a new user is added, you will only have to add
+        the user to one or more netgroups.  Those changes are
+        independent of each other: no more <quote>for each combination
+        of user and machine do...</quote> If your NIS setup is planned
+        carefully, you will only have to modify exactly one central
+        configuration file to grant or deny access to machines.</para>
+
+      <para>The first step is the initialization of the NIS map
+        netgroup.  FreeBSD's &man.ypinit.8; does not create this map by
+        default, but its NIS implementation will support it once it has
+        been created.  To create an empty map, simply type</para>
+
+      <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>
+
+      <para>and start adding content.  For our example, we need at
+         least four netgroups: IT employees, IT apprentices, normal
+         employees and interns.</para>
+
+      <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
+IT_APP  (,charlie,test-domain)  (,delta,test-domain)
+USERS   (,echo,test-domain)     (,foxtrott,test-domain) \
+        (,golf,test-domain)
+INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>
+
+      <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
+        are the names of the netgroups.  Each bracketed group adds
+        one or more user accounts to it.  The three fields inside a
+        group are:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>The name of the host(s) where the following items are
+            valid.  If you do not specify a hostname, the entry is
+            valid on all hosts.  If you do specify a hostname, you
+            will enter a realm of darkness, horror and utter confusion.</para>
+        </listitem>
+
+        <listitem>
+          <para>The name of the account that belongs to this
+            netgroup.</para>
+        </listitem>
+
+        <listitem>
+          <para>The NIS domain for the account.  You can import
+            accounts from other NIS domains into your netgroup if you
+            are one of the unlucky fellows with more than one NIS
+            domain.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>Each of these fields can contain wildcards.  See
+        &man.netgroup.5; for details.</para>
+
+      <note>
+        <indexterm><primary>netgroups</primary></indexterm>
+        <para>Netgroup names longer than 8 characters should not be
+          used, especially if you have machines running other
+          operating systems within your NIS domain.  The names are
+          case sensitive; using capital letters for your netgroup
+          names is an easy way to distinguish between user, machine
+          and netgroup names.</para>
+
+        <para>Some NIS clients (other than FreeBSD) cannot handle
+          netgroups with a large number of entries.  For example, some
+          older versions of &sunos; start to cause trouble if a netgroup
+          contains more than 15 <emphasis>entries</emphasis>.  You can
+          circumvent this limit by creating several sub-netgroups with
+          15 users or less and a real netgroup that consists of the
+          sub-netgroups:</para>
+
+        <programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
+BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
+BIGGRP3  (,joe31,domain)  (,joe32,domain)
+BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>
+
+        <para>You can repeat this process if you need more than 225
+          users within a single netgroup.</para>
+      </note>
+
+      <para>Activating and distributing your new NIS map is
+        easy:</para>
+
+      <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
+ellington&prompt.root; <userinput>make</userinput></screen>
+
+      <para>This will generate the three NIS maps
+        <filename>netgroup</filename>,
+        <filename>netgroup.byhost</filename> and
+        <filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
+        check if your new NIS maps are available:</para>
+
+      <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
+ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
+ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>
+
+      <para>The output of the first command should resemble the
+        contents of <filename>/var/yp/netgroup</filename>.  The second
+        command will not produce output if you have not specified
+        host-specific netgroups.  The third command can be used to
+        get the list of netgroups for a user.</para>
+
+      <para>The client setup is quite simple.  To configure the server
+        <hostid>war</hostid>, you only have to start
+        &man.vipw.8; and replace the line</para>
+
+      <programlisting>+:::::::::</programlisting>
+
+      <para>with</para>
+
+      <programlisting>+@IT_EMP:::::::::</programlisting>
+
+      <para>Now, only the data for the users defined in the netgroup
+        <literal>IT_EMP</literal> is imported into
+        <hostid>war</hostid>'s password database and only
+        these users are allowed to login.</para>
+
+      <para>Unfortunately, this limitation also applies to the
+	<literal>~</literal> function of the shell and all routines
+	converting between user names and numerical user IDs.  In
+	other words, <command>cd
+	~<replaceable>user</replaceable></command> will not work,
+	<command>ls -l</command> will show the numerical ID instead of
+	the username and <command>find . -user joe -print</command>
+	will fail with <errorname>No such user</errorname>.  To fix
+	this, you will have to import all user entries
+	<emphasis>without allowing them to login onto your
+	servers</emphasis>.</para>
+
+      <para>This can be achieved by adding another line to
+        <filename>/etc/master.passwd</filename>.  This line should
+        contain:</para>
+
+      <para><literal>+:::::::::/sbin/nologin</literal>, meaning
+        <quote>Import all entries but replace the shell with
+        <filename>/sbin/nologin</filename> in the imported
+        entries</quote>.  You can replace any field in the
+        <literal>passwd</literal> entry by placing a default value in
+        your <filename>/etc/master.passwd</filename>.</para>
+
+      <!-- Been there, done that, got the scars to prove it - ue -->
+      <warning>
+        <para>Make sure that the line
+        <literal>+:::::::::/sbin/nologin</literal> is placed after
+        <literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
+        accounts imported from NIS will have <filename>/sbin/nologin</filename> as their
+        login shell.</para>
+      </warning>
+
+      <para>After this change, you will only have to change one NIS
+        map if a new employee joins the IT department.  You could use
+        a similar approach for the less important servers by replacing
+        the old <literal>+:::::::::</literal> in their local version
+        of <filename>/etc/master.passwd</filename> with something like
+        this:</para>
+
+      <programlisting>+@IT_EMP:::::::::
++@IT_APP:::::::::
++:::::::::/sbin/nologin</programlisting>
+
+      <para>The corresponding lines for the normal workstations
+        could be:</para>
+
+      <programlisting>+@IT_EMP:::::::::
++@USERS:::::::::
++:::::::::/sbin/nologin</programlisting>
+
+      <para>And everything would be fine until there is a policy
+        change a few weeks later: The IT department starts hiring
+        interns.  The IT interns are allowed to use the normal
+        workstations and the less important servers; and the IT
+        apprentices are allowed to login onto the main servers.  You
+        add a new netgroup <literal>IT_INTERN</literal>, add the new
+        IT interns to this netgroup and start to change the
+        configuration on each and every machine...  As the old saying
+        goes: <quote>Errors in centralized planning lead to global
+        mess</quote>.</para>
+
+      <para>NIS' ability to create netgroups from other netgroups can
+        be used to prevent situations like these.  One possibility
+        is the creation of role-based netgroups.  For example, you
+        could create a netgroup called
+        <literal>BIGSRV</literal> to define the login
+        restrictions for the important servers, another netgroup
+        called <literal>SMALLSRV</literal> for the less
+        important servers and a third netgroup called
+        <literal>USERBOX</literal> for the normal
+        workstations.  Each of these netgroups contains the netgroups
+        that are allowed to login onto these machines.  The new
+        entries for your NIS map netgroup should look like this:</para>
+
+      <programlisting>BIGSRV    IT_EMP  IT_APP
+SMALLSRV  IT_EMP  IT_APP  ITINTERN
+USERBOX   IT_EMP  ITINTERN USERS</programlisting>
+
+      <para>This method of defining login restrictions works
+        reasonably well if you can define groups of machines with
+        identical restrictions.  Unfortunately, this is the exception
+        and not the rule.  Most of the time, you will need the ability
+        to define login restrictions on a per-machine basis.</para>
+
+      <para>Machine-specific netgroup definitions are the other
+        possibility to deal with the policy change outlined above.  In
+        this scenario, the <filename>/etc/master.passwd</filename> of
+        each box contains two lines starting with <quote>+</quote>.
+        The first of them adds a netgroup with the accounts allowed to
+        login onto this machine, the second one adds all other
+        accounts with <filename>/sbin/nologin</filename> as shell.  It
+        is a good idea to use the <quote>ALL-CAPS</quote> version of
+        the machine name as the name of the netgroup.  In other words,
+        the lines should look like this:</para>
+
+      <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
++:::::::::/sbin/nologin</programlisting>
+
+      <para>Once you have completed this task for all your machines,
+        you will not have to modify the local versions of
+        <filename>/etc/master.passwd</filename> ever again.  All
+        further changes can be handled by modifying the NIS map.  Here
+        is an example of a possible netgroup map for this
+        scenario with some additional goodies:</para>
+
+      <programlisting># Define groups of users first
+IT_EMP    (,alpha,test-domain)    (,beta,test-domain)
+IT_APP    (,charlie,test-domain)  (,delta,test-domain)
+DEPT1     (,echo,test-domain)     (,foxtrott,test-domain)
+DEPT2     (,golf,test-domain)     (,hotel,test-domain)
+DEPT3     (,india,test-domain)    (,juliet,test-domain)
+ITINTERN  (,kilo,test-domain)     (,lima,test-domain)
+D_INTERNS (,able,test-domain)     (,baker,test-domain)
+#
+# Now, define some groups based on roles
+USERS     DEPT1   DEPT2     DEPT3
+BIGSRV    IT_EMP  IT_APP
+SMALLSRV  IT_EMP  IT_APP    ITINTERN
+USERBOX   IT_EMP  ITINTERN  USERS
+#
+# And a groups for a special tasks
+# Allow echo and golf to access our anti-virus-machine
+SECURITY  IT_EMP  (,echo,test-domain)  (,golf,test-domain)
+#
+# machine-based netgroups
+# Our main servers
+WAR       BIGSRV
+FAMINE    BIGSRV
+# User india needs access to this server
+POLLUTION  BIGSRV  (,india,test-domain)
+#
+# This one is really important and needs more access restrictions
+DEATH     IT_EMP
+#
+# The anti-virus-machine mentioned above
+ONE       SECURITY
+#
+# Restrict a machine to a single user
+TWO       (,hotel,test-domain)
+# [...more groups to follow]</programlisting>
+
+      <para>If you are using some kind of database to manage your user
+        accounts, you should be able to create the first part of the
+        map with your database's report tools.  This way, new users
+        will automatically have access to the boxes.</para>
+
+      <para>One last word of caution: It may not always be advisable
+        to use machine-based netgroups.  If you are deploying a couple of
+        dozen or even hundreds of identical machines for student labs,
+        you should use role-based netgroups instead of machine-based
+        netgroups to keep the size of the NIS map within reasonable
+        limits.</para>
+    </sect2>
+
+    <sect2>
+      <title>Important Things to Remember</title>
+
+      <para>There are still a couple of things that you will need to do
+        differently now that you are in an NIS environment.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Every time you wish to add a user to the lab, you
+            must add it to the master NIS server <emphasis>only</emphasis>,
+            and <emphasis>you must remember to rebuild the NIS
+            maps</emphasis>.  If you forget to do this, the new user will
+            not be able to login anywhere except on the NIS master.
+            For example, if we needed to add a new user
+            <username>jsmith</username> to the lab, we would:</para>
+
+          <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
+&prompt.root; <userinput>cd /var/yp</userinput>
+&prompt.root; <userinput>make test-domain</userinput></screen>
+
+          <para>You could also run <command>adduser jsmith</command> instead
+            of <command>pw useradd jsmith</command>.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis>Keep the administration accounts out of the
+            NIS maps</emphasis>.  You do not want to be propagating
+            administrative accounts and passwords to machines that
+            will have users that should not have access to those
+            accounts.</para>
+        </listitem>
+        <listitem>
+          <para><emphasis>Keep the NIS master and slave secure, and
+            minimize their downtime</emphasis>.  If somebody either
+            hacks or simply turns off these machines, they have
+            effectively rendered many people without the ability to
+            login to the lab.</para>
+
+          <para>This is the chief weakness of any centralized administration
+            system.  If you do
+            not protect your NIS servers, you will have a lot of angry
+            users!</para>
+        </listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>NIS v1 Compatibility</title>
+
+      <para> FreeBSD's <application>ypserv</application> has some
+	support for serving NIS v1 clients.  FreeBSD's NIS
+	implementation only uses the NIS v2 protocol, however other
+	implementations include support for the v1 protocol for
+	backwards compatibility with older systems.  The
+	<application>ypbind</application> daemons supplied with these
+	systems will try to establish a binding to an NIS v1 server
+	even though they may never actually need it (and they may
+	persist in broadcasting in search of one even after they
+	receive a response from a v2 server).  Note that while support
+	for normal client calls is provided, this version of
+	<application>ypserv</application> does not handle v1 map
+	transfer requests; consequently, it cannot be used as a master
+	or slave in conjunction with older NIS servers that only
+	support the v1 protocol.  Fortunately, there probably are not
+	any such servers still in use today.</para>
+    </sect2>
+
+    <sect2 id="network-nis-server-is-client">
+      <title>NIS Servers That Are Also NIS Clients</title>
+
+      <para> Care must be taken when running
+	<application>ypserv</application> in a multi-server domain
+	where the server machines are also NIS clients.  It is
+	generally a good idea to force the servers to bind to
+	themselves rather than allowing them to broadcast bind
+	requests and possibly become bound to each other.  Strange
+	failure modes can result if one server goes down and others
+	are dependent upon it.  Eventually all the clients will time
+	out and attempt to bind to other servers, but the delay
+	involved can be considerable and the failure mode is still
+	present since the servers might bind to each other all over
+	again.</para>
+
+      <para>You can force a host to bind to a particular server by running
+	<command>ypbind</command> with the <option>-S</option>
+	flag.  If you do not want to do this manually each time you
+        reboot your NIS server, you can add the following lines to
+        your <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>nis_client_enable="YES"	# run client stuff as well
+nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting>
+
+      <para>See &man.ypbind.8; for further information.</para>
+    </sect2>
+
+    <sect2>
+      <title>Password Formats</title>
+      <indexterm>
+        <primary>NIS</primary>
+	<secondary>password formats</secondary>
+      </indexterm>
+      <para>One of the most common issues that people run into when trying
+	to implement NIS is password format compatibility.  If your NIS
+	server is using DES encrypted passwords, it will only support
+	clients that are also using DES.  For example, if you have
+	&solaris; NIS clients in your network, then you will almost certainly
+	need to use DES encrypted passwords.</para>
+
+      <para>To check which format your servers
+	and clients are using, look at <filename>/etc/login.conf</filename>.
+	If the host is configured to use DES encrypted passwords, then the
+	<literal>default</literal> class will contain an entry like this:</para>
+
+      <programlisting>default:\
+	:passwd_format=des:\
+	:copyright=/etc/COPYRIGHT:\
+	[Further entries elided]</programlisting>
+
+      <para>Other possible values for the <literal>passwd_format</literal>
+	capability include <literal>blf</literal> and <literal>md5</literal>
+	(for Blowfish and MD5 encrypted passwords, respectively).</para>
+
+      <para>If you have made changes to
+	<filename>/etc/login.conf</filename>, you will also need to
+	rebuild the login capability database, which is achieved by
+	running the following command as
+	<username>root</username>:</para>
+
+      <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
+
+      <note><para>The format of passwords already in
+	<filename>/etc/master.passwd</filename> will not be updated
+	until a user changes his password for the first time
+	<emphasis>after</emphasis> the login capability database is
+	rebuilt.</para></note>
+
+      <para>Next, in order to ensure that passwords are encrypted with
+	the format that you have chosen, you should also check that
+	the <literal>crypt_default</literal> in
+	<filename>/etc/auth.conf</filename> gives precedence to your
+	chosen password format.  To do this, place the format that you
+	have chosen first in the list.  For example, when using DES
+	encrypted passwords, the entry would be:</para>
+
+      <programlisting>crypt_default	=	des blf md5</programlisting>
+
+      <para>Having followed the above steps on each of the &os; based
+	NIS servers and clients, you can be sure that they all agree
+	on which password format is used within your network.  If you
+	have trouble authenticating on an NIS client, this is a pretty
+	good place to start looking for possible problems.  Remember:
+	if you want to deploy an NIS server for a heterogenous
+	network, you will probably have to use DES on all systems
+	because it is the lowest common standard.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-dhcp">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Greg</firstname>
+      	  <surname>Sutter</surname>
+	  <contrib>Written by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>Automatic Network Configuration (DHCP)</title>
+
+    <sect2>
+      <title>What Is DHCP?</title>
+      <indexterm>
+        <primary>Dynamic Host Configuration Protocol</primary>
+        <see>DHCP</see>
+      </indexterm>
+      <indexterm>
+        <primary>Internet Software Consortium (ISC)</primary>
+      </indexterm>
+
+      <para>DHCP, the Dynamic Host Configuration Protocol, describes
+        the means by which a system can connect to a network and obtain the
+        necessary information for communication upon that network.  FreeBSD
+	versions prior to 6.0 use the ISC (Internet Software
+	Consortium) DHCP client (&man.dhclient.8;) implementation.
+	Later versions use the OpenBSD <command>dhclient</command>
+	taken from OpenBSD&nbsp;3.7.  All
+	information here regarding <command>dhclient</command> is for
+	use with either of the ISC or OpenBSD DHCP clients. The DHCP
+	server is the one included in the ISC distribution.</para>
+    </sect2>
+
+    <sect2>
+      <title>What This Section Covers</title>
+
+      <para>This section describes both the client-side components of the ISC and OpenBSD DHCP client and
+        server-side components of the ISC DHCP system.  The
+        client-side program, <command>dhclient</command>, comes
+        integrated within FreeBSD, and the server-side portion is
+        available from the <filename
+        role="package">net/isc-dhcp3-server</filename> port.  The
+        &man.dhclient.8;, &man.dhcp-options.5;, and
+        &man.dhclient.conf.5; manual pages, in addition to the
+        references below, are useful resources.</para>
+    </sect2>
+
+    <sect2>
+      <title>How It Works</title>
+      <indexterm><primary>UDP</primary></indexterm>
+      <para>When <command>dhclient</command>, the DHCP client, is
+	executed on the client machine, it begins broadcasting
+	requests for configuration information.  By default, these
+	requests are on UDP port 68.  The server replies on UDP 67,
+	giving the client an IP address and other relevant network
+	information such as netmask, router, and DNS servers.  All of
+	this information comes in the form of a DHCP
+	<quote>lease</quote> and is only valid for a certain time
+	(configured by the DHCP server maintainer).  In this manner,
+	stale IP addresses for clients no longer connected to the
+	network can be automatically reclaimed.</para>
+
+      <para>DHCP clients can obtain a great deal of information from
+        the server.  An exhaustive list may be found in
+        &man.dhcp-options.5;.</para>
+    </sect2>
+
+    <sect2>
+      <title>FreeBSD Integration</title>
+
+      <para>&os; fully integrates the ISC or OpenBSD DHCP client,
+        <command>dhclient</command> (according to the &os; version you run).  DHCP client support is provided
+        within both the installer and the base system, obviating the need
+        for detailed knowledge of network configurations on any network
+        that runs a DHCP server.  <command>dhclient</command> has been
+        included in all FreeBSD distributions since 3.2.</para>
+        <indexterm>
+          <primary><application>sysinstall</application></primary>
+        </indexterm>
+
+        <para>DHCP is supported by
+          <application>sysinstall</application>.  When configuring a
+          network interface within
+          <application>sysinstall</application>, the second question
+          asked is: <quote>Do you want to try DHCP configuration of
+          the interface?</quote>. Answering affirmatively will
+          execute <command>dhclient</command>, and if successful, will
+          fill in the network configuration information
+          automatically.</para>
+
+        <para>There are two things you must do to have your system use
+	  DHCP upon startup:</para>
+        <indexterm>
+          <primary>DHCP</primary>
+          <secondary>requirements</secondary>
+        </indexterm>
+	<itemizedlist>
+	  <listitem>
+            <para>Make sure that the <devicename>bpf</devicename>
+	      device is compiled into your kernel.  To do this, add
+	      <literal>device bpf</literal> to your kernel
+	      configuration file, and rebuild the kernel.  For more
+	      information about building kernels, see <xref
+	      linkend="kernelconfig">.</para> <para>The
+	      <devicename>bpf</devicename> device is already part of
+	      the <filename>GENERIC</filename> kernel that is supplied
+	      with FreeBSD, so if you do not have a custom kernel, you
+	      should not need to create one in order to get DHCP
+	      working.</para>
+	    <note>
+	      <para>For those who are particularly security conscious,
+	        you should be warned that <devicename>bpf</devicename>
+		is also the device that allows packet sniffers to work
+		correctly (although they still have to be run as
+		<username>root</username>).  <devicename>bpf</devicename>
+		<emphasis>is</emphasis> required to use DHCP, but if
+		you are very sensitive about security, you probably
+		should not add <devicename>bpf</devicename> to your
+		kernel in the expectation that at some point in the
+		future you will be using DHCP.</para>
+	    </note>
+	  </listitem>
+          <listitem>
+            <para>Edit your <filename>/etc/rc.conf</filename> to
+	      include the following:</para>
+
+            <programlisting>ifconfig_fxp0="DHCP"</programlisting>
+
+            <note>
+              <para>Be sure to replace <literal>fxp0</literal> with the
+                designation for the interface that you wish to dynamically
+                 configure, as described in
+		 <xref linkend="config-network-setup">.</para>
+            </note>
+
+            <para>If you are using a different location for
+              <command>dhclient</command>, or if you wish to pass additional
+              flags to <command>dhclient</command>, also include the
+              following (editing as necessary):</para>
+
+            <programlisting>dhcp_program="/sbin/dhclient"
+dhcp_flags=""</programlisting>
+          </listitem>
+        </itemizedlist>
+
+        <indexterm>
+          <primary>DHCP</primary>
+          <secondary>server</secondary>
+        </indexterm>
+        <para>The DHCP server, <application>dhcpd</application>, is included
+          as part of the <filename
+          role="package">net/isc-dhcp3-server</filename> port in the ports
+          collection.  This port contains the ISC DHCP server and
+          documentation.</para>
+    </sect2>
+
+    <sect2>
+      <title>Files</title>
+      <indexterm>
+        <primary>DHCP</primary>
+        <secondary>configuration files</secondary>
+      </indexterm>
+      <itemizedlist>
+        <listitem><para><filename>/etc/dhclient.conf</filename></para>
+          <para><command>dhclient</command> requires a configuration file,
+            <filename>/etc/dhclient.conf</filename>.  Typically the file
+            contains only comments, the defaults being reasonably sane.  This
+            configuration file is described by the &man.dhclient.conf.5;
+            manual page.</para>
+        </listitem>
+
+        <listitem><para><filename>/sbin/dhclient</filename></para>
+          <para><command>dhclient</command> is statically linked and
+            resides in <filename>/sbin</filename>.  The &man.dhclient.8;
+            manual page gives more information about
+            <command>dhclient</command>.</para>
+        </listitem>
+
+        <listitem><para><filename>/sbin/dhclient-script</filename></para>
+          <para><command>dhclient-script</command> is the FreeBSD-specific
+            DHCP client configuration script.  It is described in
+            &man.dhclient-script.8;, but should not need any user
+            modification to function properly.</para>
+        </listitem>
+
+        <listitem><para><filename>/var/db/dhclient.leases</filename></para>
+          <para>The DHCP client keeps a database of valid leases in this
+            file, which is written as a log.  &man.dhclient.leases.5;
+            gives a slightly longer description.</para>
+        </listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Further Reading</title>
+
+      <para>The DHCP protocol is fully described in
+        <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
+        An informational resource has also been set up at
+        <ulink url="http://www.dhcp.org/"></ulink>.</para>
+    </sect2>
+
+    <sect2 id="network-dhcp-server">
+	<title>Installing and Configuring a DHCP Server</title>
+
+	<sect3>
+	  <title>What This Section Covers</title>
+
+	  <para>This section provides information on how to configure
+	    a FreeBSD system to act as a DHCP server using the ISC
+	    (Internet Software Consortium) implementation of the DHCP
+	    server.</para>
+
+	  <para>The server is not provided as part of
+	    FreeBSD, and so you will need to install the
+	    <filename role="package">net/isc-dhcp3-server</filename>
+	    port to provide this service.  See <xref linkend="ports"> for
+	    more information on using the Ports Collection.</para>
+	</sect3>
+
+	<sect3>
+	  <title>DHCP Server Installation</title>
+	  <indexterm>
+	    <primary>DHCP</primary>
+	    <secondary>installation</secondary>
+	  </indexterm>
+	  <para>In order to configure your FreeBSD system as a DHCP
+	    server, you will need to ensure that the &man.bpf.4;
+	    device is compiled into your kernel.  To do this, add
+	    <literal>device bpf</literal> to your kernel
+	    configuration file, and rebuild the kernel.  For more
+	    information about building kernels, see <xref
+	    linkend="kernelconfig">.</para>
+
+	  <para>The <devicename>bpf</devicename> device is already
+	    part of the <filename>GENERIC</filename> kernel that is
+	    supplied with FreeBSD, so you do not need to create a custom
+	    kernel in order to get DHCP working.</para>
+
+	    <note>
+	      <para>Those who are particularly security conscious
+	        should note that <devicename>bpf</devicename>
+		is also the device that allows packet sniffers to work
+		correctly (although such programs still need privileged
+		access).  <devicename>bpf</devicename>
+		<emphasis>is</emphasis> required to use DHCP, but if
+		you are very sensitive about security, you probably
+		should not include <devicename>bpf</devicename> in your
+		kernel purely because you expect to use DHCP at some
+		point in the future.</para>
+	    </note>
+
+	  <para>The next thing that you will need to do is edit the sample
+	    <filename>dhcpd.conf</filename> which was installed by the
+	    <filename role="package">net/isc-dhcp3-server</filename> port.
+	    By default, this will be
+	    <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and you
+	    should copy this to
+	    <filename>/usr/local/etc/dhcpd.conf</filename> before proceeding
+	    to make changes.</para>
+	</sect3>
+
+	<sect3>
+	  <title>Configuring the DHCP Server</title>
+	  <indexterm>
+	    <primary>DHCP</primary>
+	    <secondary>dhcpd.conf</secondary>
+	  </indexterm>
+	  <para><filename>dhcpd.conf</filename> is
+	    comprised of declarations regarding subnets and hosts, and is
+	    perhaps most easily explained using an example :</para>
+
+	  <programlisting>option domain-name "example.com";<co id="domain-name">
+option domain-name-servers 192.168.4.100;<co id="domain-name-servers">
+option subnet-mask 255.255.255.0;<co id="subnet-mask">
+
+default-lease-time 3600;<co id="default-lease-time">
+max-lease-time 86400;<co id="max-lease-time">
+ddns-update-style none;<co id="ddns-update-style">
+
+subnet 192.168.4.0 netmask 255.255.255.0 {
+  range 192.168.4.129 192.168.4.254;<co id="range">
+  option routers 192.168.4.1;<co id="routers">
+}
+
+host mailhost {
+  hardware ethernet 02:03:04:05:06:07;<co id="hardware">
+  fixed-address mailhost.example.com;<co id="fixed-address">
+}</programlisting>
+
+	  <calloutlist>
+	    <callout arearefs="domain-name">
+	      <para>This option specifies the domain that will be provided
+		to clients as the default search domain.  See
+		&man.resolv.conf.5; for more information on what this
+		means.</para>
+	    </callout>
+
+	    <callout arearefs="domain-name-servers">
+	      <para>This option specifies a comma separated list of DNS
+		servers that the client should use.</para>
+	    </callout>
+
+	    <callout arearefs="subnet-mask">
+	      <para>The netmask that will be provided to clients.</para>
+	    </callout>
+
+	    <callout arearefs="default-lease-time">
+	      <para>A client may request a specific length of time that a
+		lease will be valid.  Otherwise the server will assign
+		a lease with this expiry value (in seconds).</para>
+	    </callout>
+
+	    <callout arearefs="max-lease-time">
+	      <para>This is the maximum length of time that the server will
+		lease for.  Should a client request a longer lease, a lease
+		will be issued, although it will only be valid for
+		<literal>max-lease-time</literal> seconds.</para>
+	    </callout>
+
+	    <callout arearefs="ddns-update-style">
+	      <para>This option specifies whether the DHCP server should
+		attempt to update DNS when a lease is accepted or released.
+		In the ISC implementation, this option is
+		<emphasis>required</emphasis>.</para>
+	    </callout>
+
+	    <callout arearefs="range">
+	      <para>This denotes which IP addresses should be used in
+		the pool reserved for allocating to clients.  IP
+		addresses between, and including, the ones stated are
+		handed out to clients.</para>
+	    </callout>
+
+	    <callout arearefs="routers">
+	      <para>Declares the default gateway that will be provided to
+		clients.</para>
+	    </callout>
+
+	    <callout arearefs="hardware">
+	      <para>The hardware MAC address of a host (so that the DHCP server
+		can recognize a host when it makes a request).</para>
+	    </callout>
+
+	    <callout arearefs="fixed-address">
+	      <para>Specifies that the host should always be given the
+		same IP address.  Note that using a hostname is
+		correct here, since the DHCP server will resolve the
+		hostname itself before returning the lease
+		information.</para>
+	    </callout>
+	  </calloutlist>
+
+	  <para>Once you have finished writing your
+	    <filename>dhcpd.conf</filename>,
+	    you should enable the DHCP server in
+	    <filename>/etc/rc.conf</filename>, i.e. by adding:</para>
+
+	  <programlisting>dhcpd_enable="YES"
+dhcpd_ifaces="dc0"</programlisting>
+
+	  <para>Replace the <literal>dc0</literal> interface name with the
+	    interface (or interfaces, separated by whitespace) that your DHCP
+	    server should listen on for DHCP client requests.</para>
+
+	  <para>Then, you can proceed to start the server by issuing the
+	    following command:</para>
+
+	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd.sh start</userinput></screen>
+
+	  <para>Should you need to make changes to the configuration of your
+	    server in the future, it is important to note that sending a
+	    <literal>SIGHUP</literal> signal to
+	    <application>dhcpd</application> does <emphasis>not</emphasis>
+	    result in the configuration being reloaded, as it does with most
+	    daemons.  You will need to send a <literal>SIGTERM</literal>
+	    signal to stop the process, and then restart it using the command
+	    above.</para>
+	</sect3>
+
+	<sect3>
+	  <title>Files</title>
+	  <indexterm>
+	    <primary>DHCP</primary>
+	    <secondary>configuration files</secondary>
+	  </indexterm>
+	  <itemizedlist>
+	    <listitem><para><filename>/usr/local/sbin/dhcpd</filename></para>
+	      <para><application>dhcpd</application> is statically linked and
+		resides in <filename>/usr/local/sbin</filename>.  The
+		&man.dhcpd.8; manual page installed with the
+		port gives more information about
+		<application>dhcpd</application>.</para>
+	    </listitem>
+
+	    <listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
+	      <para><application>dhcpd</application> requires a configuration
+		file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
+		will start providing service to clients.  This file needs to
+		contain all the information that should be provided to clients
+		that are being serviced, along with information regarding the
+		operation of the server.  This configuration file is described
+		by the &man.dhcpd.conf.5; manual page installed
+		by the port.</para>
+	    </listitem>
+
+	    <listitem><para><filename>/var/db/dhcpd.leases</filename></para>
+	      <para>The DHCP server keeps a database of leases it has issued
+		in this file, which is written as a log.  The manual page
+		&man.dhcpd.leases.5;, installed by the port
+		gives a slightly longer description.</para>
+	    </listitem>
+
+	    <listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
+	      <para><application>dhcrelay</application> is used in advanced
+		environments where one DHCP server forwards a request from a
+		client to another DHCP server on a separate network.  If you
+		require this functionality, then install the <filename
+		role="package">net/isc-dhcp3-relay</filename> port.  The
+		&man.dhcrelay.8; manual page provided with the
+		port contains more detail.</para>
+	    </listitem>
+	  </itemizedlist>
+	</sect3>
+
+      </sect2>
+
+  </sect1>
+
+  <sect1 id="network-dns">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Chern</firstname>
+          <surname>Lee</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	</author>
+
+	<author>
+	  <firstname>Daniel</firstname>
+	  <surname>Gerzo</surname>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Domain Name System (<acronym>DNS</acronym>)</title>
+
+    <sect2>
+      <title>Overview</title>
+      <indexterm><primary>BIND</primary></indexterm>
+
+      <para>&os; utilizes, by default, a version of BIND (Berkeley
+	Internet Name Domain), which is the most common implementation
+	of the <acronym>DNS</acronym> protocol. <acronym>DNS</acronym>
+	is the protocol through which names are mapped to
+	<acronym>IP</acronym> addresses, and vice versa.  For example, a
+	query for <hostid role="fqdn">www.FreeBSD.org</hostid> will
+	receive a reply with the <acronym>IP</acronym> address of The
+	&os; Project's web server, whereas, a query for <hostid
+	role="fqdn">ftp.FreeBSD.org</hostid> will return the
+	<acronym>IP</acronym> address of the corresponding
+	<acronym>FTP</acronym> machine.  Likewise, the opposite can
+	happen.  A query for an <acronym>IP</acronym> address can
+	resolve its hostname.  It is not necessary to run a name server
+	to perform <acronym>DNS</acronym> lookups on a system.</para>
+
+      <para>&os; currently comes with <acronym>BIND</acronym>9
+	<acronym>DNS</acronym> server software by default.  Our
+	installation provides enhanced security features, a new file
+	system layout and automated &man.chroot.8; configuration.</para>
+
+      <indexterm><primary>DNS</primary></indexterm>
+      <para><acronym>DNS</acronym> is coordinated across the Internet
+	through a somewhat complex system of authoritative root, Top
+	Level Domain (<acronym>TLD</acronym>), and other smaller-scale
+	name servers which host and cache individual domain
+	information.</para>
+
+      <para>Currently, BIND is maintained by the
+	Internet Software Consortium
+	<ulink url="http://www.isc.org/"></ulink>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Terminology</title>
+
+      <para>To understand this document, some terms related to
+	<acronym>DNS</acronym> must be understood.</para>
+
+      <indexterm><primary>resolver</primary></indexterm>
+      <indexterm><primary>reverse DNS</primary></indexterm>
+      <indexterm><primary>root zone</primary></indexterm>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <colspec colwidth="1*">
+	  <colspec colwidth="3*">
+
+	  <thead>
+	    <row>
+	      <entry>Term</entry>
+	      <entry>Definition</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>Forward <acronym>DNS</acronym></entry>
+	      <entry>Mapping of hostnames to IP addresses.</entry>
+	    </row>
+
+	    <row>
+	      <entry>Origin</entry>
+	      <entry>Refers to the domain covered in a particular zone
+		file.</entry>
+	    </row>
+
+	    <row>
+	      <entry><application>named</application>, BIND, name server</entry>
+	      <entry>Common names for the BIND name server package within
+		&os;.</entry>
+	    </row>
+
+	    <row>
+	      <entry>Resolver</entry>
+	      <entry>A system process through which a
+		machine queries a name server for zone information.</entry>
+	    </row>
+
+	    <row>
+	      <entry>Reverse <acronym>DNS</acronym></entry>
+	      <entry>The opposite of forward <acronym>DNS</acronym>;
+		mapping of <acronym>IP</acronym> addresses to
+		hostnames.</entry>
+	    </row>
+
+	    <row>
+	      <entry>Root zone</entry>
+
+	      <entry>The beginning of the Internet zone hierarchy.
+		All zones fall under the root zone, similar to how
+		all files in a file system fall under the root
+		directory.</entry>
+	    </row>
+
+	    <row>
+	      <entry>Zone</entry>
+	      <entry>An individual domain, subdomain, or portion of the
+		<acronym>DNS</acronym> administered by the same
+		authority.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <indexterm>
+	<primary>zones</primary>
+	<secondary>examples</secondary>
+      </indexterm>
+
+      <para>Examples of zones:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><hostid>.</hostid> is the root zone.</para>
+	</listitem>
+
+	<listitem>
+	  <para><hostid>org.</hostid> is a Top Level Domain
+	    (<acronym>TLD</acronym>) under the root zone.</para>
+	</listitem>
+
+	<listitem>
+	  <para><hostid role="domainname">example.org.</hostid> is a
+	    zone under the <hostid>org.</hostid>
+	    <acronym>TLD</acronym>.</para>
+	</listitem>
+
+	<listitem>
+	  <para><hostid>1.168.192.in-addr.arpa</hostid> is a zone
+	    referencing all <acronym>IP</acronym> addresses which fall
+	    under the <hostid role="ipaddr">192.168.1.*</hostid>
+	    <acronym>IP</acronym> space.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>As one can see, the more specific part of a hostname appears
+	to its left.  For example, <hostid
+	role="domainname">example.org.</hostid> is more specific than
+	<hostid>org.</hostid>, as <hostid>org.</hostid> is more specific
+	than the root zone.  The layout of each part of a hostname is
+	much like a file system: the
+	<filename role="directory">/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 <acronym>DNS</acronym> information to
+	    the world, replying authoritatively to queries.</para>
+	</listitem>
+
+	<listitem>
+	  <para>A domain, such as <hostid
+	    role="domainname">example.org</hostid>, is registered and
+	    <acronym>IP</acronym> addresses need to be assigned to
+	    hostnames under it.</para>
+	</listitem>
+
+	<listitem>
+	  <para>An <acronym>IP</acronym> address block requires reverse
+	    <acronym>DNS</acronym> entries (<acronym>IP</acronym> to
+	    hostname).</para>
+	</listitem>
+
+	<listitem>
+	  <para>A backup or second name server, called a slave, will
+	    reply to queries.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>A caching name server is needed when:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>A local <acronym>DNS</acronym> server may cache and
+	    respond more quickly than querying an outside name
+	    server.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>When one queries for <hostid
+	role="fqdn">www.FreeBSD.org</hostid>, the resolver usually
+	queries the uplink <acronym>ISP</acronym>'s name server, and
+	retrieves the reply.  With a local, caching
+	<acronym>DNS</acronym> server, the query only has to be made
+	once to the outside world by the caching <acronym>DNS</acronym>
+	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 &os;, the BIND daemon is called
+	<application>named</application> for obvious reasons.</para>
+
+      <informaltable frame="none" pgwide="1">
+	<tgroup cols="2">
+	  <thead>
+	    <row>
+	      <entry>File</entry>
+	      <entry>Description</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry>&man.named.8;</entry>
+	      <entry>The BIND daemon.</entry>
+	    </row>
+
+	    <row>
+	      <entry>&man.rndc.8;</entry>
+	      <entry>Name server control utility.</entry>
+	    </row>
+
+	    <row>
+	      <entry><filename role="directory">/etc/namedb</filename></entry>
+	      <entry>Directory where BIND zone information resides.</entry>
+	    </row>
+
+	    <row>
+	      <entry><filename>/etc/namedb/named.conf</filename></entry>
+	      <entry>Configuration file of the daemon.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </informaltable>
+
+      <para>Depending on how a given zone is configured on the server,
+	the files related to that zone can be found in the <filename
+	role="directory">master</filename>, <filename
+	role="directory">slave</filename>, or <filename
+	role="directory">dynamic</filename> subdirectories of the
+	<filename role="directory">/etc/namedb</filename> directory.
+	These files contain the <acronym>DNS</acronym> information that
+	will be given out by the name server in response to queries.</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>The default <application>named</application> configuration
+	is that of a basic resolving name server, ran in a
+	&man.chroot.8; environment.  To start the server one time with
+	this configuration, use the following command:</para>
+
+      <screen>&prompt.root; <userinput>/etc/rc.d/named forcestart</userinput></screen>
+
+      <para>To ensure the <application>named</application> daemon is
+         started at boot each time, put the following line into the
+         <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>named_enable="YES"</programlisting>
+
+      <para>There are obviously many configuration options for
+	<filename>/etc/namedb/named.conf</filename> that are beyond the
+	scope of this document.  However, if you are interested in the
+	startup options for <application>named</application> on &os;,
+	take a look at the
+	<literal>named_<replaceable>*</replaceable></literal> flags in
+	<filename>/etc/defaults/rc.conf</filename> and consult the
+	&man.rc.conf.5; manual page.  The
+	<xref linkend="configtuning-rcd"> section is also a good read.</para>
+    </sect2>
+
+    <sect2>
+      <title>Configuration Files</title>
+      <indexterm>
+	<primary>BIND</primary>
+	<secondary>configuration files</secondary>
+      </indexterm>
+
+      <para>Configuration files for <application>named</application>
+	currently reside in
+	<filename role="directory">/etc/namedb</filename> directory and
+	will need modification before use, unless all that is needed is
+	a simple resolver.  This is where most of the configuration will
+	be performed.</para>
+
+      <sect3>
+	<title>Using <command>make-localhost</command></title>
+
+	<para>To configure a master zone for the localhost visit the
+	  <filename role="directory">/etc/namedb</filename> directory
+	  and run the following command:</para>
+
+	<screen>&prompt.root; <userinput>sh make-localhost</userinput></screen>
+
+	<para>If all went well, a new file should exist in the
+	  <filename class="directory">master</filename> subdirectory.
+	  The filenames should be <filename>localhost.rev</filename> for
+	  the local domain name and <filename>localhost-v6.rev</filename>
+	  for <acronym>IPv6</acronym> configurations.  As the default
+	  configuration file, required information will
+	  be present in the <filename>named.conf</filename> file.</para>
+      </sect3>
+
+      <sect3>
+	<title><filename>/etc/namedb/named.conf</filename></title>
+
+	<programlisting>// &dollar;FreeBSD&dollar;
+//
+// Refer to the named.conf(5) and named(8) man pages, and the documentation
+// in /usr/share/doc/bind9 for more details.
+//
+// If you are going to set up an authoritative server, make sure you
+// understand the hairy details of how DNS works.  Even with
+// simple mistakes, you can break connectivity for affected parties,
+// or cause huge amounts of useless Internet traffic.
+
+options {
+	directory	"/etc/namedb";
+	pid-file	"/var/run/named/pid";
+	dump-file	"/var/dump/named_dump.db";
+	statistics-file	"/var/stats/named.stats";
+
+// If named is being used only as a local resolver, this is a safe default.
+// For named to be accessible to the network, comment this option, specify
+// the proper IP address, or delete this option.
+	listen-on	{ 127.0.0.1; };
+
+// If you have IPv6 enabled on this system, uncomment this option for
+// use as a local resolver.  To give access to the network, specify
+// an IPv6 address, or the keyword "any".
+//	listen-on-v6	{ ::1; };
+
+// 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
+	    <acronym>IP</acronym> address to a name server at your
+	    uplink.</para>
+	</warning>
+
+	<programlisting>	/*
+	 * If there is a firewall between you and nameservers you want
+	 * to talk to, you might need to uncomment the query-source
+	 * directive below.  Previous versions of BIND always asked
+	 * questions using port 53, but BIND versions 8 and later
+	 * use a pseudo-random unprivileged UDP port by default.
+	 */
+	 // query-source address * port 53;
+};
+
+// If you enable a local name server, don't forget to enter 127.0.0.1
+// first in your /etc/resolv.conf so this server will be queried.
+// 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 "master/localhost.rev";
+};
+
+// RFC 3152
+zone "1.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.ARPA" {
+	type master;
+	file "master/localhost-v6.rev";
+};
+
+// NB: Do not use the IP addresses below, they are faked, and only
+// serve demonstration/documentation purposes!
+//
+// Example slave zone config entries.  It can be convenient to become
+// a slave at least for the zone 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 named after the first bytes of the IP address, in reverse
+// order, with ".IN-ADDR.ARPA" appended.)
+//
+// Before starting to set up a primary zone, make sure you fully
+// understand how DNS and BIND works.  There are sometimes
+// non-obvious pitfalls.  Setting up a slave zone is simpler.
+//
+// NB: Don't blindly enable the examples below. :-)  Use actual names
+// and addresses instead.
+
+/* An example master zone
+zone "example.net" {
+	type master;
+	file "master/example.net";
+};
+*/
+
+/* An example dynamic zone
+key "exampleorgkey" {
+	algorithm hmac-md5;
+	secret "sf87HJqjkqh8ac87a02lla==";
+};
+zone "example.org" {
+	type master;
+	allow-update {
+		key "exampleorgkey";
+	};
+	file "dynamic/example.org";
+};
+*/
+
+/* Examples of forward and reverse slave zones
+zone "example.com" {
+	type slave;
+	file "slave/example.com";
+	masters {
+		192.168.1.1;
+	};
+};
+zone "1.168.192.in-addr.arpa" {
+	type slave;
+	file "slave/1.168.192.in-addr.arpa";
+	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 "master/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/master/example.org</filename>
+	  indicated by the <option>file</option> statement.</para>
+
+	<programlisting>zone "example.org" {
+	type slave;
+	file "slave/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>
+	<indexterm>
+	  <primary>BIND</primary>
+	  <secondary>zone files</secondary>
+	</indexterm>
+	
+	<para>An example master zone file for <hostid
+	  role="domainname">example.org</hostid> (existing within
+	  <filename>/etc/namedb/master/example.org</filename>) is as
+	  follows:</para>
+
+	<programlisting>&dollar;TTL 3600        ; 1 hour
+example.org.    IN      SOA      ns1.example.org. admin.example.org. (
+                                2006051501      ; Serial
+                                10800           ; Refresh
+                                3600            ; Retry
+                                604800          ; Expire
+                                86400           ; Minimum TTL
+                        )
+
+; DNS Servers
+                IN      NS      ns1.example.org.
+                IN      NS      ns2.example.org.
+
+; MX Records
+                IN      MX 10   mx.example.org.
+                IN      MX 20   mail.example.org.
+
+                IN      A       192.168.1.1
+
+; Machine Names
+localhost       IN      A       127.0.0.1
+ns1             IN      A       192.168.1.2
+ns2             IN      A       192.168.1.3
+mx              IN      A       192.168.1.4
+mail            IN      A       192.168.1.5
+
+; Aliases
+www             IN      CNAME   @</programlisting>
+
+        <para>
+          Note that every hostname ending in a <quote>.</quote> is an
+          exact hostname, whereas everything without a trailing
+          <quote>.</quote> is referenced to the origin.  For example,
+          <literal>www</literal> is translated into
+          <literal>www.<replaceable>origin</replaceable></literal>.
+          In our fictitious zone file, our origin is
+          <hostid>example.org.</hostid>, so <literal>www</literal>
+          would translate to <hostid>www.example.org.</hostid>
+        </para>
+
+        <para>
+          The format of a zone file follows:
+        </para>
+        <programlisting>recordname      IN recordtype   value</programlisting>
+
+	<indexterm>
+	  <primary>DNS</primary>
+	  <secondary>records</secondary>
+	</indexterm>
+        <para>
+          The most commonly used DNS records:
+        </para>
+
+	<variablelist>
+	  <varlistentry>
+	    <term>SOA</term>
+
+	    <listitem><para>start of zone authority</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>NS</term>
+
+	    <listitem><para>an authoritative name server</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>A</term>
+
+	    <listitem><para>a host address</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>CNAME</term>
+
+	    <listitem><para>the canonical name for an alias</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>MX</term>
+
+	    <listitem><para>mail exchanger</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term>PTR</term>
+
+	    <listitem><para>a domain name pointer (used in reverse DNS)
+	      </para></listitem>
+	  </varlistentry>
+	</variablelist>
+
+        <programlisting>
+example.org. IN SOA ns1.example.org. admin.example.org. (
+                        2006051501      ; Serial
+                        10800           ; Refresh after 3 hours
+                        3600            ; Retry after 1 hour
+                        604800          ; Expire after 1 week
+                        86400 )         ; Minimum TTL of 1 day</programlisting>
+
+
+
+	<variablelist>
+	  <varlistentry>
+	    <term><hostid role="domainname">example.org.</hostid></term>
+
+	    <listitem><para>the domain name, also the origin for this
+		zone file.</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><hostid role="fqdn">ns1.example.org.</hostid></term>
+
+	    <listitem><para>the primary/authoritative name server for this
+		zone.</para></listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>admin.example.org.</literal></term>
+
+	    <listitem><para>the responsible person for this zone,
+		email address with <quote>@</quote>
+          replaced.  (<email>admin@example.org</email> becomes
+		<literal>admin.example.org</literal>)</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>2006051501</literal></term>
+
+	      <listitem><para>the serial number of the file.  This
+		  must be incremented each time the zone file is
+		  modified.  Nowadays, many admins prefer a
+		  <literal>yyyymmddrr</literal> format for the serial
+		  number.  <literal>2006051501</literal> would mean
+		  last modified 05/15/2006, the latter
+		  <literal>01</literal> being the first time the zone
+		  file has been modified this day.  The serial number
+		  is important as it alerts slave name servers for a
+		  zone when it is updated.</para>
+	      </listitem>
+	  </varlistentry>
+	</variablelist>
+
+        <programlisting>
+       IN NS           ns1.example.org.</programlisting>
+
+        <para>
+          This is an NS entry.  Every name server that is going to reply
+          authoritatively for the zone must have one of these entries.
+        </para>
+
+        <programlisting>
+localhost       IN      A       127.0.0.1
+ns1             IN      A       192.168.1.2
+ns2             IN      A       192.168.1.3
+mx              IN      A       192.168.1.4
+mail            IN      A       192.168.1.5</programlisting>
+
+        <para>
+          The A record indicates machine names.  As seen above,
+          <hostid role="fqdn">ns1.example.org</hostid> would resolve
+          to <hostid role="ipaddr">192.168.1.2</hostid>.
+        </para>
+
+        <programlisting>
+                IN      A       192.168.1.1</programlisting>
+
+	<para>This line assigns IP address
+	  <hostid role="ipaddr">192.168.1.1</hostid> to the current origin,
+	  in this case <hostid role="domainname">example.org</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 <quote>master</quote> machine which name equals
+          to domain name <hostid role="domainname">example.org</hostid>
+          (<hostid role="ipaddr">192.168.1.1</hostid>).
+          CNAMEs can be used to provide alias
+          hostnames, or round robin one hostname among multiple
+          machines.
+        </para>
+
+	<indexterm>
+	  <primary>MX record</primary>
+	</indexterm>
+
+        <programlisting>
+               IN MX   10      mail.example.org.</programlisting>
+
+        <para>
+          The MX record indicates which mail
+          servers are responsible for handling incoming mail for the
+          zone.  <hostid role="fqdn">mail.example.org</hostid> is the
+          hostname of the mail server, and 10 being the priority of
+          that mail server.
+        </para>
+
+        <para>
+          One can have several mail servers, with priorities of 10,
+          20 and so on.  A mail server attempting to deliver to <hostid
+          role="domainname">example.org</hostid> would first try the
+          highest priority MX (the record with the lowest priority
+	  number), then the second highest, etc, until the mail can be
+	  properly delivered.
+        </para>
+
+        <para>
+          For in-addr.arpa zone files (reverse DNS), the same format is
+          used, except with PTR entries instead of
+	  A or CNAME.
+        </para>
+
+        <programlisting>$TTL 3600
+
+1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
+                        2006051501      ; Serial
+                        10800           ; Refresh
+                        3600            ; Retry
+                        604800          ; Expire
+                        3600 )          ; Minimum
+
+        IN      NS      ns1.example.org.
+        IN      NS      ns2.example.org.
+
+1       IN      PTR     example.org.
+2       IN      PTR     ns1.example.org.
+3       IN      PTR     ns2.example.org.
+4       IN      PTR     mx.example.org.
+5       IN      PTR     mail.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>
+      <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>While &os; automatically drops
+	<application>named</application> into a &man.chroot.8;
+	environment; there are several other security mechanisms in
+	place which could help to lure off possible
+	<acronym>DNS</acronym> service attacks.</para>
+
+      <para>It is always good idea to read <ulink
+	url="http://www.cert.org/">CERT</ulink>'s security advisories
+	and to subscribe to the &a.security-notifications; to stay up to
+	date with the current Internet and &os; security issues.</para>
+
+      <tip>
+	<para>If a problem arises, keeping sources up to date and
+	  having a fresh build of <application>named</application> would
+	  not hurt.</para>
+      </tip>
+    </sect2>
+
+    <sect2>
+      <title>Further Reading</title>
+
+      <para>BIND/<application>named</application> manual pages:
+      &man.rndc.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.isc.org/sw/guild/bf/">Official ISC BIND
+	      Forum</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="http://www.nominum.com/getOpenSourceResource.php?id=6">
+	      BIND FAQ</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink url="http://www.oreilly.com/catalog/dns5/">O'Reilly
+	      DNS and BIND 5th Edition</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="ftp://ftp.isi.edu/in-notes/rfc1034.txt">RFC1034
+	      - Domain Names - Concepts and Facilities</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink
+	      url="ftp://ftp.isi.edu/in-notes/rfc1035.txt">RFC1035
+	      - Domain Names - Implementation and Specification</ulink></para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-apache">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Murray</firstname>
+	  <surname>Stokely</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Apache HTTP Server</title>
+
+    <indexterm><primary>web servers</primary>
+      <secondary>setting up</secondary></indexterm>
+    <indexterm><primary>Apache</primary></indexterm>
+
+    <sect2>
+      <title>Overview</title>
+
+      <para>&os; is used to run some of the busiest web sites in the
+        world.  The majority of web servers on the Internet are using
+        the <application>Apache HTTP Server</application>.
+        <application>Apache</application> software packages should be
+        included on your FreeBSD installation media.  If you did not
+        install <application>Apache</application> when you first
+        installed FreeBSD, then you can install it from the <filename
+        role="package">www/apache13</filename> or <filename
+        role="package">www/apache20</filename> port.</para>
+
+      <para>Once <application>Apache</application> has been installed
+        successfully, it must be configured.</para>
+
+      <note><para>This section covers version 1.3.X of the
+        <application>Apache HTTP Server</application> as that is the
+        most widely used version for &os;.  <application>Apache</application>&nbsp;2.X introduces many
+        new technologies but they are not discussed here.  For more
+        information about <application>Apache</application>&nbsp;2.X, please see <ulink
+        url="http://httpd.apache.org/"></ulink>.</para></note>
+
+    </sect2>
+
+    <sect2>
+      <title>Configuration</title>
+
+      <indexterm><primary>Apache</primary>
+	<secondary>configuration file</secondary></indexterm>
+
+      <para>The main <application>Apache HTTP Server</application> configuration file is
+	installed as
+	<filename>/usr/local/etc/apache/httpd.conf</filename> on &os;.
+	This file is a typical &unix; text configuration file with
+	comment lines beginning with the <literal>#</literal>
+	character.  A comprehensive description of all possible
+	configuration options is outside the scope of this book, so
+	only the most frequently modified directives will be described
+	here.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><literal>ServerRoot "/usr/local"</literal></term>
+
+	  <listitem>
+	    <para>This specifies the default directory hierarchy for
+	    the <application>Apache</application> installation.  Binaries are stored in the
+	    <filename class="directory">bin</filename> and 
+	    <filename class="directory">sbin</filename> subdirectories
+	    of the server root, and configuration files are stored in
+	    <filename class="directory">etc/apache</filename>.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>ServerAdmin you@your.address</literal></term>
+
+	  <listitem>
+	    <para>The address to which problems with the server should
+	      be emailed.  This address appears on some
+	      server-generated pages, such as error documents.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>ServerName www.example.com</literal></term>
+
+	  <listitem>
+	    <para><literal>ServerName</literal> allows you to set a host name which is
+	      sent back to clients for your server if it is different
+	      to the one that the host is configured with (i.e., use <hostid>www</hostid>
+	      instead of the host's real name).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>DocumentRoot "/usr/local/www/data"</literal></term>
+
+	  <listitem>
+	    <para><literal>DocumentRoot</literal>: The directory out of which you will
+	      serve your documents. By default, all requests are taken
+	      from this directory, but symbolic links and aliases may
+	      be used to point to other locations.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>It is always a good idea to make backup copies of your
+	<application>Apache</application> configuration file before making changes.  Once you are
+	satisfied with your initial configuration you are ready to
+	start running <application>Apache</application>.</para>
+
+<!-- sect3 for performance tuning directives?  maxservers minservers -->
+<!-- etc..?? -->
+
+<!-- Advanced configuration section.
+
+Performance tuning directives.
+
+Log file format -->
+
+    </sect2>
+
+    <sect2>
+      <title>Running <application>Apache</application></title>
+
+      <indexterm><primary>Apache</primary>
+	<secondary>starting or stopping</secondary></indexterm>
+
+      <para><application>Apache</application> does not run from the
+        <application>inetd</application> super server as many other
+        network servers do.  It is configured to run standalone for
+        better performance for incoming HTTP requests from client web
+        browsers.  A shell script wrapper is included to make
+        starting, stopping, and restarting the server as simple as
+        possible.  To start up <application>Apache</application> for
+        the first time, just run:</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl start</userinput></screen>
+
+      <para>You can stop the server at any time by typing:</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl stop</userinput></screen>
+
+      <para>After making changes to the configuration file for any
+      reason, you will need to restart the server:</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl restart</userinput></screen>
+
+      <para>To restart <application>Apache</application> without
+	aborting current connections, run:</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/sbin/apachectl graceful</userinput></screen>
+
+      <para>Additional information available at
+	&man.apachectl.8; manual page.</para>
+
+      <para>To launch <application>Apache</application> at system
+        startup, add the following line to
+        <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>apache_enable="YES"</programlisting>
+
+      <para>If you would like to supply additional command line
+	options for the <application>Apache</application>
+	<command>httpd</command> program started at system boot, you
+	may specify them with an additional line in
+	<filename>rc.conf</filename>:</para>
+
+      <programlisting>apache_flags=""</programlisting>
+
+      <para>Now that the web server is running, you can view your web
+        site by pointing a web browser to
+        <literal>http://localhost/</literal>.  The default web page
+        that is displayed is
+        <filename>/usr/local/www/data/index.html</filename>.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Virtual Hosting</title>
+
+      <para><application>Apache</application> supports two different
+	types of Virtual Hosting. The first method is Name-based
+	Virtual Hosting. Name-based virtual hosting uses the clients
+	HTTP/1.1 headers to figure out the hostname. This allows many
+	different domains to share the same IP address.</para>
+
+      <para>To setup <application>Apache</application> to use
+        Name-based Virtual Hosting add an entry like the following to
+        your <filename>httpd.conf</filename>:</para>
+
+      <programlisting>NameVirtualHost *</programlisting>
+
+      <para>If your webserver was named <hostid role="fqdn">www.domain.tld</hostid> and
+        you wanted to setup a virtual domain for
+        <hostid role="fqdn">www.someotherdomain.tld</hostid> then you would add
+        the following entries to
+        <filename>httpd.conf</filename>:</para>
+
+      <screen>&lt;VirtualHost *&gt;
+ServerName www.domain.tld
+DocumentRoot /www/domain.tld
+&lt;/VirtualHost&gt;
+
+&lt;VirtualHost *&gt;
+ServerName www.someotherdomain.tld
+DocumentRoot /www/someotherdomain.tld
+&lt;/VirtualHost&gt;</screen>
+
+      <para>Replace the addresses with the addresses you want to use
+        and the path to the documents with what you are using.</para>
+
+      <para>For more information about setting up virtual hosts,
+        please consult the official <application>Apache</application>
+        documentation at: <ulink
+        url="http://httpd.apache.org/docs/vhosts/"></ulink>.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Apache Modules</title>
+
+      <indexterm><primary>Apache</primary>
+	<secondary>modules</secondary></indexterm>
+
+      <para>There are many different <application>Apache</application> modules available to add
+        functionality to the basic server.  The FreeBSD Ports
+        Collection provides an easy way to install
+        <application>Apache</application> together with some of the
+        more popular add-on modules.</para>
+
+      <sect3>
+        <title>mod_ssl</title>
+
+	<indexterm><primary>web servers</primary>
+          <secondary>secure</secondary></indexterm>
+	<indexterm><primary>SSL</primary></indexterm>
+	<indexterm><primary>cryptography</primary></indexterm>
+
+        <para>The <application>mod_ssl</application> module uses the OpenSSL library to provide
+          strong cryptography via the Secure Sockets Layer (SSL v2/v3)
+          and Transport Layer Security (TLS v1) protocols.  This
+          module provides everything necessary to request a signed
+          certificate from a trusted certificate signing authority so
+          that you can run a secure web server on &os;.</para>
+
+	<para>If you have not yet installed
+	  <application>Apache</application>, then a version of <application>Apache</application>
+	  1.3.X that includes <application>mod_ssl</application> may be installed with the <filename
+	  role="package">www/apache13-modssl</filename> port.  SSL
+	  support is also available for <application>Apache</application>&nbsp;2.X in the
+	  <filename role="package">www/apache20</filename> port,
+	  where it is enabled by default.</para>
+
+<!-- XXX add more information about configuring mod_ssl here. -->
+<!-- Generating keys, getting the key signed, setting up your secure -->
+<!-- web server! -->
+      </sect3>
+
+      <sect3>
+        <title>Dynamic Websites with Perl &amp; PHP</title>
+        <para>In the past few years, more businesses have turned to the
+          Internet in order to enhance their revenue and increase
+          exposure.  This has also increased the need for interactive
+          web content.  While some companies, such as &microsoft;, have
+          introduced solutions into their proprietary products, the
+          open source community answered the call.  Two options for
+          dynamic web content include
+          <application>mod_perl</application> &amp;
+          <application>mod_php</application>.</para>
+
+        <sect4>
+        <title>mod_perl</title>
+
+	<indexterm>
+          <primary>mod_perl</primary>
+          <secondary>Perl</secondary>
+        </indexterm>
+
+        <para>The <application>Apache</application>/Perl integration project brings together the
+	  full power of the Perl programming language and the <application>Apache
+	  HTTP Server</application>.  With the <application>mod_perl</application> module it is possible to
+	  write <application>Apache</application> modules entirely in Perl.  In addition, the
+	  persistent interpreter embedded in the server avoids the
+	  overhead of starting an external interpreter and the penalty
+	  of Perl start-up time.</para>
+
+          <para><application>mod_perl</application> is available a few
+            different ways.  To use <application>mod_perl</application>
+            remember that <application>mod_perl</application> 1.0 only
+            works with <application>Apache</application> 1.3 and
+            <application>mod_perl</application> 2.0 only works with
+            <application>Apache</application> 2.
+            <application>mod_perl</application> 1.0 is available in
+            <filename role="package">www/mod_perl</filename> and a
+            statically compiled version is available in
+            <filename role="package">www/apache13-modperl</filename>.
+            <application>mod_perl</application> 2.0 is avaliable in
+            <filename role="package">www/mod_perl2</filename>.</para>
+        </sect4>
+
+        <sect4>
+          <sect4info>
+	  <authorgroup>
+	    <author>
+	      <firstname>Tom</firstname>
+	      <surname>Rhodes</surname>
+	      <contrib>Written by </contrib>
+	    </author>
+	  </authorgroup>
+        </sect4info>
+        <title>mod_php</title>
+
+	<indexterm>
+          <primary>mod_php</primary>
+          <secondary>PHP</secondary>
+        </indexterm>
+
+	<para><acronym>PHP</acronym>, also known as <quote>PHP:
+          Hypertext Preprocessor</quote> is a general-purpose scripting
+          language that is especially suited for Web development.
+          Capable of being embedded into <acronym>HTML</acronym> its
+          syntax draws upon C, &java;, and Perl with the intention of
+          allowing web developers to write dynamically generated
+          webpages quickly.</para>
+
+	<para>To gain support for <acronym>PHP</acronym>5 for the
+	  <application>Apache</application> web server, begin by
+	  installing the
+	  <filename role="package">www/mod_php5</filename>
+	  port.</para>
+
+	<para>This will install and configure the modules required
+          to support dynamic <acronym>PHP</acronym> applications.  Check
+          to ensure the following sections have been added to
+	  <filename>/usr/local/etc/apache/httpd.conf</filename>:</para>
+
+	<programlisting>LoadModule php5_module        libexec/apache/libphp5.so</programlisting>
+
+        <programlisting>AddModule mod_php5.c
+    &lt;IfModule mod_php5.c&gt;
+        DirectoryIndex index.php index.html
+    &lt;/IfModule&gt;
+    &lt;IfModule mod_php5.c&gt;
+        AddType application/x-httpd-php .php
+        AddType application/x-httpd-php-source .phps
+    &lt;/IfModule&gt;</programlisting>
+
+          <para>Once completed, a simple call to the
+            <command>apachectl</command> command for a graceful
+            restart is needed to load the <acronym>PHP</acronym>
+            module:</para>
+
+	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
+
+          <para>The <acronym>PHP</acronym> support in &os; is extremely
+            modular so the base install is very limited.  It is very easy
+            to add support using the
+            <filename role="package">lang/php5-extensions</filename> port.
+            This port provides a menu driven interface to
+            <acronym>PHP</acronym> extension installation.
+            Alternatively, individual extensions can be installed using
+            the appropriate port.</para>
+
+	<para>For instance, to add support for the
+	  <application>MySQL</application> database server to
+	  <acronym>PHP</acronym>5, simply install the
+	  <filename role="package">databases/php5-mysql</filename>
+	  port.</para>
+
+          <para>After installing an extension, the
+            <application>Apache</application> server must be reloaded to
+              pick up the new configuration changes:</para>
+
+	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
+        </sect4>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-ftp">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Murray</firstname>
+	  <surname>Stokely</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>File Transfer Protocol (FTP)</title>
+
+    <indexterm><primary>FTP servers</primary></indexterm>
+
+    <sect2>
+      <title>Overview</title>
+
+      <para>The File Transfer Protocol (FTP) provides users with a
+	simple way to transfer files to and from an <acronym
+	role="File Transfer Protocol">FTP</acronym> server.  &os;
+	includes <acronym role="File Transfer Protocol">FTP</acronym>
+	server software, <application>ftpd</application>, in the base
+	system.  This makes setting up and administering an <acronym
+	role="File Transfer Protocol">FTP</acronym> server on FreeBSD
+	very straightforward.</para>
+    </sect2>
+
+    <sect2>
+      <title>Configuration</title>
+
+      <para>The most important configuration step is deciding which
+	accounts will be allowed access to the FTP server.  A normal
+	FreeBSD system has a number of system accounts used for
+	various daemons, but unknown users should not be allowed to
+	log in with these accounts.  The
+	<filename>/etc/ftpusers</filename> file is a list of users
+	disallowed any FTP access.  By default, it includes the
+	aforementioned system accounts, but it is possible to add
+	specific users here that should not be allowed access to
+	FTP.</para>
+
+      <para>You may want to restrict the access of some users without
+	preventing them completely from using FTP.  This can be
+	accomplished with the <filename>/etc/ftpchroot</filename>
+	file.  This file lists users and groups subject to FTP access
+	restrictions.  The &man.ftpchroot.5; manual page has all of
+	the details so it will not be described in detail here.</para>
+
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
+      <para>If you would like to enable anonymous FTP access to your
+	server, then you must create a user named
+	<username>ftp</username> on your &os; system.  Users will then
+	be able to log on to your FTP server with a username of
+	<username>ftp</username> or <username>anonymous</username> and
+	with any password (by convention an email address for the user
+	should be used as the password).  The FTP server will call
+	&man.chroot.2; when an anonymous user logs in, to restrict
+	access to only the home directory of the
+	<username>ftp</username> user.</para>
+
+      <para>There are two text files that specify welcome messages to
+	be displayed to FTP clients.  The contents of the file
+	<filename>/etc/ftpwelcome</filename> will be displayed to
+	users before they reach the login prompt.  After a successful
+	login, the contents of the file
+	<filename>/etc/ftpmotd</filename> will be displayed.  Note
+	that the path to this file is relative to the login environment, so the
+	file <filename>~ftp/etc/ftpmotd</filename> would be displayed
+	for anonymous users.</para>
+
+      <para>Once the FTP server has been configured properly, it must
+        be enabled in <filename>/etc/inetd.conf</filename>.  All that
+        is required here is to remove the comment symbol
+        <quote>#</quote> from in front of the existing
+        <application>ftpd</application> line :</para>
+
+      <programlisting>ftp	stream	tcp	nowait	root	/usr/libexec/ftpd	ftpd -l</programlisting>
+
+      <para>As explained in <xref linkend="network-inetd-reread">,
+        the <application>inetd</application> configuration must be reloaded
+        after this configuration file is changed.</para>
+
+      <para>You can now log on to your FTP server by typing:</para>
+
+      <screen>&prompt.user; <userinput>ftp localhost</userinput></screen>
+
+    </sect2>
+
+    <sect2>
+      <title>Maintaining</title>
+
+      <indexterm><primary>syslog</primary></indexterm>
+      <indexterm><primary>log files</primary>
+	<secondary>FTP</secondary></indexterm>
+
+      <para>The <application>ftpd</application> daemon uses
+        &man.syslog.3; to log messages.  By default, the system log
+        daemon will put messages related to FTP in the
+        <filename>/var/log/xferlog</filename> file.  The location of
+        the FTP log can be modified by changing the following line in
+        <filename>/etc/syslog.conf</filename>:</para>
+
+      <programlisting>ftp.info      /var/log/xferlog</programlisting>
+
+      <indexterm>
+	<primary>FTP</primary>
+	<secondary>anonymous</secondary>
+      </indexterm>
+
+      <para>Be aware of the potential problems involved with running
+        an anonymous FTP server.  In particular, you should think
+        twice about allowing anonymous users to upload files.  You may
+        find that your FTP site becomes a forum for the trade of
+        unlicensed commercial software or worse.  If you do need to
+        allow anonymous FTP uploads, then you should set up the
+        permissions so that these files can not be read by other
+        anonymous users until they have been reviewed.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="network-samba">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Murray</firstname>
+	  <surname>Stokely</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>File and Print Services for &microsoft.windows; clients (Samba)</title>
+
+    <indexterm><primary>Samba server</primary></indexterm>
+    <indexterm><primary>Microsoft Windows</primary></indexterm>
+    <indexterm>
+      <primary>file server</primary>
+      <secondary>Windows clients</secondary>
+    </indexterm>
+    <indexterm>
+      <primary>print server</primary>
+      <secondary>Windows clients</secondary>
+    </indexterm>
+
+    <sect2>
+      <title>Overview</title>
+
+      <para><application>Samba</application> is a popular open source
+        software package that provides file and print services for
+        &microsoft.windows; clients.  Such clients can connect to and
+        use FreeBSD filespace as if it was a local disk drive, or
+        FreeBSD printers as if they were local printers.</para>
+
+      <para><application>Samba</application> software packages should
+        be included on your FreeBSD installation media.  If you did
+        not install <application>Samba</application> when you first
+        installed FreeBSD, then you can install it from the <filename
+        role="package">net/samba3</filename> port or package.</para>
+
+<!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. -->
+
+    </sect2>
+
+    <sect2>
+      <title>Configuration</title>
+
+      <para>A default <application>Samba</application> configuration
+        file is installed as
+        <filename>/usr/local/etc/smb.conf.default</filename>.  This
+        file must be copied to
+        <filename>/usr/local/etc/smb.conf</filename> and customized
+        before <application>Samba</application> can be used.</para>
+
+      <para>The <filename>smb.conf</filename> file contains runtime
+        configuration information for
+        <application>Samba</application>, such as definitions of the
+        printers and <quote>file system shares</quote> that you would
+        like to share with &windows; clients.  The
+        <application>Samba</application> package includes a web based
+        tool called <application>swat</application> which provides a
+        simple way of configuring the <filename>smb.conf</filename>
+        file.</para>
+
+      <sect3>
+	<title>Using the Samba Web Administration Tool (SWAT)</title>
+
+	<para>The Samba Web Administration Tool (SWAT) runs as a
+	  daemon from <application>inetd</application>.  Therefore, the
+	  following line in <filename>/etc/inetd.conf</filename>
+	  should be uncommented before <application>swat</application> can be
+	  used to configure <application>Samba</application>:</para>
+
+	<programlisting>swat   stream  tcp     nowait/400      root    /usr/local/sbin/swat</programlisting>
+        <para>As explained in <xref linkend="network-inetd-reread">,
+          the <application>inetd</application> must be reloaded after this configuration
+          file is changed.</para>
+
+	<para>Once <application>swat</application> has been enabled in
+	  <filename>inetd.conf</filename>, you can use a browser to
+	  connect to <ulink url="http://localhost:901"></ulink>.  You will
+	  first have to log on with the system <username>root</username> account.</para>
+
+<!-- XXX screenshots go here, loader is creating them -->
+
+	<para>Once you have successfully logged on to the main
+	  <application>Samba</application> configuration page, you can
+	  browse the system documentation, or begin by clicking on the
+	  <guimenu>Globals</guimenu> tab.  The <guimenu>Globals</guimenu> section corresponds to the
+	  variables that are set in the <literal>[global]</literal>
+	  section of
+	  <filename>/usr/local/etc/smb.conf</filename>.</para>
+      </sect3>
+
+      <sect3>
+	<title>Global Settings</title>
+
+	<para>Whether you are using <application>swat</application> or
+	  editing <filename>/usr/local/etc/smb.conf</filename>
+	  directly, the first directives you are likely to encounter
+	  when configuring <application>Samba</application>
+	  are:</para>
+
+        <variablelist>
+	  <varlistentry>
+	    <term><literal>workgroup</literal></term>
+
+	    <listitem>
+	      <para>NT Domain-Name or Workgroup-Name for the computers
+	        that will be accessing this server.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>netbios name</literal></term>
+	    <indexterm><primary>NetBIOS</primary></indexterm>
+
+	    <listitem>
+	      <para>This sets the NetBIOS name by which a <application>Samba</application> server
+		is known. By default it is the same as the first
+		component of the host's DNS name.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>server string</literal></term>
+
+	    <listitem>
+	      <para>This sets the string that will be displayed with
+		the <command>net view</command> command and some other
+		networking tools that seek to display descriptive text
+		about the server.</para>
+	    </listitem>
+	  </varlistentry>
+        </variablelist>
+      </sect3>
+
+      <sect3>
+	<title>Security Settings</title>
+
+	<para>Two of the most important settings in
+	  <filename>/usr/local/etc/smb.conf</filename> are the
+	  security model chosen, and the backend password format for
+	  client users.  The following directives control these
+	  options:</para>
+
+        <variablelist>
+	  <varlistentry>
+	    <term><literal>security</literal></term>
+
+	    <listitem>
+	      <para>The two most common options here are
+	        <literal>security = share</literal> and <literal>security
+	        = user</literal>.  If your clients use usernames that
+	        are the same as their usernames on your &os; machine
+	        then you will want to use user level security.  This
+	        is the default security policy and it requires clients
+	        to first log on before they can access shared
+	        resources.</para>
+
+	      <para>In share level security, client do not need to log
+	        onto the server with a valid username and password
+	        before attempting to connect to a shared resource.
+	        This was the default security model for older versions
+	        of <application>Samba</application>.</para>
+	    </listitem>
+	  </varlistentry>
+
+	  <varlistentry>
+	    <term><literal>passdb backend</literal></term>
+
+	    <indexterm><primary>NIS+</primary></indexterm>
+	    <indexterm><primary>LDAP</primary></indexterm>
+	    <indexterm><primary>SQL database</primary></indexterm>
+
+	    <listitem>
+	      <para><application>Samba</application> has several
+	        different backend authentication models.  You can
+	        authenticate clients with LDAP, NIS+, a SQL database,
+	        or a modified password file.  The default
+	        authentication method is <literal>smbpasswd</literal>,
+	        and that is all that will be covered here.</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+
+	<para>Assuming that the default <literal>smbpasswd</literal>
+	  backend is used, the
+	  <filename>/usr/local/private/smbpasswd</filename> file must
+	  be created to allow <application>Samba</application> to
+	  authenticate clients.  If you would like to give all of
+	  your &unix; user accounts access from &windows; clients, use the
+	  following command:</para>
+
+	<screen>&prompt.root; <userinput>grep -v "^#" /etc/passwd | make_smbpasswd &gt; /usr/local/private/smbpasswd</userinput>
+&prompt.root; <userinput>chmod 600 /usr/local/private/smbpasswd</userinput></screen>
+
+	<para>Please see the <application>Samba</application>
+	  documentation for additional information about configuration
+	  options.  With the basics outlined here, you should have
+	  everything you need to start running
+	  <application>Samba</application>.</para>
+      </sect3>
+
+    </sect2>
+    <sect2>
+      <title>Starting <application>Samba</application></title>
+
+      <para>To enable <application>Samba</application> when your
+        system boots, add the following line to
+        <filename>/etc/rc.conf</filename>:</para>
+
+      <programlisting>samba_enable="YES"</programlisting>
+
+      <para>You can then start <application>Samba</application> at any
+        time by typing:</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba.sh start</userinput>
+Starting SAMBA: removing stale tdbs :
+Starting nmbd.
+Starting smbd.</screen>
+
+      <para><application>Samba</application> actually consists of
+        three separate daemons.  You should see that both the
+        <application>nmbd</application> and <application>smbd</application> daemons
+        are started by the <filename>samba.sh</filename> script.  If
+        you enabled winbind name resolution services in
+        <filename>smb.conf</filename>, then you will also see that
+        the <application>winbindd</application> daemon is started.</para>
+
+      <para>You can stop <application>Samba</application> at any time
+        by typing :</para>
+
+      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba.sh stop</userinput></screen>
+
+      <para><application>Samba</application> is a complex software
+        suite with functionality that allows broad integration with
+        &microsoft.windows; networks.  For more information about
+        functionality beyond the basic installation described here,
+        please see <ulink url="http://www.samba.org"></ulink>.</para>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="network-ntp">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Hukins</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Clock Synchronization with NTP</title>
+
+    <indexterm><primary>NTP</primary></indexterm>
+
+    <sect2>
+      <title>Overview</title>
+
+      <para>Over time, a computer's clock is prone to drift.  The
+	Network Time Protocol (NTP) is one way to ensure your clock stays
+	accurate.</para>
+
+      <para>Many Internet services rely on, or greatly benefit from,
+	computers' clocks being accurate.  For example, a web server
+	may receive requests to send a file if it has been modified since a
+	certain time.  In a local area network environment, it is
+	essential that computers sharing files from the same file
+	server have synchronized clocks so that file timestamps stay
+	consistent.  Services such as &man.cron.8; also rely on
+	an accurate system clock to run commands at the specified
+	times.</para>
+
+      <indexterm>
+	<primary>NTP</primary>
+	<secondary>ntpd</secondary>
+      </indexterm>
+      <para>FreeBSD ships with the &man.ntpd.8; <acronym role="Network
+	Time Protocol">NTP</acronym> server which can be used to query
+	other <acronym role="Network Time Protocol">NTP</acronym>
+	servers to set the clock on your machine or provide time
+	services to others.</para>
+    </sect2>
+
+    <sect2>
+      <title>Choosing Appropriate NTP Servers</title>
+
+      <indexterm>
+	<primary>NTP</primary>
+	<secondary>choosing servers</secondary>
+      </indexterm>
+
+      <para>In order to synchronize your clock, you will need to find
+	one or more <acronym role="Network Time
+	Protocol">NTP</acronym> servers to use.  Your network
+	administrator or ISP may have set up an NTP server for this
+	purpose&mdash;check their documentation to see if this is the
+	case.  There is an <ulink
+	url="http://ntp.isc.org/bin/view/Servers/WebHome">online
+	list of publicly accessible NTP servers</ulink> which you can
+	use to find an NTP server near to you.  Make sure you are
+	aware of the policy for any servers you choose, and ask for
+	permission if required.</para>
+
+      <para>Choosing several unconnected NTP servers is a good idea in
+	case one of the servers you are using becomes unreachable or
+	its clock is unreliable.  &man.ntpd.8; uses the responses it
+	receives from other servers intelligently&mdash;it will favor
+	unreliable servers less than reliable ones.</para>
+    </sect2>
+
+    <sect2>
+      <title>Configuring Your Machine</title>
+
+      <indexterm>
+	<primary>NTP</primary>
+	<secondary>configuration</secondary>
+      </indexterm>
+
+      <sect3>
+	<title>Basic Configuration</title>
+	<indexterm><primary>ntpdate</primary></indexterm>
+
+	<para>If you only wish to synchronize your clock when the
+	  machine boots up, you can use &man.ntpdate.8;.  This may be
+	  appropriate for some desktop machines which are frequently
+	  rebooted and only require infrequent synchronization, but
+	  most machines should run &man.ntpd.8;.</para>
+
+	<para>Using &man.ntpdate.8; at boot time is also a good idea
+	  for machines that run &man.ntpd.8;.  The &man.ntpd.8;
+	  program changes the clock gradually, whereas &man.ntpdate.8;
+	  sets the clock, no matter how great the difference between a
+	  machine's current clock setting and the correct time.</para>
+
+	<para>To enable &man.ntpdate.8; at boot time, add
+	  <literal>ntpdate_enable="YES"</literal> to
+	  <filename>/etc/rc.conf</filename>.  You will also need to
+	  specify all servers you wish to synchronize with and any
+	  flags to be passed to &man.ntpdate.8; in
+	  <varname>ntpdate_flags</varname>.</para>
+      </sect3>
+
+      <sect3>
+	<indexterm>
+	  <primary>NTP</primary>
+	  <secondary>ntp.conf</secondary>
+	</indexterm>
+
+	<title>General Configuration</title>
+
+	<para>NTP is configured by the
+	  <filename>/etc/ntp.conf</filename> file in the format
+	  described in &man.ntp.conf.5;.  Here is a simple
+	  example:</para>
+
+	<programlisting>server ntplocal.example.com prefer
+server timeserver.example.org
+server ntp2a.example.net
+
+driftfile /var/db/ntp.drift</programlisting>
+
+	<para>The <literal>server</literal> option specifies which
+	  servers are to be used, with one server listed on each line.
+	  If a server is specified with the <literal>prefer</literal>
+	  argument, as with <hostid
+	  role="fqdn">ntplocal.example.com</hostid>, that server is
+	  preferred over other servers.  A response from a preferred
+	  server will be discarded if it differs significantly from
+	  other servers' responses, otherwise it will be used without
+	  any consideration to other responses.  The
+	  <literal>prefer</literal> argument is normally used for NTP
+	  servers that are known to be highly accurate, such as those
+	  with special time monitoring hardware.</para>
+
+	<para>The <literal>driftfile</literal> option specifies which
+	  file is used to store the system clock's frequency offset.
+	  The &man.ntpd.8; program uses this to automatically
+	  compensate for the clock's natural drift, allowing it to
+	  maintain a reasonably correct setting even if it is cut off
+	  from all external time sources for a period of time.</para>
+
+	<para>The <literal>driftfile</literal> option specifies which
+	  file is used to store information about previous responses
+	  from the NTP servers you are using.  This file contains
+	  internal information for NTP.  It should not be modified by
+	  any other process.</para>
+      </sect3>
+
+      <sect3>
+	<title>Controlling Access to Your Server</title>
+
+	<para>By default, your NTP server will be accessible to all
+	  hosts on the Internet.  The <literal>restrict</literal>
+	  option in <filename>/etc/ntp.conf</filename> allows you to
+	  control which machines can access your server.</para>
+
+	<para>If you want to deny all machines from accessing your NTP
+	  server, add the following line to
+	  <filename>/etc/ntp.conf</filename>:</para>
+
+        <programlisting>restrict default ignore</programlisting>
+
+        <para>If you only want to allow machines within your own
+	  network to synchronize their clocks with your server, but
+	  ensure they are not allowed to configure the server or used
+	  as peers to synchronize against, add</para>
+
+        <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>
+
+	<para>instead, where <hostid role="ipaddr">192.168.1.0</hostid> is
+	  an IP address on your network and <hostid
+	  role="netmask">255.255.255.0</hostid> is your network's
+	  netmask.</para>
+
+	<para><filename>/etc/ntp.conf</filename> can contain multiple
+	  <literal>restrict</literal> options.  For more details, see
+	  the <literal>Access Control Support</literal> subsection of
+	  &man.ntp.conf.5;.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Running the NTP Server</title>
+
+      <para>To ensure the NTP server is started at boot time, add the
+	line <literal>ntpd_enable="YES"</literal> to
+	<filename>/etc/rc.conf</filename>.  If you wish to pass
+	additional flags to &man.ntpd.8;, edit the
+	<varname>ntpd_flags</varname> parameter in
+	<filename>/etc/rc.conf</filename>.</para>
+
+      <para>To start the server without rebooting your machine, run
+	<command>ntpd</command> being sure to specify any additional
+	parameters from <varname>ntpd_flags</varname> in
+	<filename>/etc/rc.conf</filename>.  For example:</para>
+
+      <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Using ntpd with a Temporary Internet
+	Connection</title>
+
+      <para>The &man.ntpd.8; program does not need a permanent
+	connection to the Internet to function properly.  However, if
+	you have a temporary connection that is configured to dial out
+	on demand, it is a good idea to prevent NTP traffic from
+	triggering a dial out or keeping the connection alive.  If you
+	are using user PPP, you can use <literal>filter</literal>
+	directives in <filename>/etc/ppp/ppp.conf</filename>.  For
+	example:</para>
+
+      <programlisting> set filter dial 0 deny udp src eq 123
+ # Prevent NTP traffic from initiating dial out
+ set filter dial 1 permit 0 0
+ set filter alive 0 deny udp src eq 123
+ # Prevent incoming NTP traffic from keeping the connection open
+ set filter alive 1 deny udp dst eq 123
+ # Prevent outgoing NTP traffic from keeping the connection open
+ set filter alive 2 permit 0/0 0/0</programlisting>
+
+      <para>For more details see the <literal>PACKET
+	FILTERING</literal> section in &man.ppp.8; and the examples in
+	<filename>/usr/share/examples/ppp/</filename>.</para>
+
+      <note>
+	<para>Some Internet access providers block low-numbered ports,
+	  preventing NTP from functioning since replies never
+	  reach your machine.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Further Information</title>
+
+      <para>Documentation for the NTP server can be found in
+	<filename>/usr/share/doc/ntp/</filename> in HTML
+	format.</para>
+    </sect2>
+  </sect1>
+
+</chapter>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->
+<!--  LocalWords:  config mnt www -->
diff --git a/pl_PL.ISO8859-2/books/handbook/pgpkeys/Makefile b/pl_PL.ISO8859-2/books/handbook/pgpkeys/Makefile
new file mode 100644
index 0000000000..7c61203aff
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/pgpkeys/Makefile
@@ -0,0 +1,19 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	pgpkeys/chapter.sgml
+
+PGPKEYS!=	perl -ne 'm/\"([\w-]+.key)\"/ && print "$$1\n"' \
+		    ${DOC_PREFIX}/share/pgpkeys/pgpkeys.ent
+SRCS+=		${PGPKEYS}
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/pgpkeys/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/pgpkeys/chapter.sgml
new file mode 100644
index 0000000000..7c1fc562eb
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/pgpkeys/chapter.sgml
@@ -0,0 +1,50 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+<!--
+
+  Do not edit this file except as instructed by the addkey.sh script.
+
+  See the README file in doc/share/pgpkeys for instructions.
+
+-->
+<appendix id="pgpkeys">
+  <title>PGP Keys</title>
+
+  <indexterm><primary>pgp keys</primary></indexterm>
+  <para>In case you need to verify a signature or send encrypted email
+    to one of the officers or developers a number of keys are provided
+    here for your convenience.  A complete keyring of <hostid role="domainname">FreeBSD.org</hostid>
+    users is available for download from <ulink url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para>
+
+  <sect1 id="pgpkeys-officers">
+    <title>Officers</title>
+
+    &section.pgpkeys-officers;
+  </sect1>
+
+  <sect1 id="pgpkeys-core">
+    <title>Core Team Members</title>
+
+    &section.pgpkeys-core;
+  </sect1>
+
+  <sect1 id="pgpkeys-developers">
+    <title>Developers</title>
+
+    &section.pgpkeys-developers;
+  </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/pl_PL.ISO8859-2/books/handbook/ports/Makefile b/pl_PL.ISO8859-2/books/handbook/ports/Makefile
new file mode 100644
index 0000000000..93280bcae8
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/ports/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	ports/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/ports/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/ports/chapter.sgml
new file mode 100644
index 0000000000..3a9120c972
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/ports/chapter.sgml
@@ -0,0 +1,1489 @@
+<!--
+     The FreeBSD Polish Documentation Project
+
+     $FreeBSD$
+     Original revision: 1.259
+-->
+
+<chapter id="ports">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+        <firstname>Cezary</firstname>
+        <surname>Morga</surname>
+        <contrib>T³umaczy³ </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Instalacja programów: pakiety i porty</title>
+
+  <sect1 id="ports-synopsis">
+    <title>Strzeszczenie</title>
+
+    <indexterm><primary>porty</primary></indexterm>
+    <indexterm><primary>pakiety</primary></indexterm>
+    <para>System FreeBSD rozprowadzany jest wraz z bogat± kolekcj±
+      narzêdzi systemowych. Tym nie mniej, stanowi to absolutne minimum.
+      Szybko pojawia siê bowiem potrzeba zainstalowania dodatkowego
+      oprogramowania, by móc rozpocz±æ prawdziw± pracê z systemem.
+      FreeBSD dostarcza dwóch dope³niaj±cych siê metod instalacji
+      oprogramowania: kolekcjê portów FreeBSD (kompilacja programów
+      ze ¼róde³) i system pakietów (instalacja z gotowych binariów).
+      Ka¿da z tych metod mo¿e zostaæ wykorzystana do intalacji najnowszych
+      wersji ulubionego oprogramowania z lokalnych no¶ników b±d¼
+      bezpo¶rednio z sieci.</para>
+
+    <para>Przeczytawszy ten rozdia³ dowiemy siê:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Jak instalowaæ oprogramowanie innych producentów
+          dostarczane w postaci binarnej.</para>
+      </listitem>
+      <listitem>
+        <para>Jak kompilowaæ oprogrmowanie innych producentów
+          z wykorzystaniem kolekcji portów.</para>
+      </listitem>
+      <listitem>
+        <para>Jak usun±æ poprzednio zainstalowane pakiety b±d¼
+          porty.</para>
+      </listitem>
+      <listitem>
+        <para>Kak zmieniæ domy¶lne warto¶ci wykorzystywane
+          przy kompilacji portów.</para>
+      </listitem>
+      <listitem>
+	<para>Jak odnale¿æ w³a¶ciwe oprogramowanie.</para>
+      </listitem>
+      <listitem>
+        <para>Jak zaktualizaowaæ wykorzystywane aplikacje.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="ports-overview">
+    <title>Omówienie instalacji oprogramowania</title>
+
+    <para>Osoby, które ju¿ wcze¶niej pracowa³y z systemami &unix;
+      wiedz±, ¿e typowy proces instalacji oprogramowania sprowadza
+      siê mniej wiêcej do nastêpuj±cych punktów:</para>
+
+    <procedure>
+      <step>
+        <para>Pobranie programu, który mo¿e byæ rozprowadzany
+          w postaci kodu ¼ród³owego b±d¼ binarnej.</para>
+      </step>
+
+      <step>
+        <para>Rozpakowania programu z formatu w jakim jest
+          rozprowadzany (najcze¶ciej jest to plik tar skompresowany
+          za pomoc± &man.compress.1;, &man.gzip.1; lub
+          &man.bzip2.1;).</para>
+      </step>
+
+      <step>
+        <para>Odnalezienie dokumentacji (najczê¶ciej plik
+          <filename>INSTALL</filename> lub <filename>README</filename>
+          b±d¼ pliki w podkatalogu <filename>doc/</filename>)
+          i zapoznanie siê z instrukcjami instalacji programu.</para>
+      </step>
+
+      <step>
+        <para>Kompilacja programu, je¶li rozprowadzany jest w postaci
+          ¼ród³owej. Mo¿e to wymagaæ równie¿ wykonania dodatkowych
+          czynno¶ci, jak np. edycji pliku <filename>Makefile</filename>
+          b±d¼ uruchomienia skryptu <command>configure</command>.</para>
+      </step>
+
+      <step>
+        <para>Weryfikacja i instalacja aplikacji.</para>
+      </step>
+    </procedure>
+
+    <para>Wszystko to przy za³o¿eniu, ¿e w miêdzy czasie nie pojawi³y
+      siê ¿adne trudno¶ci. Instalacja oprogramowania, które nie by³o
+      przygotowywane z my¶l± o FreeBSD mo¿e wymagaæ nawet modyfikacji
+      kodu ¼ród³owego nim zacznie poprawnie funkcjonowaæ.</para>
+
+    <para>Oczywi¶cie, we FreeBSD mo¿na instalowaæ oprogramowanie
+      <quote>tradycyjnym</quote> sposobem. Jednak¿e system ten
+      posiada dwa rozwi±zania, które potrafi± zaoszczêdziæ mnóstwo
+      czasu i trudu: pakiety i porty. W chwili pisania tego tekstu,
+      dostêpnych za pomoc± tych systemów jest przesz³o &os.numports;
+      aplikacji.</para>
+
+    <para>Dla ka¿dego programu dostêpny jest do pobrania pojedynczy
+      pakiet, który zawiera skompilowane kopie plików aplikacji,
+      zarówno plików uruchomieniowych jak i konfiguracyjnych czy
+      dokumentacji. Pobranym plikiem mo¿na manipulowaæ za pomoc±
+      poleceñ &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;,
+      itp. Nowe programy mo¿na instalowaæ za pomoc± zaledwie
+      jednego polecenia.</para>
+
+    <para>Port natomiast, jest zbiorem plików maj±cych za zadanie
+      zautomatyzowaæ proces kompilacji danego programu z kodu
+      ¼ród³owego.</para>
+
+    <para>O ile typowa kompilacja programu sk³ada siê z wielu czynno¶ci
+      wykonywanych przez u¿ytkownika, o tyle pliki sk³adaj±ce siê na
+      port zawieraj± dostateczn± ilo¶æ informacji aby pozwoliæ
+      systemowi zrobiæ to za nas. Wystarczy wprowadziæ kilka prostych
+      poleceñ a system automatycznie pobierze kod ¼ród³owy programu,
+      rozpakuje, na³o¿y ³atki, skompiluje i zainstaluje za nas.</para>
+
+    <para>Ponadto system portów mo¿e równie¿ pos³u¿yæ do przygotowania
+      pakietów, którymi nastêpnie mo¿na manipulowaæ za pomoc±
+      <command>pkg_add</command> i innymi poleceniami
+      zarz±dzaj±cych pakietami.</para>
+
+    <para>Obydwa systemy potrafi± analizowaæ <emphasis>zale¿no¶ci</emphasis>
+      wystêpuj±ce pomiêdzy aplikacjami. Za³ó¿my, ¿e chcemy zainstalowaæ
+      program, który zale¿y od pewnej biblioteki. Zarówno program jak
+      i biblioteka dostêpne s± w systemach portów i pakietów FreeBSD.
+      Niezale¿nie od tego czy wykorzystamy polecenie <command>pkg_add</command>
+      czy porty, by zainstalowaæ program, to obydwa systemy spostrzeg±,
+      ¿e biblioteka nie zosta³a zainstalowana i automatycznie zainstaluj±
+      najpierw bibliotekê.</para>
+
+    <para>Mo¿na by siê zastanawiaæ dlaczego FreeBSD wykorzystuje obydwa
+      systemy, skoro ich dzia³anie jest tak bardzo podobne. Tak pakiety
+      jak i porty posiadaj± pewne zalety. Który system wykorzystamy zale¿y
+      od naszych w³asnych upodobañ.</para>
+
+    <itemizedlist>
+      <title>Zalety pakietów</title>
+      
+      <listitem>
+        <para>Skompresowany plik pakietu zajmuje z regu³y mniej miejsca
+          ni¿ skompresowany plik zawieraj±cy kod ¼ród³owy.</para>
+      </listitem>
+
+      <listitem>
+        <para>Instalacja pakietów nie wymaga dodatkowej kompilacji.
+          W przypadku du¿ych aplikacji, jak np. <application>Mozilla</application>,
+          <application>KDE</application> czy <application>GNOME</application>
+          mo¿e to byæ istotne. Szczególnie gdy pracuje siê na do¶æ wolnej
+          maszynie.</para>
+      </listitem>
+
+      <listitem>
+        <para>Stosowanie pakietów nie wymaga ¿adnej wiedzy o procesie
+          kompilowania oprogramowania w systemie FreeBSD.</para>
+      </listitem>
+    </itemizedlist>
+
+    <itemizedlist>
+      <title>Zalety portów</title>
+      
+      <listitem>
+        <para>Pakiety s± z regu³y kompilowane z do¶æ typowymi opcjami,
+          poniewa¿ powinny byæ przydatne do wykorzystania na maksymalnej
+          liczbie komputerów. Instaluj±c programy z portów mamy mo¿liwo¶æ
+          <quote>podkrêcenia</quote> opcji kompilacji, by (przyk³adowo)
+          skompilowaæ program zoptymalizowany dla procesorów Pentium IV
+          lub Athlon.</para>
+      </listitem>
+
+      <listitem>
+        <para>Niektóre aplikacje posiadaj± pewne opcje kompilacji
+          zwi±zane z zadaniami, które maja realizowaæ. Przyk³adowo
+          <application>Apache</application> mo¿e zostaæ skompilowany
+          z wieloma róznorodnymi opcjami. Kompiluj±c go z portów nie
+          musimy zgadzaæ siê na domy¶lne opcje mog±c samemu dokonaæ
+          wyboru.</para>
+
+        <para>W niektórych przypadkach dostêpnych jest kilka pakietów
+          tej samej aplikacji skompilowanych z ró¿nymi parametrami.
+          Na przyk³ad program <application>Ghostscript</application>
+          dostêpny jest jako pakiet <filename>ghostscript</filename>
+          oraz <filename>ghostscript-nox11</filename>, zale¿nie od
+          tego czy mamy zainstalowany serwer X11. O ile tego typu
+          rozwi±zania s± teoretycznie mo¿liwe do zrealizowania w
+          systemie pakietów, o tyle staje siê to praktycznie niemo¿liwe
+          gdy aplikacja posiada wiêcej ni¿ kilka ró¿nych opcji
+          kompilacji.</para>
+      </listitem>
+
+      <listitem>
+        <para>Warunki licencji niektórych aplikacji zabraniaj±
+          rozprowadzania w postaci binarnej. Musz± byæ zatem rozprowadzane
+          jako kod ¼ród³owy.</para>
+      </listitem>
+
+      <listitem>
+        <para>Niektórzy nie ufaj± pakietom binarnym. W przypadku
+          kodu ¼ród³owego mo¿na (przynajmniej w teorii) przejrzeæ
+          go i samemu poszukaæ potencjalnych luk.</para>
+      </listitem>
+
+      <listitem>
+        <para>Je¶li posiadamy w³asne ³aty bêdziemy potrzebowali
+          kodu ¼ród³owego aby je nanie¶æ do programu.</para>
+      </listitem>
+
+      <listitem>
+        <para>Jeszcze inni po prostu lubi± mieæ pod rêk± kod ¼ród³owy,
+          by móc go poczytaæ gdy siê nudz±, zmodyfikowaæ czy zapo¿yczyæ
+          pewne rozwi±zania (o ile pozwala na to licencja), itd.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Najlepszym sposobem ¶ledzenia zmian dokonywanych w systemie
+      portów jest zapisanie siê na &a.pl.ports.b; oraz
+      &a.pl.ports-bugs.b;.</para>
+
+    <warning>
+      <para> Przed instalacj± jakiejkolwiek aplikacji nale¿y sprawdziæ
+        na stronie <ulink url="http://vuxml.freebsd.org/"></ulink>
+        czy w danym programie istniej± luki zwi±zane bezpieczeñstem.</para>
+
+      <para>Alternatywnie mo¿emy zainstalowaæ <filename
+	role="package">security/portaudit</filename>, który automatycznie
+        sprawdza wszystkie instalowane programy pod wzglêdem znanych
+        luk bezpieczeñstwa; weryfikowane s± równie¿ porty przed kompilacj±.
+        W miêdzy czasie mo¿na wykorzystaæ polecenie <command>portaudit
+	-F -a</command>, by sprawdziæ zainstalowane ju¿ pakiety.</para>
+    </warning>
+
+    <para>Pozosta³a czê¶æ niniejszego rozdzia³u ma za zadanie wyja¶niæ
+      jak z wykorzystaniem systemu pakietów i portów instalowaæ w systemie
+      FreeBSD oprogramowanie innych producentów.</para>
+  </sect1>
+
+  <sect1 id="ports-finding-applications">
+    <title>Odnalezienie programu dla siebie</title>
+
+    <para>Nim przyst±pimy do instalacji programów musimy wiedzieæ
+      co chcemy zainstalowaæ i jak siê nazywa.</para>
+
+    <para>Lista dostêpnych we FreeBSD programów ro¶nie ca³y czas.
+      Na szczê¶cie jest wiele sposobów na odnalezienie tego czego
+      szukamy:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Na stronie internetowej FreeBSD pod adresem <ulink
+	  url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>
+          znajduje jest aktualna lista dostêpnych programów. Listê mo¿na
+          dowolnie przeszukiwaæ wed³ug kilku kryteriów, np. nazwy (je¶li
+          j± znamy). Mo¿liwe jest równie¿ przejrzenie spisu wszystkich
+          aplikacji znajduj±cych siê w danej kategorii.</para>
+      </listitem>
+
+      <indexterm><primary>FreshPorts</primary></indexterm>
+
+      <listitem>
+        <para>Dziêki stronie FreshPorts (<ulink
+	  url="http://www.FreshPorts.org/"></ulink>) prowadzonej
+          przez Dana Langille'a mo¿liwe jest bie¿±ce ¶ledzenie zmian
+          aplikacji w drzewie portów. Witryna umo¿liwia otrzymywanie
+          informacji drog± emailow± o zmianach w wybranych
+          portach.</para>
+      </listitem>
+
+      <indexterm><primary>FreshMeat</primary></indexterm>
+
+      <listitem>
+        <para>Je¶li nie znamy nazwy programu, który chcemy zainstalowaæ,
+          warto poszukaæ go na stronach pokroju FreshMeat (<ulink
+	  url="http://www.freshmeat.net/"></ulink>) a nastêpnie
+          sprawdziæ na stronie FreeBSD czy zosta³ przygotowany
+          odpowiedni port.</para>
+      </listitem>
+
+      <listitem>
+        <para>Je¶li znamy dok³adn± nazwê portu a chcemy sprawdziæ
+          z jakiej pochodzi kategorii, mo¿na skorzystaæ z polecenia
+          &man.whereis.1;. Wystarczy wpisaæ <command>whereis
+          <replaceable>plik</replaceable></command>, gdzie
+          <replaceable>plik</replaceable> jest nazw± programu, którego
+          poszukujemy. Otrzymany wynik bêdzie postaci:</para>
+
+      <screen>&prompt.root; <userinput>whereis lsof</userinput>
+lsof: /usr/ports/sysutils/lsof</screen>
+
+      <para>Przyk³ad ten informuje nas, ¿e program <command>lsof</command>
+        (narzêdzie systemowe) znajduje siê w katalogu
+	<filename>/usr/ports/sysutils/lsof</filename>.</para></listitem>
+
+      <listitem>
+        <para>Jeszcze innym sposobem na odnalezienie danego portu jest
+          wykorzystanie mechanizmu przeszukiwania kolekcji portów.
+          By skorzystaæ z tej funkcji nale¿y przej¶æ do katalogu
+          <filename>/usr/ports</filename>. Nastêpnie wpisaæ
+          <command>make search
+            name=<replaceable>nazwa-programu</replaceable></command>,
+          gdzie <replaceable>program-name</replaceable> jest nazw±
+          poszukiwanej aplikacji. Przyk³adowo, szukaj±c
+          <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>Czê¶æ wyniku, która nas interesuje to wiersz zaczynaj±cy
+        siê od <quote>Path:</quote>, a okre¶laj±cy lokalizacjê portu.
+        Pozosta³e z uzyskanych w ten sposób informacji nie zostan±
+        tutaj opisane, gdy¿ nie s± potrzebne do instalacji
+        programu.</para>
+
+      <para>Szersze przeszukanie kolekcji portów mo¿liwe jest
+        wykorzystuj±c <command>make
+        search key=<replaceable>zwrot</replaceable></command>,
+        gdzie <replaceable>zwrot</replaceable> jest dowolnym wyrazem.
+        Opcja ta przeszukuje nazwy portów, komentarze, opisy i listy
+        zale¿no¶ci. Moze byæ wykorzystana do odnalezienia portów
+        zwi±zanych z danym zagadnieniem gdy nie znamy nazwy
+        poszukiwanego programu.</para>
+
+      <para>W obydwu przypadkach nie s± rozró¿niane ma³e i du¿e
+        litery w poszukiwanym ci±gu. Szukaj±c zatem <quote>LSOF</quote>
+        oraz <quote>lsof</quote> otrzymamy takie same wyniki.</para>
+      </listitem>
+
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="packages-using">
+    <sect1info>    
+      <authorgroup>
+        <author>
+          <firstname>Chern</firstname>
+	  <surname>Lee</surname>
+	  <contrib>Napisa³ </contrib>
+        </author>
+      </authorgroup>
+    <!-- 30 Mar 2001 -->
+      <authorgroup>
+        <author>
+          <firstname>Aleksander</firstname>
+          <surname>Fafu³a</surname>
+          <contrib>T³umaczy³ </contrib>
+        </author>
+      </authorgroup>
+      <authorgroup>
+        <author>
+          <firstname>Cezary</firstname>
+          <surname>Morga</surname>
+          <contrib>Przek³ad uzupe³ni³ </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Korzystanie z systemu pakietów</title>
+
+    <sect2>
+      <title>Instalacja pakietów</title>
+      <indexterm>
+        <primary>pakiety</primary>
+        <secondary>instalacja</secondary>
+      </indexterm>
+    
+      <indexterm>
+        <primary><command>pkg_add</command></primary>
+      </indexterm>
+      <para>Programu &man.pkg.add.1; mo¿na u¿yæ do instalacji
+        programów zarówno z dysku lokalnego, jak i z sieci.</para>
+
+      <example>
+        <title>Rêczne pobranie pakietu i instalacja lokalna</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>Je¶li nie posiadamy lokalnego ¼ród³a programów (np na
+        p³ytach CD FreeBSD), bêdzie Ci prawdopodobnie ³atwiej u¿yæ komendy
+        &man.pkg.add.1; z opcj± <option>-r</option>. Spowoduje to,
+        ¿e program samodzielnie okre¶li odpowiedni± wersjê oprogramowania
+        dla naszej wersji systemu. Nastêpnie pobierze odpowiedni plik
+        z sieci oraz go zainstaluje.</para>
+
+      <indexterm>
+        <primary><command>pkg_add</command></primary></indexterm>
+      <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen>
+
+      <para>W powy¿szym przyk³adzie program pobierze w³a¶ciwy pakiet
+        i zainstaluje go bez jakiejkolwiek dalszej ingerencji u¿ytkownika.
+        Je¶li chcemy wskazaæ programowi alternatywny serwer lustrzany,
+        nale¿y odpowiednio zdefiniowaæ zmienn± ¶rodowiskow±
+        <envar>PACKAGESITE</envar>. Program  &man.pkg.add.1; do pobierania
+        plików z serwerów wykorzystuje &man.fetch.3;, który z kolei
+        wykorzystuje ró¿norodne zmienne ¶rodowiskowe, m.in.
+        <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar> oraz
+	<envar>FTP_PASSWORD</envar>. Mo¿e siê okazaæ, ¿e bêdziemy musieli
+        zdefiniowaæ niektóre z nich je¶li nasz komputer znajduje siê za
+        zapor± ogniow±, b±d¼ musi korzystaæ z serwera po¶rednicz±cego
+        FTP/HTTP proxy. Wiêcej informacji znale¼æ mo¿na w podrêczniku
+        systemowym programu &man.fetch.3;. Warto zauwa¿yæ, i¿ w
+        powy¿szym przyk³adzie jako nazwê pakietu podano jedynie
+        <literal>lsof</literal> zamiast <literal>lsof-4.56.4</literal>.
+        Przy zdalnym pobieraniu pakietów nie nale¿y podawaæ numeru wersji
+        pakietu. Program &man.pkg.add.1; automatycznie pobie¿e najnowsz±
+        wersjê aplikacji.</para>
+
+      <note>
+        <para>Program &man.pkg.add.1; pobierze najnowsz± wersjie aplikacji
+          jedynie, gdy wykorzystujemy &os.current; albo &os.stable;. W przypadku
+          -RELEASE pobrana zostanie wersja pakietu zbudowana dla danego wydania.
+          Ograniczenie to mo¿na obej¶æ modyfikuj±æ zmienn± ¶rodowiskow±
+          <envar>PACKAGESITE</envar>. Na przyk³ad, je¶li korzystamy z
+          &os;&nbsp;5.4-RELEASE domy¶lnie &man.pkg.add.1; bêdzie pobiera³
+          pakiety z
+          <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-5.4-release/Latest/</literal>.
+          By zmusiæ go do pobierania pakietów zbudowanych dla
+          &os;&nbsp;5-STABLE nale¿y zmodyfikowaæ zmienn± <envar>PACKAGESITE</envar>
+          by wskazywa³a na
+          <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-5-stable/Latest/</literal>.</para>
+      </note>
+
+      <para>Pakiety rozpowszechniane s± w formacie <filename>.tgz</filename>
+        oraz <filename>.tbz</filename>. Mo¿emy je pobraæ z
+        <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
+        w Polsce z <ulink
+          url="ftp://ftp.pl.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>,
+        b±d¼ odnale¼æ na p³ytach CDROM FreeBSD. Ka¿da p³yta z cztero p³ytowej
+        dystrybucji (tak¿e PowerPak'a itp) zawiera pakiety w katalogu
+        <filename>/packages</filename>. Struktura katalogu podobna jest
+        do drzewa portów <filename>/usr/ports</filename>. Ka¿da kategoria ma
+        swój w³asny katalog, ponadto ka¿dy pakiet mo¿e zostaæ odnaleziony
+        w katalogu <filename>All</filename> (Wszystkie).</para>
+
+      <para>Struktura katalogów pakietów jest identyczna wzglêdem
+        struktury katalogów portów. Porty i pakiety kooperuj± za sob±,
+        tworz±c wspólnie ca³y system pakietów/portów.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Zarz±dzanie pakietami</title>
+
+      <indexterm>
+        <primary>pakiety</primary>
+        <secondary>zarz±dzanie</secondary>
+      </indexterm>
+      <para>Narzêdziem s³u¿±cym do przedstawienia informacji
+        o zainstalowanych pakietach oraz wy¶wietlaj±cym ich krótki
+        opis jest &man.pkg.info.1;.</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>Program &man.pkg.version.1; jest natomiast narzêdziem,
+        które podsumowuje wersje wszystkich zainstalowanych pakietów.
+        Porównuje je nastêpnie z tymi które znajduj± siê w drzewie portów.</para>
+      <indexterm>
+        <primary><command>pkg_version</command></primary>
+      </indexterm>
+        <screen>&prompt.root; <userinput>pkg_version</userinput>
+cvsup                       =
+docbook                     =
+...</screen>
+
+      <para>Symbol w drugiej kolumnie okre¶la wiek zainstalowanej wersji
+        oprogramowania wzglêdem wersji odnalezionej w portach.</para>
+
+      <informaltable frame="none" pgwide="1">
+        <tgroup cols="2">
+	  <thead>
+            <row>
+              <entry>Symbol</entry>
+              <entry>Znaczenie</entry>
+            </row>
+          </thead>
+
+ 	  <tbody>
+  	    <row>
+	    <entry>=</entry> <entry>Wersja odnaleziona w portach jest
+              identyczna./entry>
+  	    </row>
+ 
+        <row><entry>&lt;</entry>
+	<entry>Wersja jest starsza, ni¿ ta odnaleziona w portach.</entry>
+	</row>
+
+        <row><entry>&gt;</entry><entry>Zainstalowana wersja jest nowsza,
+            ni¿ znaleziona w portach. (Prawdopodobnie lokalne drzewo portów
+            nie zosta³o zaktualizowane.)</entry></row>
+
+        <row><entry>?</entry><entry>Zainstalowany pakiet nie mo¿e zostaæ
+            odnaleziony w drzewie portów. (Mo¿e to mieæ miejsce np. w sytuacji
+            gdy zainstalowany port zosta³ usuniêty z kolekcji portów, b±d¼
+            zmieni³ nazwê.)</entry></row>
+
+        <row><entry>*</entry><entry>Istnieje wiele wersji tego programu.</entry></row>
+
+	</tbody>
+	</tgroup>
+    </informaltable>
+    </sect2>
+
+    <sect2>
+      <title>Usuwanie pakietów</title>
+      <indexterm>
+        <primary><command>pkg_delete</command></primary>
+      </indexterm>
+      <indexterm>
+        <primary>pakiety</primary>
+        <secondary>usuwanie</secondary>
+      </indexterm>
+      <para>Aby usun±æ uprzednio zainstalowane oprogramowanie u¿yj &man.pkg.delete.1;.</para>
+
+      <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Dodatkowe informacje</title>
+      <para>Wszystkie informacje o pakietach znajduj± siê w katalogu
+        <filename>/var/db/pkg</filename>. Lista zainstalowanych plików,
+        a tak¿e opis ka¿dej paczki mo¿na odnale¼æ w³a¶nie w tym katalogu.
+      </para>
+    </sect2>
+  </sect1>
+  
+  <sect1 id="ports-using">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Aleksander</firstname>
+          <surname>Fafu³a</surname>
+          <contrib>T³umaczy³ </contrib>
+        </author>
+      </authorgroup>
+      <authorgroup>
+        <author>
+          <firstname>Cezary</firstname>
+          <surname>Morga</surname>
+          <contrib>Przek³ad uzupe³ni³ </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <title>Korzystanie z kolekcji portów</title>
+
+    <para>Poni¿szy podrozdzia³ dostarcza podstawowych informacji
+      z zakresu u¿ywania kolekcji portów, w stopniu umo¿liwiaj±cym
+      instalowanie lub odinstalowywanie programów z w³asnego systemu.
+      Szczegó³owy opis parametrów polecenia <command>make</command>
+      i zmiennych ¶rodowiskowych dostêpny jest w podrêczniku
+      systemowym &man.ports.7;.</para>
+
+    <sect2 id="ports-tree">
+      <title>Pozyskanie kolekcji portów</title>
+
+      <para>Zanim zainstalujemy jakikolwiek port, musimy pobraæ
+        kolekcjê portów, która w zasadzie jest zestawem plików
+        <filename>Makefiles</filename>, ³at i opisowych. Kolekcja
+        znajduje siê w katalogu <filename>/usr/ports</filename>.</para>
+
+      <para>W trakcie instalacji FreeBSD, <application>sysinstall</application>
+        zapyta³ czy chcemy zainstalowaæ kolekcjê portów. Je¶li wybrali¶my
+        nie, poni¿sze instrukcje pomog± nam w³asnorêcznie zainstalowaæ
+        kolekcjê portów:</para>
+
+      <procedure>
+        <title>Metoda CVSup</title>
+
+        <para>Jest to prosta i szybka metoda pobrania kolekcji portów
+          wykorzystuj±ca system <application>CVSup</application>.
+          Wiêcej informacji o <application>CVSup</application> dostêpnych
+          jest w podrozdziale <link linkend="cvsup">Korzystanie z
+          CVSup</link>.</para>
+
+	<para>Bardzo wa¿nym jest, aby upewniæ siê, ¿e katalog
+          <filename role="directory">/usr/ports</filename> jest pusty
+          nim po raz pierwszy uruchomimy <application>CVSup</application>!
+          Jesli posiadamy ju¿ kolekcjê portów pozyskan± z innego ¼ród³a
+          <application>CVSup</application> nie usunie nieu¿ywanych
+          plików ³at.</para>
+
+	<step>
+          <para>Zainstaluj pakiet <filename
+	    role="package">net/cvsup-without-gui</filename>:</para>
+
+	  <screen>&prompt.root; <userinput>pkg_add -r cvsup-without-gui</userinput></screen>
+
+          <para>Wiêcej informacji w podrozdziale <link
+	      linkend="cvsup-install">Instalacja CVSup</link> (<xref
+	      linkend="cvsup-install">).</para>
+	</step>
+
+	<step>
+          <para>Uruchom <command>cvsup</command>:</para>
+
+	  <screen>&prompt.root; <userinput>cvsup -L 2 -h <replaceable>cvsup.FreeBSD.org</replaceable> /usr/share/examples/cvsup/ports-supfile</userinput></screen>
+
+	  <para>Warto zast±piæ <replaceable>cvsup.FreeBSD.org</replaceable>
+		  adresem serwera CVSup zlokalizowanego bli¿ej nas. Kompletna lista
+		  serwerów lustrzanych dostêpna jest w podrozdziale
+		  <link linkend="cvsup-mirrors">Serwery lustrzane CVSup</link>
+		  (<xref linkend="cvsup-mirrors">).</para>
+
+	  <note>
+		  <para>Mo¿na wykorzystaæ w³asny plik  <filename>ports-supfile</filename>,
+			  by np. unikn±æ konieczno¶ci podawania adresu serwera
+			  <application>CVSup</application> z linii poleceñ.</para>
+
+	    <procedure>
+	      <step>
+                <para>W takim wypadku, jako u¿ytkownik <username>root</username>,
+                  skopiuj plik
+                  <filename>/usr/share/examples/cvsup/ports-supfile</filename>
+                  do innego katalogu, np. <filename>/root</filename> b±d¼ w³asnego
+                  katalogu domowego.</para>
+	      </step>
+
+	      <step>
+                <para>Zmodyfikuj plik <filename>ports-supfile</filename>.</para>
+	      </step>
+
+	      <step>
+                <para>Zmieñ wpis
+                  <replaceable>CHANGE_THIS.FreeBSD.org</replaceable>na adres
+                  wybranego serwera lustrzanego <application>CVSup</application>.
+                  Kompletna lista serwerów lustrzanych dostêpna jest w podrozdziale
+                  <link linkend="cvsup-mirrors">Serwery lustrzane
+                    CVSup</link> (<xref linkend="cvsup-mirrors">).</para>
+	      </step>
+
+	      <step>
+                <para>Teraz uruchom <command>cvsup</command> u¿ywaj±c
+                  polecenia::</para>
+
+		<screen>&prompt.root; <userinput>cvsup -L 2 <replaceable>/root/ports-supfile</replaceable></userinput></screen>
+	      </step>
+	    </procedure>
+	  </note>
+	</step>
+
+	<step>
+          <para>Pó¼niejsze wpisanie polecenia &man.cvsup.1; spowoduje
+            sprawdzenie zmian dokonanych w kolekcji portów i aktualizacjê
+            lokalnej wersji. Nie spowoduje to natomiast automatycznie ponownego
+            skompilowania wykorzystywanych przez nas portów.</para>
+	</step>
+      </procedure>
+
+      <procedure>
+        <title>Metoda Portsnap</title>
+
+        <para><application>Portsnap</application> jest alternatywnym
+          systemem dystrybucji kolekcji portów. Po raz pierwszy zosta³
+            do³±czony do FreeBSD&nbsp;6.0. W starszych wersjach mo¿e zostaæ
+            zainstalowany z pakietu <filename
+	  role="package">sysutils/portsnap</filename>:</para>
+
+	<screen>&prompt.root; <userinput>pkg_add -r portsnap</userinput></screen>
+
+        <para>Szczegó³owe informacje o mo¿liwo¶ciach programu dostêpne
+          s± w podrozdziale <link linkend="portsnap">Korzystanie z
+            Portsnap</link>.</para>
+
+	<step>
+          <para>Ten punkt mo¿emy pomin±æ je¶li posiadamy &os;&nbsp;6.1-RELEASE
+            b±d¼ najnowsz± wersjê programu <application>Portsnap</application>.
+            Przy pierwszym uruchomieniu programu &man.portsnap.8;  zostanie
+            automatycznie utworzony katalog <filename
+	    role="directory">/usr/ports</filename>. W starszych wersjach programu
+            wymagane jest w³asnorêczne utworzenie katalogu:</para>
+
+	  <screen>&prompt.root; <userinput>mkdir /usr/ports</userinput></screen>
+	</step>
+
+	<step>
+          <para>Pobierz skompresowan± migawkê kolekcji portów do katalogu
+            <filename role="directory">/var/db/portsnap</filename>. Mo¿na nastêpnie
+            zakoñczyæ po³±czenie z Internetem, je¶li jest taka potrzeba.</para>
+
+	  <screen>&prompt.root; <userinput>portsnap fetch</userinput></screen>
+	</step>
+
+	<step>
+          <para>Je¶li uruchamiany <application>Portsnap</application> po raz
+            pierwszy nale¿y rozpakowaæ migawkê do katalogu
+            <filename role="directory">/usr/ports</filename>:
+	  </para>
+
+	  <screen>&prompt.root; <userinput>portsnap extract</userinput></screen>
+
+          <para>Je¶li posiadamy ju¿ kolekcjê portów w <filename
+	    role="directory">/usr/ports</filename> i jedynie j± aktualizujemy,
+            wpisujemy polecenie:</para>
+
+	  <screen>&prompt.root; <userinput>portsnap update</userinput></screen>
+	</step>
+
+      </procedure>
+
+      <procedure>
+        <title>Metoda sysinstall</title>
+
+        <para>Metoda ta instaluje kolekcjê portów z lokalnego no¶nika pos³uguj±c
+          siê programem <application>sysinstall</application>. Zainstalowana
+          zostanie kopia kolekcji z dnia, w którym przygotowana zosta³a dana wersja
+          FreeBSD. Je¶li dysponujemy po³±czeniem z Internetem powinni¶my zawsze
+          stosowaæ jedn± z metod opisanych powy¿ej.</para>
+
+	<step>
+          <para>Uruchom  <command>sysinstall</command> jako u¿ytkownik
+            <username>root</username> (<command>/stand/sysinstall</command>
+            w wersjach &os; starszych ni¿ 5.2):</para>
+
+	  <screen>&prompt.root; <userinput>sysinstall</userinput></screen>
+	</step>
+
+	<step>
+          <para>Przejd¼ w dó³, wybierz <guimenuitem>Configure</guimenuitem>,
+            i naci¶nij <keycap>Enter</keycap>.</para>
+	</step>
+
+	<step>
+          <para>Przejd¼ w dó³, wybierz
+            <guimenuitem>Distributions</guimenuitem> i naci¶nij
+	    <keycap>Enter</keycap>.</para>
+	</step>
+
+	<step>
+          <para>Przejd¼ w dó³ do opcji <guimenuitem>ports</guimenuitem> i naci¶nij
+	    <keycap>Spacjê</keycap>.</para>
+	</step>
+
+	<step>
+          <para>Przejd¼ do góry do opcji <guimenuitem>Exit</guimenuitem> i naci¶nij
+	    <keycap>Enter</keycap>.</para>
+	</step>
+
+	<step>
+          <para>Ustaw wybrany przez siebie typ medium instalacji, jak np. p³ytê CDROM,
+            serwer FTP, itd.</para>
+	</step>
+
+	<step>
+          <para>Przejd¼ do góry do opcji <guimenuitem>Exit</guimenuitem> i naci¶nij
+	    <keycap>Enter</keycap>.</para>
+	</step>
+
+	<step>
+          <para>Naci¶ni <keycap>X</keycap> by wyj¶æ z programu
+	    <application>sysinstall</application>.</para>
+	</step>
+      </procedure>
+    </sect2>
+
+    <sect2 id="ports-skeleton">
+      <title>Instalacja Portów</title>
+
+      <indexterm>
+        <primary>porty</primary>
+        <secondary>instalacja</secondary>
+      </indexterm>
+      <para>Pierwsza rzecz o jakiej nale¿y wspomnieæ omawiaj±c
+        kolekcjê portów, jest <quote>szkielet</quote>. Mówi±c w
+        skrócie, szkielet portu jest minimalnym zestawem plików,
+        które informuj± FreeBSD, jak poprawnie skompilowaæ i
+        zainstalowaæ program. Ka¿dy szkielet portu zawiera:</para>
+
+      <itemizedlist>
+	<listitem>
+          <para>Plik <filename>Makefile</filename>.  Plik ten zawiera
+            ró¿ne dane okre¶laj±ce jak skompilowaæ aplikacjê oraz gdzie
+            j± zainstalowaæ w systemie.</para>
+	</listitem>
+
+	<listitem>
+          <para>Plik <filename>distinfo</filename> Plik ten zawiera informacje
+            dotycz±ce plików, które musz± zostaæ pobrane, by skompilowaæ
+            port. Ponadto zawiera sumy kontrolne, na podstawie których
+            &man.md5.1; potrafi sprawdziæ, czy pliki nie uleg³y uszkodzeniu
+            w trakcie pobierania z sieci.</para>
+	</listitem>
+	
+	<listitem>
+          <para>Katalog <filename>files</filename>, który zawiera ³aty
+            pozwalaj±ce skompilowaæ i zainstalowaæ program w naszym
+            systemie FreeBSD. £aty s± ma³ymi plikami, w których okre¶lone
+            s± zmiany dotycz±ce konkretnych plików. S± to pliki tekstowe i po
+            prostu mówi± <quote>Usuñ liniê 10</quote> lub <quote>Zmieñ liniê
+              26 na to: ...</quote>. £atki s± tak¿e znane jako <quote>diffs</quote>
+            (ang. skrót od ró¿nice) poniewa¿ s± generowane przez program
+            &man.diff.1;.</para>
+
+          <para>Ten katalog mo¿e zawieraæ tak¿e inne pliki u¿ywane do
+            kompilacji portu.</para>
+	</listitem>
+
+	<listitem>
+          <para>Plik opisu <filename>pkg-descr</filename>. Jest to bardziej
+            szczegó³owy, nierzadko wieloliniowy opis programu.</para>
+	</listitem>
+	
+	<listitem>
+          <para>Plik listy <filename>pkg-plist</filename>.  Jest to lista wszystkich
+            plików, które zostan± zainstalowane przez port. Jest to tak¿e lista plików,
+            które nale¿y usun±æ w przypadku odinstalowywania.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Niekiedy porty zawieraj± równie¿ inne pliki, jak na przyk³ad
+        <filename>pkg-message</filename> (message-wiadomo¶æ).
+        System portów u¿ywa tych plików w specjalnych sytuacjach. Je¶li potrzebujesz
+        wiêcej informacji na temat tych plików i portów w ogóle, zajrzyj do podrêcznika
+        <ulink url="&url.books.porters-handbook;/index.html">FreeBSD
+          Porter's Handbook</ulink>.</para>
+
+      <para>Jak ju¿ raz powiedziano, porty zawieraj± instrukcje odno¶nie
+        kompilacji programów z kodu ¼ród³owego. Jednak¿e nie zawieraj±
+        one samego kodu. Kod pobraæ mo¿na z p³yty CD b±d¼ z Internetu.
+        Rozprowadzany mo¿e byæ w dowolnej postaci jak± wybierze sobie
+        jego producent, przy czym najczê¶ciej jest to spakowany plik tar
+        skompresowany dodatkowo gzipem. Kod ¼ród³owy programu nazywany
+        jest <quote>distfile</quote>. Poni¿ej przedstawione zosta³y dwie
+        metody instalacji portów we &os;.</para>
+
+      <note>
+        <para> By móc zainstalowaæ port musimy byæ zalogowania jako
+          u¿ytkownik <username>root</username>.</para>
+      </note>
+
+      <warning>
+        <para> Przed instalacj± jakiegokolwiek portu nale¿y upewniæ siê,
+          ¿e dysponujemy aktualn± kolekcj± portów oraz sprawdziæ potencjalne
+          luki bezpieczeñstwa zwi±zane z danym portem na stronie <ulink
+	  url="http://vuxml.freebsd.org/"></ulink>.</para>
+
+        <para>Istnieje mo¿liwo¶æ zautomatyzowania procesu weryfikacji
+          potencjalnych luk bezpieczeñstwa przed instalacj± portu. Do tego
+          celu mo¿na wykorzystaæ program <application>portaudit</application>,
+          dostêpny równie¿ w kolekcji portów (<filename
+	  role="package">security/portaudit</filename>). Wydanie polecenia
+          <command>portaudit -F</command> przed instalacj± nowego portu
+          spowoduje pobranie aktualnej bazy luk bezpieczeñstwa. Mo¿liwe jest
+          równie¿ wykonywanie regularnych aktualizacji bazy i rewizji
+          zainstalowanego oprogramowania w trakcie codziennego przegl±du
+          bezpieczeñstwa systemu. Wiêcej informacji dostêpnych jest na stronach
+          podrêcznika systemowego &man.portaudit.1; i &man.periodic.8;.</para>
+      </warning>
+
+      <para>Sposób funkcjonowania kolekcji portów wi±¿e siê z za³o¿eniem,
+        ¿e posiadamy po³±czenie z Internetem. Je¶li nie, bêdziemy musieli
+        rêcznie pobieraæ kod ¼ród³owy <quote>distfile</quote> i umieszczaæ
+        w katalogu <filename>/usr/ports/distfiles</filename> dla ka¿dego
+        instalowanego portu.</para>
+
+	<para>By rozpocz±æ instalacjê nale¿y przej¶æ do katalogu
+          wybranego portu:</para>
+
+        <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen>
+
+        <para>Wewn±trz katalogu <filename>lsof</filename> znajduje siê
+          szkielet portu. Nastêpnym krokiem jest kompilacja programu, co
+          sprowadza siê do wpisania polecenia <command>make</command>.
+          Efekt dzia³ania polecenia powinien byæ zbli¿ony do:</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 ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/.
+===&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>Po skoñczeniu kompilacji powracamy do linii poleceñ.
+          Kolejnym krokiem jest instalacja portu poprzez wpisanie polecenia
+          <command>make</command> wraz ze s³owem
+          <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>Gdy ponownie powrócimy do linii poleceñ, powinni¶my
+          byæ ju¿ w stanie uruchomiæ w³a¶nie zainstalowan± aplikacjê.
+          Ostrze¿enie jakie pojawi siê na ekranie zwi±zane jest z faktem,
+          ¿e lsof jest programem pracuj±cym ze zwiêkszonymi przywilejami.
+          W trakcie kompilacji i instalacji portów powinni¶my zwracaæ uwagê
+          na wszystkie pojawiaj±ce siê ostrze¿enia.</para>
+
+        <para>Dobrym pomys³em, jest równie¿ usuniêcie podkatalogu
+          zawieraj±cego wszystkie tymczasowe pliki wykorzystywane
+          w trakcie kompilacji. Nie tylko dlatego, ¿e niepotrzebnie zajmuje
+          miejsce na dysku, ale równie¿ dlatego, ¿e mo¿e byæ przyczyn±
+          problemów podczas aktualizacji programu do nowszej wersji.</para>
+
+	<screen>&prompt.root; <userinput>make clean</userinput>
+===&gt;  Cleaning for lsof-4.57
+&prompt.root;</screen>
+
+        <note>
+          <para>Mo¿na sobie oszczêdziæ dwóch naddatkowych kroków wpisuj±c
+            od razu <command>make install clean</command> zamiast trzech
+            osobnych poleceñ <command>make</command>,
+	    <command>make install</command> oraz
+            <command>make clean</command>.</para>
+	</note>
+
+	<note>
+          <para>Niektóre pow³oki utrzymuj± bufor listy poleceñ
+            z katalogów znajduj±cych siê w zmiennej ¶rodowiskowej
+            <envar>PATH</envar>. Ma to za zadanie przy¶pieszyæ
+            wyszukiwanie plików binarnych tych¿e poleceñ.
+            Je¶li korzystamy z jednej z takich w³a¶nie pow³ok
+            mo¿e okazaæ siê niezbêdnym wydaæ polecenie
+            <command>rehash</command> po instalacji portu,
+            nim bêdziemy mogli wykorzystaæ nowo zainstalowany
+            program. Polecenie to dostêpne jest przy wykorzystaniu
+            pow³oki typu <command>tcsh</command>. Natomiast
+            dla pow³oki typu <command>sh</command> odpowiednikiem
+            jest <command>hash -r</command>. Wiêcej informacji
+            dostêpnych jest w dokumentacji pow³oki.</para>
+	</note>
+
+        <para>Niektóre wydawnictwa na p³ytach DVD-ROM, jak np. FreeBSD
+          Toolkit z <ulink url="http://www.freebsdmall.com/">FreeBSD
+	  Mall</ulink>, zawieraj± ¼ród³a distfile. Mog± byæ one
+          wykorzystane z kolekcj± portów. Wystarczy zamontowaæ p³ytê
+          DVD w <filename>/cdrom</filename>. Je¶li natomiast u¿ywamy
+          innego punktu montowania dla p³yt musimy zmodyfikowaæ zmienn±
+          <makevar>CD_MOUNTPTS</makevar> by wskazywa³a na w³a¶ciwe
+          miejsce. Niezbêdne ¼ród³a distfile zostan± automatycznie
+          wykorzystane je¶li znajduj± siê na p³ycie.</para>
+
+	<note>
+          <para>Mimo wszystko nale¿y mieæ w pamiêci, ¿e licencje
+            nielicznych portów nie zezwalaj± na za³±czenie ich na
+            p³ycie CD-ROM. Mo¿e to byæ np. z powodu konieczno¶ci
+            wcze¶niejszej rejestracji przed pobraniem ¼róde³ b±d¼
+            ich redystrybucja nie jest dozwolona. Je¶li chcemy
+            zainstalowaæ port, który nie znajduje siê na p³ycie
+            CD musimy mieæ po³±czenie z Internetem.</para>
+	</note>
+
+        <para>System portów do pobierania plików wykorzystuje
+          program &man.fetch.1;, który z kolei potrafi korzystaæ
+          z wielu zmiennych ¶rodowiskowych, m.in.
+          <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>
+	  czy <envar>FTP_PASSWORD</envar>. Je¶li znajdujemy siê
+          za zapor± ogniow±, b±d¼ musimy korzystaæ z serwera
+          po¶rednicz±cego FTP/HTTP proxy, mo¿e siê okazaæ,
+          ¿e bêdziemy musieli ustawiæ niektóre z tych zmiennych.
+          Kompletna lista wykorzystywanych zmiennych dostêpna
+          jest w podrêczniku systemowym &man.fetch.3;.</para>
+
+        <para>Dla u¿ytkowników nie mog±cych byæ ca³y czas po³±czonych
+          z Internetem dostêpne jest polecenie
+          <command>make <maketarget>fetch</maketarget></command>.
+          Wystarczy wpisaæ to polecenie znajduj±c siê w g³ównym
+          katalogu drzewa portów (<filename>/usr/ports</filename>)
+          a wymagane pliki zostan± automatycznie pobrane. Polecenie
+          to bêdzie równie¿ funkcjonowaæ w podkatalogach, np.
+          <filename>/usr/ports/net</filename>. Jednak¿e, w takiej
+          sytuacji <emphasis>nie</emphasis> zostan± automatycznie
+          pobrane ¼ród³a bibliotek, od których zale¿y dany port.
+          Zamieniaj±c parametr <maketarget>fetch</maketarget> na
+          <maketarget>fetch-recursive</maketarget> spowodujemy
+          pobranie równie¿ ¼róde³ wszystkich portów, od których
+          zale¿y instalowany program.</para>
+
+        <note><para>Mo¿liwe jest kompilowanie ka¿dego portu z osobna
+          w danej kategorii, b±d¼ wszystkich na raz poprzez polecenie
+          <command>make</command> wykonane, analogicznie do
+          <command>make <makevar>fetch</makevar></command>,
+          w g³ównym katalogu kategorii. Jednak¿e jest to niebezpieczna
+          metoda, gdy¿ niektóre porty nie mog± jednocze¶nie funkcjonowaæ
+          w systemie, b±d¼ mog± zainstalowaæ ró¿ne pliki o tej samej
+          nazwie.</para></note>
+
+	<para>W naprawdê ¿adkich przypadkach, u¿ytkownicy mog± pozyskaæ
+          pliki distfile z innego ¼ród³a ni¿ <makevar>MASTER_SITES</makevar>
+          (miejsce sk±d je pobiera system portów). Opcjê
+          <makevar>MASTER_SITES</makevar> mo¿na zast±piæ za
+          pomoc± nastêpuj±cego polecenia:</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>
+
+	<para>W tym przyk³adzie zast±pili¶my opcjê
+          <makevar>MASTER_SITES</makevar> adresem <hostid
+	  role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para>
+
+        <note><para>Niektóre porty umo¿liwiaj± (a nawet wymagaj±)
+          podanie pewnych opcji kompilacji, które mog± w³±czyæ
+          b±d¼ wy³±czyæ nie potrzebne czê¶ci aplikacji, pewne
+          opcje bezpieczeñstwa i inne parametry. Z przychodz±cych
+          na my¶l tego typu programów to
+          <filename role="package">www/mozilla</filename>, <filename
+          role="package">security/gpgme</filename> oraz <filename
+	  role="package">mail/sylpheed-claws</filename>. Za ka¿dym
+          razem gdy dostêpne bêd± tego typu opcje wy¶wietlony
+          zostanie komunikat.</para></note>
+
+      <sect3>
+        <title>Ignorowanie domy¶lnych katalogów portów</title>
+
+        <para>Czasami okazuje siê byæ przydatne (a nawet wymagane)
+          by skorzystaæ z innych katalogów tymczasowych i docelowych.
+          Domy¶lne katalogi mo¿na zast±piæ wykorzystuj±c zmienne
+          <makevar>WRKDIRPREFIX</makevar> i <makevar>PREFIX</makevar>.
+          Na przyk³ad:</para>
+
+	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen>
+
+        <para>spowoduje skompilowanie portu w katalogu
+          <filename>/usr/home/example/ports</filename> i instalacjê
+          w podkatalogach <filename>/usr/local</filename>.</para>
+
+	<screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen>
+
+        <para>spowoduje natomiast kompilacjê w katalogu
+          <filename>/usr/ports</filename> oraz instalacjê
+          w podkatalogach
+	  <filename>/usr/home/example/local</filename>.</para>
+
+        <para>I oczywi¶cie,</para>
+
+	<screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen>
+
+        <para>spowoduje po³±cznie obydwu powy¿szych
+          ustawien (jest to za d³ugie by ca³kowicie zmie¶ci³o
+          siê na stronie, ale powinno daæ ogólne wyobra¿enie).</para>
+
+        <para>Alternatywnie, obydwie zmienne mog± byæ
+          równie¿ okre¶lone jako zmienne ¶rodowiskowe.
+          Informacje o definiowaniu zmiennych ¶rodowiskowych
+          dostêpne s± w podrêczniku systemowym naszej
+          pow³oki.</para>
+      </sect3>
+
+      <sect3>
+        <title>Jak poradziæ sobie z <command>imake</command></title>
+
+        <para>Niektóre porty wykorzystuj±ce <command>imake</command>
+          (czê¶æ Systemu okien X) nie wspó³pracuj± ze zmienn±
+          <makevar>PREFIX</makevar> i mimo wszystko bêd±
+          instalowa³y programy w <filename>/usr/X11R6</filename>.
+          Podobnie niektóre z portów napisanych w jêzyku Perl
+          ingoruj± zmienn± <makevar>PREFIX</makevar>
+          i instaluj± programy w g³ównym drzewie Perla.
+          Zmuszenie tych portów do wspó³pracy ze zmienn±
+          <makevar>PREFIX</makevar> jest niezmiernie trudne,
+          albo wrêcz niemo¿liwe.</para>
+
+      </sect3>
+    </sect2>
+
+    <sect2 id="ports-removing">
+      <title>Usuwanie zainstalowanych portów</title>
+
+      <indexterm>
+        <primary>porty</primary>
+        <secondary>usuwanie</secondary>
+      </indexterm>
+      <para>Teraz, gdy wiesz ju¿ jak instalowaæ porty,
+        zastanawiasz siê prawdopodobnie jak je usuwaæ,
+        na przyk³ad w wypadku, gdy zainstalowali¶my port,
+        ale okaza³o siê jednak, ¿e to nie by³ ten którego
+        szukali¶my. W ramach przyk³adu usuniemy port,
+        który instalowali¶my poprzednio (dla tych którzy
+        nie uwa¿aj±, by³ to <command>lsof</command>).
+        Podobnie jak w przypadku pakietów (szerzej opisane
+        w podrozdziale traktuj±cym o <link
+	linkend="packages-using">pakietach</link>),
+        równie¿ porty usuwane s± za pomoc± polecenia
+        &man.pkg.delete.1;:</para>
+
+      <screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen>
+
+    </sect2>
+
+    <sect2 id="ports-upgrading">
+      <title>Aktualizacja portów</title>
+
+      <indexterm>
+	<primary>porty</primary>
+	<secondary>aktualizacja</secondary>
+      </indexterm>
+      <para>Na wstêpie musimy wy¶wietliæ zdezaktualizowane porty w kolekcji.
+        Wykorzystamy do tego polecenie &man.pkg.version.1;:</para>
+
+      <screen>&prompt.root; <userinput>pkg_version -v</userinput></screen>
+
+      <sect3 id="ports-file-updating">
+	<title><filename>/usr/ports/UPDATING</filename></title>
+
+        <para>Po zaktualizowaniu kolekcji, a przed prób± aktualizacji
+          jakichkolwiek portów, nale¿y zapoznaæ siê z zawarto¶ci± pliku
+          <filename>/usr/ports/UPDATING</filename>. Plik ten opisuje
+          ró¿ne zagadnienia i dodatkowe kroki, na które mo¿na natkn±æ
+          siê i bêdzie trzeba wykonaæ podczas aktualizacji, np.
+          zmiany formatu plików czy zmiany w lokalizacji plików
+          konfiguracyjnych.</para>
+
+	<para>Je¶li opis w pliku <filename>UPDATING</filename> mówi co¶ innego
+          ni¿ ten tekst, nale¿y zastosowaæ siê do opisu.</para>
+      </sect3>
+
+      <sect3 id="portupgrade">
+        <title>Aktualizacja portów z wykorzystaniem programu Portupgrade</title>
+
+	<indexterm>
+	  <primary>portupgrade</primary>
+	</indexterm>
+
+        <para>Program <application>portupgrade</application> zosta³
+          zaprojektowany by u³atwiæ aktualizacjê zainstalowanych w
+          systemie portów. Dostêpny jest z portu <filename
+	  role="package">sysutils/portupgrade</filename>.
+          Jego instalacja przebiega dok³adnie tak samo, jak ka¿dego
+          innego portu, wykorzystuj±c polecenie
+          <command>make <makevar>install
+          clean</makevar></command> command:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/portupgrade</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+      <para>Przeskanujmy nastêpnie listê zainstalowanych portów
+        za pomoc± polecenia <command>pkgdb -F</command> i usuñmy
+        wszystkie niezgodno¶ci jakie nam zwróci skanowanie.
+        Regularne skanowanie przed ka¿d± aktualizacj± jest
+        zdecydowanie dobrym pomys³em.</para>
+
+      <para>Wydanie polecenia <command>portupgrade -a</command>
+        spowoduje, ¿e program <application>portupgrade</application>
+        rozpocznie aktualizacjê wszystkich przedawnionych portów
+        zainstalowanych w naszym systemie. Parametr <option>-i</option>
+        pozwoli przej¶æ w tryb interaktywny, gdzie bêdziemy musieli
+        potwierdziæ aktualizacjê ka¿dego portu.</para>
+
+      <screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen>
+
+      <para>By zaktualizowaæ jedynie wybran± aplikacjê zamiast wszystkich
+        portów nale¿y wykorzystaæ polecenie <command>portupgrade
+	<replaceable>nazwa_programu</replaceable></command>.
+        Opcja <option>-R</option> oznacza, ¿e portupgrade powinien
+        najpierw zaktualizowaæ wszystkie porty, od których
+        zale¿y dany program.</para>
+
+      <screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen>
+
+      <para>By do instalacji wykorzystaæ pakiety zamiast portów
+        nale¿y dodaæ parametr <option>-P</option>. Wówczas
+        <application>portupgrade</application> przeszuka katalogi
+        zawarte w zmiennej <envar>PKG_PATH</envar>. Je¶li pakiet
+        nie zostanie odnaleziony lokalnie zostanie pobrany z Internetu.
+        Je¶li nie bêdzie mo¿liwe ¿adne z powy¿szych, wówczas
+        <application>portupgrade</application> wykorzystan do
+        aktualizacji porty. By temu zapobiec nale¿y zastosowaæ
+        parametr <option>-PP</option>.</para>
+
+      <screen>&prompt.root; <userinput>portupgrade -PR gnome2</userinput></screen>
+
+      <para>Aby pobraæ jedynie pliki ¼ród³owe distfiles
+        (b±d¼ pakiety, gdy wykorzystamy opcjê <option>-P</option>)
+        bez kompilacji czy instalacji czegokolwiek nale¿y u¿yæ
+        parametru <option>-F</option>. Wiêcej informacji
+        dostepnych jest w &man.portupgrade.1;.</para>
+      </sect3>
+
+      <sect3 id="portmanager">
+        <title>Aktualizacja portów z wykorzystaniem programu Portmanager</title>
+
+	<indexterm>
+	  <primary>portmanager</primary>
+	</indexterm>
+
+        <para>Kolejnym narzêdziem u³atwiaj±cym aktualizacjê zainstalowanych
+          portów jest <application>Portmanager</application>, dostêpny z portu
+	  <filename role="package">sysutils/portmanager</filename>:</para>
+
+	<screen>&prompt.root; <userinput>cd <filename role="directory">/usr/ports/sysutils/portmanager</filename></userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+	<para>Wszystkie zainstalowane porty mog± zostaæ zaktualizowane
+          za pomoc± polecenia:</para>
+
+	<screen>&prompt.root; <userinput>portmanager -u</userinput></screen>
+
+        <para>Wykorzystuj±c parametr <option>-ui</option> przechodzimy w tryb
+          interaktywny, gdzie bêdziemy pytani o potwierdzenie ka¿dej operacji
+          wykonywanej przez <application>Portmanager</application>.
+          Program ten mo¿e byæ z równym powodzeniem wykorzystywany do instalacji
+          nowych portów w systemie. W przeciwieñstwe do polecenia
+          <command>make install clean</command> program
+          <application>Portmanager</application> zaktualizuje wszystkie
+          zale¿no¶ci nim skompiluje i zainstaluje wybrany port.</para>
+
+	<screen>&prompt.root; <userinput>portmanager <replaceable>x11/gnome2</replaceable></userinput></screen>
+
+        <para>Gdy wyst±pi± problemy z zale¿no¶ciamy wybranego portu
+          mo¿na wykorzystaæ <application>Portmanager</application>a,
+          by ponownie skompilowa³ je we w³a¶ciwej kolejno¶ci. Na
+          koniec zostanie równie¿ ponownie skompilowany port
+          stwarzaj±cy problemy.</para>
+
+	<screen>&prompt.root; <userinput>portmanager <replaceable>graphics/gimp</replaceable> -f</userinput></screen>
+
+        <para>Wiêcej informacji dostêpnych jest na stronach podrêcznika
+          systemowego <application>Portmanager</application>a.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="ports-disk-space">
+      <title>Porty i przestrzeñ na dysku</title>
+
+      <indexterm>
+	<primary>porty</primary>
+	<secondary>przestrzeñ na dysku</secondary>
+      </indexterm>
+      <para>Korzystanie z kolekcji portów z czasem odbije siê na
+        wolnym miejscu na dysku. Dlatego te¿ zawsze po skompilowaniu
+        i zainstalowaniu programu z portu powinni¶my pamiêtaæ
+        o usuniêciu tymczasowych katalogów roboczych (ang.
+        <filename class="directory">work</filename> directories)
+        wykorzystuj±c do tego polecenie <command>make
+	<makevar>clean</makevar></command>. Ca³± kolekcjê natomiast
+        mo¿na oczy¶ciæ wpisuj±ce polecenie:</para>
+
+      <screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
+
+      <para>Z czasem uzbiera nam siê wiele katalogów
+        <filename class="directory">distfiles</filename>, które
+        bêd± jedynie zajmowaæ przestreñ na dysku. Mo¿emy je rêcznie
+        usuwaæ b±d¼ pos³u¿yæ siê nastêpuj±cym popleceniem, by usun±æ
+        wszystkie katalogi distfiles nie powi±zane aktualnie z
+        ¿adnym portem:</para>
+
+      <screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
+
+      <note>
+        <para>Program <command>portsclean</command> jest czê¶ci± pakietu
+          <application>portupgrade</application>.</para>
+      </note>
+
+      <para>Pamiêtajmy równie¿ o usuwaniu instalowanych portów gdy
+        ju¿ ich nie potrzebujemy. Przydatne narzêdzie pozwalaj±ce
+        zautomatyzowaæ te czynno¶ci znajduje siê w
+	<filename role="package">sysutils/pkg_cutleaves</filename>.</para>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="ports-nextsteps">
+    <title>Czynno¶ci po-instalacyjne</title>
+
+    <para>Po zainstalowaniu nowego programu z regu³y chcemy
+      zapoznaæ siê z dostarczon± z nim dokumentacj±, zmodyfikowaæ
+      wymagane pliki konfiguracyjne, upewniæ siê, ¿e program
+      (je¶li jest to demon) bêdzie uruchamiany w trakcie
+      ³adowania systemu, itp.</para>
+
+    <para>Oczywi¶cie, szczegó³owe kroki jakie nale¿y podj±æ
+      konfiguruj±c ka¿d± aplikacjê bêd± ró¿ne. Tym nie mniej,
+      je¶li w³a¶nie zainstalowali¶my nowy program i zastanawiamy
+      siê <quote>Co dalej?</quote> poni¿sze uwagi mog±
+      okazaæ siê pomocne:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Za pomoc± &man.pkg.info.1; mo¿emy sprawdziæ gdzie
+          i jakie pliki zosta³y zainstalowane. Na przyk³ad, je¶li
+          zainstalowali¶my wersjê 1.0.0 pakietu FooPackage,
+          polecenie</para>
+
+	<screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen>
+
+        <para>wy¶wietli nam wszystkie pliki zainstalowane
+          z pakietu. Szczególn± uwagê warto zwróciæ na pliki
+          zainstalowane w katalogach: <filename>man/</filename>
+          zawieraj±cym strony podrêcznika systemowego,
+          <filename>etc/</filename>  zawieraj±cym pliki
+          konfiguracyjne, oraz <filename>doc/</filename>,
+          gdzie znajdowaæ siê bêdzie du¿o obszerniejsza
+          dokumentacja.</para>
+
+        <para>Je¶li nie jeste¶my pewni, któr± wersj± programu
+          zainstalowali¶my, polecenie</para>
+
+	<screen>&prompt.root; <userinput>pkg_info | grep -i <replaceable>foopackage</replaceable></userinput></screen>
+
+        <para>wy¶wietli wszystkie zainstalowane pakiety
+          zawieraj±ce <replaceable>foopackage</replaceable>
+          w nazwie. Oczywi¶cie <replaceable>foopackage</replaceable>
+          nale¿y zast±piæ nazw± poszukiwanego pakietu.</para>
+      </listitem>
+
+      <listitem>
+        <para>Gdy ju¿ uda³o siê ustaliæ jakie strony podrêcznika
+          systemowego zosta³y zainstalowane przez dany pakiet,
+          mo¿na je przeczytaæ za pomoc± polecenia &man.man.1;.
+          Warto równie¿ obejrzeæ przyk³adowe pliki konfiguracyjne
+          i wszelk± dodatkow± dokumentacjê.</para>
+      </listitem>
+
+      <listitem>
+        <para>Je¶li dana aplikacja posiada w³asn± witrynê internetow±
+          warto jest równie¿ tam poszukaæ dodatkowej dokumentacji
+          czy odpowiedzi na czêsto zadawane pytania (FAQ). Je¶li nie
+          znamy w³a¶ciwego adresu internetowego mo¿e byæ on podany
+          w wyniku polecenia</para>
+
+	<screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen>
+	
+        <para>Wiersz <literal>WWW:</literal>, je¶li w ogóle jest
+          podany, powinien zawieraæ informacje o adresie witryny.</para>
+      </listitem>
+
+      <listitem>
+        <para>Programy, które powinny byæ uruchamiane podczas
+          ³adowania systemu (np. serwery internetowe) z regu³y
+          instaluj± przyk³adowy skrypt w
+          <filename>/usr/local/etc/rc.d</filename>. Powinni¶my
+          sprawdziæ zawarto¶æ tego skryptu oraz w razie potrzeby
+          zmodyfikowaæ go b±d¼ zmieniæ nazwê. Szczegó³owe informacje
+          dostêpne s± w podro¼dziale <link
+	  linkend="configtuning-starting-services">Uruchamianie
+            us³ug</link>.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="ports-broken">
+    <title>Jak radziæ sobie ze ¼le przygotowanymi portami</title>
+
+    <para>Je¶li natknêli¶my siê na port, który z jakich¶
+      powodów nie dzia³a na naszym komputerze, mo¿emy zrobiæ
+      kilka nastêpuj±cych rzeczy:</para>
+
+      <orderedlist>
+	<listitem>
+          <para>Sprawdziæ w <ulink url="&url.base;/support.html#gnats">bazie
+              danych zg³oszonych problemów</ulink> czy jest przygotowywana
+            poprawka dla danego portu. Je¶li tak, mo¿e uda siê nam
+            zastosowaæ tê poprawkê.</para>
+	</listitem>
+
+	<listitem>
+          <para>Poprosiæ o pomoc opiekuna danego portu. Adres
+            email opiekuna mo¿na znale¼æ przegl±daj±æ plik
+            <filename>Makefile</filename> w katalogu portu b±d¼
+            wpisuj±æ polecenie <command>make maintainer</command>.
+            Wysy³aj±c wiadomo¶æ pamiêtajmy o zawarciu informacji
+            o nazwie i wersji portu (najlepiej jest zawrzeæ ca³y
+            wiersz z pliku <filename>Makefile</filename> zaczynaj±cy
+            siê od <literal>&dollar;FreeBSD:</literal>), oraz opis
+            b³êdu i wynik dzia³ania programu w momencie
+            zaistnienia b³êdu.</para>
+
+	  <note>
+            <para>Niektóre porty nie s± przygotowywane przez pojedyncze
+              osoby, ale raczej przez <ulink
+	      url="&url.articles.mailing-list-faq;/article.html">grupy
+                dyskusyjne</ulink>. Wiele adresów takich grup, choæ nie
+              wszystkie, ma postaæ
+              <email role="nolink">freebsd-listname@FreeBSD.org</email>.
+              Nale¿y mieæ równie¿ to na uwadze formuuj±æ swoje pytania.</para>
+
+            <para>Porty przygotowywane przez
+              <email role="nolink">freebsd-ports@FreeBSD.org</email>
+              w rzeczywisto¶ci nie posiadaj± ¿adnego konkretnego opiekuna,
+              ani grupy opiekunów. Poprawki i pomoc dla takich portów
+              przygotowuj± osoby zapisane na tê listê dyskusyjn±. Nowi
+              ochotnicy s± zawsze mile widziani!</para>
+	  </note>
+
+          <para>W przypadku braku odpowiedzi mo¿na równie¿ przes³aæ
+            zg³oszenie b³êdu poprzez &man.send-pr.1; (szczegó³y w artykule
+            <ulink
+	    url="&url.articles.problem-reports;/article.html">Writing
+	    FreeBSD Problem Reports</ulink>).</para>
+	</listitem>
+
+        <listitem>
+          <para>Naprawiæ b³±d samemu! Podrêcznik <ulink
+            url="&url.books.porters-handbook;/index.html">Porter's
+	    Handbook</ulink> (ang.) zawiera szczegó³owe informacje
+            o strukurze <quote>Portów</quote>, dziêki czemu mo¿na samemu
+            naprawiæ b³±d lub przygotowaæ w³asny port!</para>
+	</listitem>
+
+	<listitem>
+          <para>Pobraæ pakiet z najbli¿szego serwera FTP.
+            <quote>G³ówne</quote> repozytorium pakietów znajduje
+            siê na serwerze <hostid
+	    role="fqdn">ftp.FreeBSD.org</hostid> w katalogu <ulink
+	    url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages</ulink>.
+            Tym nie mniej warto jest najpierw odszkukaæ <ulink
+	    url="http://mirrorlist.FreeBSD.org/">lokalny serwer
+            lustrzany</ulink>. Szanse na to, ¿e gotowe pakiety
+            bêd± dzia³aæ poprawnie s± wiêksze ni¿ w przypadku
+            kompilowania programów. Pakiety mo¿na zainstalowaæ
+            za pomoc± programu &man.pkg.add.1;.</para>
+	</listitem>
+      </orderedlist>
+  </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/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/Makefile b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/Makefile
new file mode 100644
index 0000000000..1a44fcbd0c
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	ppp-and-slip/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/chapter.sgml
new file mode 100644
index 0000000000..01748e264f
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/ppp-and-slip/chapter.sgml
@@ -0,0 +1,3173 @@
+<!--
+     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 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 set up user PPP.</para>
+      </listitem>
+      <listitem>
+	<para>How to set up kernel PPP.</para>
+      </listitem>
+      <listitem>
+	<para>How to set up <acronym>PPPoE</acronym> (PPP over
+	  Ethernet).</para>
+      </listitem>
+      <listitem>
+	<para>How to set up <acronym>PPPoA</acronym> (PPP over
+	  ATM).</para>
+	</listitem>
+      <listitem>
+	<para>How to configure and set up 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 <application>ppp</application> unless a distinction needs to be made between it
+	and any other PPP software such as <application>pppd</application>.
+	Unless otherwise stated, all of the commands explained in this
+	chapter 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>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.</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
+		  <filename>/dev/cuaa0</filename> and
+		  <devicename>COM2</devicename> is
+		  <filename>/dev/cuaa1</filename>.</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 &amp; 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 &amp; 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 17.  It is
+		  important that this line appears after line 17,
+		  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>
+	</sect4>
+
+	  <sect4>
+	    <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>
+	  </sect4>
+
+	  <sect4>
+	    <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>
+	  </sect4>
+
+	  <sect4>
+	    <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/passwd</filename>
+	      for a dialup PPP user with username
+	      <username>pchilds</username> (remember do not directly edit
+	      the password file, use &man.vipw.8;).</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>
+	  </sect4>
+
+	  <sect4>
+	    <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>
+	  </sect4>
+
+	  <sect4>
+	    <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>
+	  </sect4>
+
+	  <sect4>
+	    <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>
+	</sect4>
+
+	  <sect4 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 the <filename>/etc/passwd</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>
+	  </sect4>
+
+	  <sect4>
+	    <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>
+	</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>13      set authname <replaceable>MyUserName</replaceable>
+14      set authkey <replaceable>MyPassword</replaceable>
+15      set login</programlisting>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term>Line 13:</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 14:</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>16      accept PAP</programlisting>
+
+		<para>or</para>
+
+		<programlisting>16      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>
+
+	    <varlistentry>
+	      <term>Line 15:</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>
+	  </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 do not 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>Make sure that the router program is set to <literal>NO</literal> with
+	  the 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, 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>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>N</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>N</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 is 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 will also need some modem/serial software (preferably
+	<filename role="package">comms/kermit</filename>), 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 does not 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 <application>Kermit</application> (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 <application>Kermit</application> (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 console messages
+	to track the problem.</para>
+	  
+      <para>Following <filename>/etc/ppp/pppup</filename> script will make
+	all 3 stages automatic:</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 <application>Kermit</application>
+      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 <command>pppd</command> 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 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 <application>Kermit</application> 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 mode
+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 &lt; \%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 &lt; \%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="ppp-troubleshoot">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 13 June 2003 -->
+    </sect1info>
+    <title>Troubleshooting <acronym>PPP</acronym> Connections</title>
+
+    <indexterm><primary>PPP</primary><secondary>troubleshooting</secondary></indexterm>
+
+      <para>This section covers a few issues which may arise when
+	using PPP over a modem connection.  For instance, perhaps you
+	need to know exactly what prompts the system you are dialing
+	into will present.  Some <acronym>ISP</acronym>s present the
+	<literal>ssword</literal> prompt, and others will present
+	<literal>password</literal>; if the <command>ppp</command>
+	script is not written accordingly, the login attempt will
+	fail.  The most common way to debug <command>ppp</command>
+	connections is by connecting manually.  The following
+	information will walk you through a manual connection step by
+	step.</para>
+
+    <sect2>
+      <title>Check the Device Nodes</title>
+
+	<para>If you reconfigured your kernel then you recall the
+	  <devicename>sio</devicename> device.  If you did not
+	  configure your kernel, there is no reason to worry.  Just
+	  check the <command>dmesg</command> output for the modem
+	  device with:</para>
+
+	<screen>&prompt.root; <userinput>dmesg | grep sio</userinput></screen>
+
+	<para>You should get some pertinent output about the
+	  <devicename>sio</devicename> devices.  These are the COM
+	  ports we need.  If your modem acts like a standard serial
+	  port then you should see it listed on
+	  <devicename>sio1</devicename>, or <devicename>COM2</devicename>.  If so, you are not
+	  required to rebuild the kernel.
+	  When matching up sio modem is on <devicename>sio1</devicename> or
+          <devicename>COM2</devicename> if you are in DOS, then your
+	  modem device would be <filename>/dev/cuaa1</filename>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Connecting Manually</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> treats <command>ppp</command> client
+	connections.  Lets start <application>PPP</application> from
+	the command line.  Note that in all of our examples we will
+	use <emphasis>example</emphasis> as the hostname of the
+	machine running <application>PPP</application>.  You start
+	<command>ppp</command> by just typing
+	<command>ppp</command>:</para>
+
+      <screen>&prompt.root; <userinput>ppp</userinput></screen>
+
+      <para>We have now started <command>ppp</command>.</para>
+
+      <screen>ppp ON example&gt; <userinput>set device <filename>/dev/cuaa1</filename></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 <filename>/dev/cuaa1</filename>
+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 logging into
+	&os;, 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>
+
+      <sect3>
+	<title>Debugging</title>
+
+	<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 <acronym>ISP</acronym>.</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 example&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 example&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 it is 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>
+
+      </sect3>
+    </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 PPP 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
+	<guimenu>System</guimenu> 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 &tm.3com; <trademark class="registered">HomeConnect</trademark> 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 immediately with the command:</para>
+
+      <screen>&prompt.root; <userinput>sysctl net.graph.nonstandard_pppoe=1</userinput></screen>
+
+      <para>Unfortunately, because this is a system-wide setting, it is
+	not possible to talk to a normal PPPoE client or server and a
+	&tm.3com; <trademark class="registered">HomeConnect</trademark> 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.speedtouchdsl.com/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>
+
+      <para>Like many USB devices, the Alcatel &speedtouch; USB needs to
+        download firmware from the host computer to operate properly.
+        It is possible to automate this process in &os; so that this
+        transfer takes place whenever the device is plugged into a USB
+        port.  The following information can be added to the
+        <filename>/etc/usbd.conf</filename> file to enable this
+        automatic firmware transfer.  This file must be edited as the
+        <username>root</username> user.</para>
+
+      <programlisting>device "Alcatel SpeedTouch USB"
+    devname "ugen[0-9]+"
+    vendor 0x06b9
+    product 0x4061
+    attach "/usr/local/sbin/modem_run -f /usr/local/libdata/mgmt.o"</programlisting>
+
+     <para>To enable the USB daemon, <application>usbd</application>,
+       put the following the line into
+       <filename>/etc/rc.conf</filename>:</para>
+
+     <programlisting>usbd_enable="YES"</programlisting>
+
+     <para>It is also possible to set up
+       <application>ppp</application> to dial up at startup.  To do
+       this add the following lines to
+       <filename>/etc/rc.conf</filename>.  Again, for this procedure
+       you will need to be logged in as the <username>root</username>
+       user.</para>
+
+     <programlisting>ppp_enable="YES"
+ppp_mode="ddial"
+ppp_profile="adsl"</programlisting>
+
+     <para>For this to work correctly you will need to have used the
+       sample <filename>ppp.conf</filename> which is supplied with the
+       <filename role="package">net/pppoa</filename> port.</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>.  Many ADSL modems
+        require that a PPTP tunnel is created between the modem and
+        computer, one such modem is the Alcatel &speedtouch;
+        Home.</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 <replaceable>PREFIX</replaceable> means the directory
+        into which your ports are installed, this defaults to
+        <filename>/usr/local/</filename>. A complete guide to
+        configure <application>mpd</application> is available in
+        HTML format once the port has been installed. It is placed in
+        <filename><replaceable>PREFIX</replaceable>/share/doc/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 acfcomp 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 outcall
+    set pptp self <replaceable>10.0.0.1</replaceable> <co
+    id="co-mpd-ex-self">
+    set pptp peer <replaceable>10.0.0.138</replaceable> <co
+    id="co-mpd-ex-peer"></programlisting>
+
+    <calloutlist>
+      <callout arearefs="co-mpd-ex-self">
+	<para>The IP address of your &os; computer which you will be
+	  using <application>mpd</application> from.</para>
+      </callout>
+      <callout arearefs="co-mpd-ex-peer">
+	<para>The IP address of your ADSL modem.  For the Alcatel
+	  &speedtouch; Home this address defaults to <hostid
+	  role="ipaddr">10.0.0.138</hostid>.</para>
+      </callout>
+    </calloutlist>
+
+    <para>It is possible to initialize the connection easily by issuing the
+      following command as <username>root</username>:</para>
+
+    <screen>&prompt.root; <userinput>mpd -b <replaceable>adsl</replaceable></userinput></screen>
+
+    <para>You can see the status of the connection with the following
+      command:</para>
+
+    <screen>&prompt.user; <userinput>ifconfig <replaceable>ng0</replaceable></userinput>
+ng0: 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
+	 manual 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 router documentation
+	should tell you which address your device uses. To open the tunnel and
+	start a PPP session execute the following
+	command:</para>
+
+      <screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>adsl</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
+	<command>pptp</command> 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 set up a symbolic link, such as
+	<filename>/dev/modem</filename>, to point to the real device name,
+	<filename>/dev/cuaaN</filename> (or <filename>/dev/cuadN</filename> under &os;&nbsp;6.X).  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> (or <filename>/dev/cuad0</filename> under &os;&nbsp;6.X) is
+	  <devicename>COM1</devicename>, <filename>cuaa1</filename> (or <filename>/dev/cuad1</filename>) is
+	  <devicename>COM2</devicename>, etc.</para>
+      </note>
+
+      <para>Make sure you have the following in your kernel configuration
+	file:</para>
+      
+      <programlisting>device   sl</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.  Ours 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 <literal>hosts</literal> before
+	      <literal>bind</literal> 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 <literal>files</literal> before
+	      <literal>dns</literal> 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>
+
+	      <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
+	      <application>Kermit</application>, 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 username and password
+	      to fit yours.  After doing so, you can just type
+	      <command>slip</command> from the <application>Kermit</application> 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 <application>Kermit</application> 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
+	  <command>kermit</command> (by running <command>fg</command> if you suspended it) and
+	  exit from
+	  it (<keycap>q</keycap>).</para>
+
+	<para>The &man.slattach.8; 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.
+	  (<command>ifconfig sl0</command> reports the same thing.)</para>
+
+	<para>Some times, your modem might refuse to drop the carrier.
+	  In that case, simply start <command>kermit</command> 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 on &a.net.name; mailing list.  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 &man.ping.8;, 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 start up 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 set up 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 <xref
+	  linkend="dialup"> for details on dialup services
+	  configuration.
+	  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
+	    <application>syslogd</application> daemon 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
+	    <application>syslogd</application> is logging and where it is
+	    logging to).</para>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<title>Kernel Configuration</title>
+	<indexterm><primary>kernel</primary><secondary>configuration</secondary></indexterm>
+	<indexterm><primary>SLIP</primary></indexterm>
+
+	<para>&os;'s default kernel (<filename>GENERIC</filename>)
+	  comes with SLIP (&man.sl.4;) support; in case of a custom
+	  kernel, you have to add the following line to your kernel
+	  configuration file:</para>
+
+	<programlisting>device   sl</programlisting>
+
+	<para>By default, your &os; machine will not forward packets.
+	  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>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>), 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 (i.e., <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 (i.e., <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 clients 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 <application>&gated;</application></title>
+	  <indexterm>
+      <primary><application>&gated;</application></primary>
+    </indexterm>
+
+	<note>
+	  <para><application>&gated;</application> 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 compatibility for
+	    those that are still using an older version.</para>
+	</note>
+
+	  <para>An alternative to the headaches of static routes is to
+	    install <application>&gated;</application> 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 will need to write a <filename>/etc/gated.conf</filename>
+	    file to configure your <application>&gated;</application>; 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 <application>&gated;</application>'s activity; you can
+	    certainly turn off the tracing options if
+	    <application>&gated;</application> works correctly 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
+	    <application>&gated;</application> on your system, you will need to
+	    tell the FreeBSD startup scripts to run
+	    <application>&gated;</application> in place of
+	    <application>routed</application>.  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 <application>&gated;</application> 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/pl_PL.ISO8859-2/books/handbook/preface/preface.sgml b/pl_PL.ISO8859-2/books/handbook/preface/preface.sgml
new file mode 100644
index 0000000000..c80eb9e2df
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/preface/preface.sgml
@@ -0,0 +1,612 @@
+<!--
+    The FreeBSD Polish Documentation Project
+
+     $FreeBSD$
+     Original revision: 1.32
+-->
+
+<preface id="book-preface">
+  <title>Przedmowa</title>
+  
+  <bridgehead id="preface-audience" renderas=sect1>Docelowy
+    czytelnik</bridgehead>
+
+  <para>Osoba poznaj±ca dopiero system FreeBSD odnajdzie w pierwszej
+    czê¶ci niniejszej ksi±¿ki szereg porad prowadz±cych u¿ytkownika
+    przez proces instalacji i delikatnie prezentuj±cych pewne koncepcje
+    i konwencje stoj±ce u podstaw systemów &unix;. Przebrniêcie przez
+    tê czê¶æ wymaga niewiele wiêcej ni¿ chêæ poznania i umiejêtno¶æ
+    przyswajania sobie nowych koncepcji w miarê jak bêd± one
+    prezentowane.</para>
+
+  <para>Po dotrwaniu do drugiej, zdecydowanie obszerniejszej czê¶ci
+    Podrêcznika, czytelnik bêdzie mia³ do dyspozycji pe³n± wiedzê z
+    zakresu wszystkich zagadnieñ znajdujacych siê w polu zainteresowañ
+    administratorów systemów FreeBSD. Niektóre z zawartych tutaj
+    rozdzia³ów mog± wymagaæ wcze¶niejszego zapoznania siê z odpowiedni±
+    literatur±. W takich przypadkach, bêdzie to wyszczególnione w
+    streszczeniu na pocz±tku ka¿dego rozdzia³u.</para>
+
+  <para><xref linkend="bibliography"> zawiera listê dodatkowych ¼róde³
+    informacji.</para>
+
+  <bridgehead id="preface-changes-from2" renderas=sect1>Zmiany od wydania
+    drugiego</bridgehead>
+
+  <para>Niniejsze trzecie wydanie stanowi punkt kulminacyjny przesz³o
+    dwuletniej pracy oddanych cz³onków Projektu Dokumentacji FreeBSD.
+    G³ówne zmiany jakie w tym okresie zosta³y dokonane to:</para>
+
+  <itemizedlist>
+      <listitem>
+        <para><xref linkend="config-tuning">, Konfiguracja i dostrajanie zosta³
+          poszerzony o nowe informacje o zarz±dzaniu moc± i zasobami APCI,
+          opis narzêdzia cron i kolejn± porcjê opcji dostrajania j±dra.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="security">, Bezpieczeñstwo, zosta³ poszerzony
+          o nowe informacje odno¶nie wirtualnych sieci prywatnych (VPN),
+	  list kontroli dostêpu do systemu plików, i biuletynach
+          bezpieczeñstwa.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="mac">, Mandatory Access Control (MAC), is
+	  a new chapter with this edition.  It explains what MAC is
+	  and how this mechanism can be used to secure a FreeBSD
+	  system.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="disks">, Storage, has been expanded with
+	  new information about USB storage devices, file system
+	  snapshots, file system quotas, file and network backed
+	  filesystems, and encrypted disk partitions.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="vinum-vinum">, Vinum, is a new chapter
+	with this edition.  It describes how to use Vinum, a logical
+	volume manager which provides device-independent logical
+	disks, and software RAID-0, RAID-1 and RAID-5.</para>
+      </listitem>
+
+      <listitem>
+	<para>A troubleshooting section has been added to <xref
+	  linkend="ppp-and-slip">, PPP and SLIP.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="mail">, Electronic Mail, has been
+	  expanded with new information about using alternative
+	  transport agents, SMTP authentication, UUCP, fetchmail,
+	  procmail, and other advanced topics.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="network-servers">, Network Servers, is
+	  all new with this edition.  This chapter includes
+	  information about setting up the Apache HTTP Server, FTPd,
+	  and setting up a server for Microsoft Windows clients with
+	  Samba.  Some sections from <xref
+	  linkend="advanced-networking">, Advanced Networking, were
+	  moved here to improve the presentation.</para>
+      </listitem>
+
+      <listitem>
+	<para><xref linkend="advanced-networking">, Advanced
+	  Networking, has been expanded with new information about
+	  using Bluetooth devices with FreeBSD, setting up wireless
+	  networks, and Asynchronous Transfer Mode (ATM)
+	  networking.</para>
+      </listitem>
+
+      <listitem>
+        <para>Definicje i wykorzystywane w ksi±¿ce terminy techniczne
+          zosta³y zebrane razem w formie leksykonu.</para>
+      </listitem>
+
+      <listitem>
+        <para>Dokonano wielu estetycznych poprawek tabel i rysunków.</para>
+      </listitem>
+    </itemizedlist>
+
+  <bridgehead id="preface-changes" renderas=sect1>Zmiany od wydania pierwszego</bridgehead>
+
+    <para>Wydanie drugie stanowi³o punkt kulminacyjny przesz³o dwuletniej pracy
+      oddanych cz³onków Projektu Dokumentacji FreeBSD. G³ówne zmiany jakie w tym
+      okresie zosta³y dokonane to:</para>
+
+<!-- Talk a little about justification and other stylesheet changes? -->
+
+    <itemizedlist>
+      <listitem>
+	<para>Dodano indeks.</para>
+      </listitem>
+      <listitem>
+	<para>Wszystkie diagramy ASCII zosta³y zast±pione rysunkami graficznymi.</para>
+      </listitem>
+      <listitem>
+	<para>Dodano standardowe streszczenie do wszystkich rozdzia³ów, informuj±ce
+          jakie informacje rozdzia³ zawiera i co powinien wiedzieæ czytelnik nim
+          przyst±pi do czytania.</para>
+      </listitem>
+      <listitem>
+	<para>Zawarto¶æ podrêcznika zosta³a zreorganizowana w trzy logiczne czê¶ci:
+          <quote>Pierwsze kroki</quote>, <quote>Administracja systemem</quote> oraz
+	<quote>Dodatki</quote>.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="install"> (<quote>Instalacja FreeBSD</quote>) zosta³ ca³kowicie
+          przepisany na nowo.Do³±czono wiele zrzutów ekranu, by u³atwiæ nowym u¿ytkownikom
+          przyswojenie tekstu.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="basics"> (<quote>Podstawy Uniksa</quote>) zosta³ poszerzony
+          o dodatkow informacje o procesach, demonach i sygna³ach.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="ports"> (<quote>Instalacja programów</quote>) zosta³ poszerzony
+	o dodatkowe informacje o zarz±dzaniu pakietami binarnymi.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="x11"> (<quote>System okien X</quote>) zosta³ w ca³ko¶ci
+ 	napisany od nowa k³ad±c nacisk na wspó³czesne ¶rodowiska graficzne we &xfree86; 4.X,
+        takie jak <application>KDE</application> i <application>GNOME</application>.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="boot"> (<quote>Proces uruchamiania FreeBSD</quote>) zosta³
+          poszerzony.</para>
+      </listitem>
+      <listitem>
+        <para><xref linkend="disks"> (<quote>Pamiêæ</quote>) zosta³ napisany na podstawie
+          rozdzia³ów <quote>Dyski</quote> oraz <quote>Kopie zapasowe</quote>.  Uwa¿amy, ¿e
+          zagadnienia te ³atwiej jest zrozumieæ, gdy s± przedstawiane jako jeden rozdzia³.
+          Dodano równie¿ podrozdzia³ traktuj±cy o RAID (zarówno sprzêtowym jak
+          i programowym).</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="serialcomms"> (<quote>Komunikacja szeregowa</quote>) zosta³ ca³kowicie
+          zreorganizowany i zaktualizowany dla FreeBSD 4.X/5.X.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="ppp-and-slip"> (<quote>PPP i SLIP</quote>) zosta³y zasadniczo
+	zaktualizowane.</para>
+      </listitem>
+      <listitem>
+        <para><xref linkend="advanced-networking"> (<quote>Advanced Networking</quote>) zosta³
+          zaktualizowany.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="mail"> (<quote>Poczta elektroniczna</quote>) zosta³ rozszerzony materia³y
+	  traktuj±ce o konfiguracji programu <application>sendmail</application>.</para>
+      </listitem>
+      <listitem>
+	<para><xref linkend="linuxemu"> (<quote>Kompatybilno¶æ z Linuksem</quote>) zosta³ poszerzony
+          o informacje o instalacji bazy <application>&oracle;</application> oraz
+          <application>&sap.r3;</application>.</para>
+      </listitem>
+      <listitem>
+	<para>W drugim wydaniu dodano nowe rozdzia³y:</para>
+	<itemizedlist>
+	  <listitem>
+	    <para>Konfiguracja i dostrajanie (<xref linkend="config-tuning">).</para>
+	  </listitem>
+	  <listitem>
+           <para>Multimedia (<xref linkend="multimedia">)</para>
+	  </listitem>
+	</itemizedlist>
+      </listitem>
+    </itemizedlist>
+
+  <bridgehead id="preface-overview" renderas=sect1>Uk³ad ksi±¿ki</bridgehead>
+
+  <para>Niniejsza ksi±¿ka zosta³a podzielona na piêæ logicznych
+    czê¶ci. Czê¶æ pierwsza, <emphasis>Pierwsze kroki</emphasis>, opisuje
+    proces instalacji oraz podstawy u¿ytkowania systemu FreeBSD. Zaleca
+    siê aby czytelnik zapozna³ siê z tymi rozdzia³ami kolejno,
+    pomijaj±c jedynie znane tematy. Czê¶æ druga, <emphasis>Codzienne
+    czynno¶ci</emphasis>, prezentuje niektóre z najczê¶ciej wykorzystywanych
+    funkcji FreeBSD. Ta czê¶æ, wraz kolejnymi, mo¿e byæ czytania bez
+    okre¶lonej kolejno¶ci. Ka¿dy z wchodz±cych w jej sk³ad rozdzia³ów
+    zaczyna siê od zwiêz³ego strzeszczenia zawarto¶ci i przedstawienia
+    co czytelnik powinien ju¿ wiedzieæ. Celem takiego uk³adu jest pozwolenie
+    zwyk³emu czytelnikowi pomin±æ pewne rozdzia³y, by prej¶æ od razu do
+    najbardziej interesuj±cych. Czê¶æ trzecia, <emphasis>Administracja
+    Systemem</emphasis>, opisuje zagadnienia administracyjne. Czê¶æ czwarta,
+    <emphasis>Komunikacja sieciowa</emphasis>, zawiera tematy zwi±zane z prac±
+    w sieci oraz obs³ug± serwerów. Czê¶æ pi±ta zawiera dodatki.</para>
+
+  <variablelist>
+
+<!-- Part I - Introduction -->
+
+    <varlistentry>
+      <term><emphasis><xref linkend="introduction">, Wprowadzenie</emphasis></term>
+      <listitem>
+        <para>Wprowadza nowego u¿ytkownika w ¶wiat FreeBSD. Streszcza historiê
+          Projektu FreeBSD, stawiane przed nim cele oraz model rozwoju.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="install">, Instalacja</emphasis></term>
+      <listitem>
+        <para>Przeprowadza u¿ytkownika przez ca³y proces instalacji. Opisuje
+          równie¿ kilka zaawansowanych zagadnieñ, jak np. instalacjê przez
+          konsolê szeregow±.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="basics">, Podstawy Uniksa</emphasis></term>
+      <listitem>
+        <para>Przedstawia podstawowe polecenie i funkcje systemu operacyjnego
+          FreeBSD. Je¶li pracowali¶my w Linuksie b±d¼ w innym systemie typu
+          &unix; najprawdopodobniej mo¿emy pomin±æ ten rozdzia³.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="ports">, Instalacja programów</emphasis></term>
+      <listitem>
+        <para>Opisuje metody instalacji dodatkowego oprogramowania we FreeBSD
+          za pomoc± systemu <quote>Kolekcji portów</quote> oraz typowych
+          pakietów binarnych.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="x11">, System okien X</emphasis></term>
+      <listitem>
+        <para>Opisuje ogólnie System okien X oraz wykorzystanie X11 we FreeBSD.
+          Ponadto, przedstawia typowe ¶rodowiska graficzne jak np.
+          <application>KDE</application> czy <application>GNOME</application>.</para>
+      </listitem>
+    </varlistentry>
+
+<!-- Part II Common Tasks -->
+
+    <varlistentry>
+      <term><emphasis><xref linkend="desktop">, Aplikacje biurowe</emphasis></term>
+      <listitem>
+        <para>Lists some common desktop applications, such as web browsers
+         and productivity suites, and describes how to install them on
+         FreeBSD.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="multimedia">, Multimedia</emphasis></term>
+      <listitem>
+      <para>Shows how to set up sound and video playback support for your
+      system.  Also describes some sample audio and video applications.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="kernelconfig">, Configuring the FreeBSD
+      Kernel</emphasis></term>
+      <listitem>
+	<para>Explains why you might need to configure a new kernel
+	and provides detailed instructions for configuring, building,
+	and installing a custom kernel.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="printing">, Printing</emphasis></term>
+      <listitem>
+	<para>Describes managing printers on FreeBSD, including
+	information about banner pages, printer accounting, and
+	initial setup.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="linuxemu">, &linux; Binary Compatibility</emphasis></term>
+      <listitem>
+	<para>Describes the &linux; compatibility features of FreeBSD.
+	Also provides detailed installation instructions for many
+	popular &linux; applications such as <application>&oracle;</application>, <application>&sap.r3;</application>, and
+	  <application>&mathematica;</application>.</para>
+      </listitem>
+    </varlistentry>
+
+<!-- Part III - System Administration -->
+
+    <varlistentry>
+      <term><emphasis><xref linkend="config-tuning">, Configuration and Tuning</emphasis></term>
+      <listitem>
+	<para>Describes the parameters available for system
+	administrators to tune a FreeBSD system for optimum
+	performance.  Also describes the various configuration files
+	used in FreeBSD and where to find them.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="boot">, Booting Process</emphasis></term>
+      <listitem>
+	<para>Describes the FreeBSD boot process and explains
+	how to control this process with configuration options.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="users">, Users and Basic Account
+      Management</emphasis></term>
+      <listitem>
+	<para>Describes the creation and manipulation of user
+	  accounts.  Also discusses resource limitations that can be
+	  set on users and other account management tasks.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="security">, Security</emphasis></term>
+      <listitem>
+	<para>Describes many different tools available to help keep your
+	FreeBSD system secure, including Kerberos, IPsec and OpenSSH.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="mac">, Mandatory Access Control</emphasis></term>
+      <listitem>
+	<para>Explains what Mandatory Access Control (MAC) is and how this
+	mechanism can be used to secure a FreeBSD system.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="disks">, Storage</emphasis></term>
+      <listitem>
+	<para>Describes how to manage storage media and filesystems
+  	  with FreeBSD.  This includes physical disks, RAID arrays,
+  	  optical and tape media, memory-backed disks, and network
+  	  filesystems.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="geom">, GEOM</emphasis></term>
+      <listitem>
+	<para>Describes what the GEOM framework in FreeBSD is and how
+	  to configure various supported RAID levels.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="vinum-vinum">, Vinum</emphasis></term>
+      <listitem>
+	<para>Describes how to use Vinum, a logical volume manager
+	  which provides device-independent logical disks, and
+	  software RAID-0, RAID-1 and RAID-5.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="l10n">, Localization</emphasis></term>
+      <listitem>
+	<para>Describes how to use FreeBSD in languages other than
+	English.  Covers both system and application level
+	localization.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="cutting-edge">, The Cutting Edge</emphasis></term>
+      <listitem>
+	<para>Explains the differences between FreeBSD-STABLE,
+	FreeBSD-CURRENT, and FreeBSD releases.  Describes which users
+	would benefit from tracking a development system and outlines
+	that process.</para>
+      </listitem>
+    </varlistentry>
+
+<!-- Part IV - Network Communications -->
+
+    <varlistentry>
+      <term><emphasis><xref linkend="serialcomms">, Serial Communications</emphasis></term>
+      <listitem>
+	<para>Explains how to connect terminals and modems to your
+  	FreeBSD system for both dial in and dial out connections.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="ppp-and-slip">, PPP and SLIP</emphasis></term>
+      <listitem>
+	<para>Describes how to use PPP, SLIP, or PPP over Ethernet to
+	connect to remote systems with FreeBSD.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="mail">, Electronic Mail</emphasis></term>
+      <listitem>
+	<para>Explains the different components of an email server and
+	dives into simple configuration topics for the most popular
+	mail server software:
+	<application>sendmail</application>.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="network-servers">, Network Servers</emphasis></term>
+      <listitem>
+	<para>Provides detailed instructions and example configuration
+	  files to set up your FreeBSD machine as a network filesystem
+	  server, domain name server, network information system
+	  server, or time synchronization server.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="firewalls">, Firewalls</emphasis></term>
+      <listitem>
+        <para>Explains the philosophy behind software-based firewalls and
+          provides detailed information about the configuration of the
+          different firewalls available for FreeBSD.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="advanced-networking">, Advanced Networking</emphasis></term>
+      <listitem>
+	<para>Describes many networking topics, including sharing an
+	Internet connection with other computers on your LAN, advanced
+	routing topics, wireless networking, bluetooth, ATM, IPv6, and
+	much more.</para>
+      </listitem>
+    </varlistentry>
+
+<!-- Part V - Appendices -->
+
+    <varlistentry>
+      <term><emphasis><xref linkend="mirrors">, Obtaining FreeBSD </emphasis></term>
+      <listitem>
+	<para>Lists different sources for obtaining FreeBSD media on CDROM
+	or DVD as well as different sites on the Internet that allow
+	you to download and install FreeBSD.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="bibliography">, Bibliography </emphasis></term>
+      <listitem>
+	<para>This book touches on many different subjects that may
+	leave you hungry for a more detailed explanation.  The
+	bibliography lists many excellent books that are referenced in
+	the text.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="eresources">, Resources on the Internet</emphasis></term>
+      <listitem>
+	<para>Describes the many forums available for FreeBSD users to
+	post questions and engage in technical conversations about
+	FreeBSD.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><emphasis><xref linkend="pgpkeys">, PGP Keys</emphasis></term>
+      <listitem>
+	<para>Lists the PGP fingerprints of several FreeBSD Developers.</para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+  <bridgehead id="preface-conv" renderas=sect1>Konwencje u¿yte w tej ksi±¿ce</bridgehead>
+
+    <para>W celu utrzymania jednolito¶ci i ³atwo¶ci czytania
+      niniejszego tekstu w ksi±¿ce zastosowane zosta³y nastêpuj±ce
+      konwencje.</para>
+
+  <bridgehead id="preface-conv-typographic" renderas=sect2>Konwencje typograficzne</bridgehead>
+
+  <variablelist>
+    <varlistentry>
+      <term><emphasis>Kursywa</emphasis></term>
+      <listitem>
+        <para>Czcionka <emphasis>pochy³a</emphasis> stosowana jest do wskazania
+          plików, adresów URL, szczególnie akcentowanych fragmentów i pierwszego
+          zastosowania zwrotów technicznych.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><literal>Sta³a szeroko¶æ</literal></term>
+      <listitem>
+        <para>Czcionka o <literal>sta³ej szeroko¶ci</literal> stosowana jest do
+          przedstawienia komunikatów o b³êdach, poleceñ, zmiennych ¶rodowiskowych,
+          nazw portów, nazw komputerów, nazw u¿ytkowników i grup, nazw urz±dzeñ,
+          zmiennych i fragmentów kodu.</para>
+      </listitem>
+    </varlistentry>
+    <varlistentry>
+      <term><application>Pogrubienie</application></term>
+      <listitem>
+        <para>Czcionka <application>pogrubiona</application> stosowana jest do
+          nazw programów, poleceñ i klawiszy.</para>
+      </listitem>
+    </varlistentry>
+  </variablelist>
+
+<!-- Var list -->
+  <bridgehead id="preface-conv-commands"
+  renderas=sect2>Zadania u¿ytkownika</bridgehead>
+
+  <para>Zgodnie z konwencj± typograficzn±, klawisze, które ma nacisn±æ
+    u¿ytkownik w trakcie pracy z opisywanym programem, zosta³y oznaczone
+    <keycap>pogrubieniem</keycap> by wyró¿nia³y siê z reszty tekstu.
+    Kombinacje klawiszy, które nale¿y nacisn±æ jednocze¶nie zawieraj± znak
+    `<literal>+</literal>' pomiêdzy, np.:</para>
+
+  <para>
+    <keycombo action="simul">
+      <keycap>Ctrl</keycap>
+      <keycap>Alt</keycap>
+      <keycap>Del</keycap>
+    </keycombo>
+  </para>
+
+  <para>Oznacza, ¿e u¿ytkownik powinien nacisn±æ <keycap>Ctrl</keycap>,
+    <keycap>Alt</keycap> i <keycap>Del</keycap> jednocze¶nie.</para>
+
+  <para>Klawisze, które nale¿y nacisn±æ kolejno bêd± oddzielone
+    przecinkiem, np.:</para>
+
+  <para>
+    <keycombo action="simul">
+      <keycap>Ctrl</keycap>
+      <keycap>X</keycap>
+    </keycombo>,
+    <keycombo action="simul">
+      <keycap>Ctrl</keycap>
+      <keycap>S</keycap>
+    </keycombo>
+  </para>
+
+  <para>Co oznacza, ¿e u¿ytkownik powinien nacisn±æ klawisze
+    <keycap>Ctrl</keycap> i <keycap>X</keycap> jednocze¶nie,
+    a nastêpnie <keycap>Ctrl</keycap> i <keycap>S</keycap>.</para>
+
+<!-- How to type in key stokes, etc.. -->
+  <bridgehead id="preface-conv-examples"
+  renderas=sect2>Przyk³ady</bridgehead>
+
+  <para>Przyk³ady zaczynaj±ce siê od <devicename>E:\&gt;</devicename>
+    wskazuj± polecenie systemu &ms-dos;. Je¶li nie jest wyra¼nie zaznaczone,
+    ¿e jest inaczej, polecenia te mog± byæ wprowadzane bezpo¶rednio w
+    oknie <quote>Linii poleceñ</quote> w ¶rodowisku &microsoft.windows;.</para>
+
+  <screen><prompt>E:\&gt;</prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen>
+
+  <para>Przyk³ady zaczynaj±ce siê od &prompt.root; wskazuj± polecenie,
+    które musi byæ wprowadzone przez u¿ytkownika z uprawnieniami
+    administratora systemu FreeBSD. Mo¿esz zalogowaæ siê jako <username>root</username>
+    i wprowadziæ polecenie, b±d¼ zalogowaæ jako zwyk³y u¿ytkownik i wykorzystaæ
+    &man.su.1; by uzyskaæ prawa administratora.</para>
+
+  <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput></screen>
+
+  <para>Przyk³ady zaczynaj±ce siê od &prompt.user; wskazuj±, i¿ polecenie
+    powinno byæ wprowadzone przez zwyk³ego u¿ytkownika. Je¶li nie jest
+    inaczej zaznaczone, stosowana jest sk³adnia pow³oki C (csh) do ustawiania
+    zmiennych ¶rodowiskowych i uruchamiania innych poleceñ pow³oki.</para>
+
+  <screen>&prompt.user; <userinput>top</userinput></screen>
+
+  <bridgehead id="preface-acknowledgements"
+  renderas=sect1>Podziêkowania</bridgehead>
+
+  <para>Niniejsza ksi±¿ka jest efektem pracy setek ludzi z ca³ego ¶wiata.
+    Niezale¿nie czy przys³ali poprawkê literówki czy ca³y rozdzia³, ka¿dy
+    wk³ad jest doceniany.</para>
+
+  <para>Kilka firm wspar³o rozwój tego dokumentu op³acaj±c autorów,
+    by mogli pracowaæ nad ni± w pe³nym wymiarze czasowym, finansuj±c
+    publikacjê w formie papierowej, itd. Pragniemy wymieniæ przede
+    wszystkim BSDi (przejête pó¼niej przez
+    <ulink url="http://www.windriver.com">Wind River Systems</ulink>),
+    które op³aci³o pracê cz³onków Projektu Dokumentacji FreeBSD nad korektami
+    ksi±¿ki, przygotowuj±c j± do pierwszej publikacji drukowanej
+    w Marcu 2000 r. (ISBN 1-57176-241-8). Nastêpnie, Wind River Systems
+    sfinansowa³o pracê kolejnych osób przygotowuj±cych nowe rozdzia³y,
+    a tak¿e format wydruku. Kulminacj± ich pracy jest drugie wydanie, które ujrza³o
+    ¶wiat³o dzienne w Listopadzie 2001 r. (ISBN 1-57176-303-1). W latach 2003-2004,
+    <ulink url="http://www.freebsdmall.com">FreeBSD Mall, Inc</ulink> sfinansowa³o
+    prace nad korekt± Podrêcznika, przygotowywanego do trzeciego wydania
+    w postaci drukowanej.</para>
+
+</preface>
+
+<!-- 
+     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" "book" "preface")
+     End:
+-->
diff --git a/pl_PL.ISO8859-2/books/handbook/printing/Makefile b/pl_PL.ISO8859-2/books/handbook/printing/Makefile
new file mode 100644
index 0000000000..72d9e9b80a
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/printing/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	printing/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/printing/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/printing/chapter.sgml
new file mode 100644
index 0000000000..42215483ec
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/printing/chapter.sgml
@@ -0,0 +1,4876 @@
+<!--
+     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 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 with 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 with printers connected to other computers.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to print with 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 may set
+      them up to work with the Berkeley line printer spooling system,
+      also known as the <application>LPD</application> spooling system,
+      or just <application>LPD</application>.
+      It is the standard printer control system in FreeBSD.  This
+      chapter introduces <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">Basic Setup</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 learn 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 set up 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 computer's local interfaces,
+	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>Printers sold for use on PC's today generally come
+	    with one or more of the following three interfaces:</para>
+
+	  <itemizedlist>
+	    <indexterm>
+        <primary>printers</primary>
+        <secondary>serial</secondary>
+      </indexterm>
+	    <listitem>
+	      <para><emphasis>Serial</emphasis> interfaces, also known
+		as RS-232 or COM ports, 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.  Most PC serial ports have a maximum
+	        transmission rate of 115200&nbsp;bps, which makes printing
+	        large graphic print jobs with them impractical.</para>
+	    </listitem>
+
+	    <indexterm>
+        <primary>printers</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
+		and are faster than RS-232 serial.
+		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>
+
+	    <indexterm>
+        <primary>printers</primary>
+        <secondary>USB</secondary>
+	</indexterm>
+	    <listitem>
+	      <para>USB interfaces, named for the Universal Serial
+	        Bus, can run at even faster speeds than parallel or
+	        RS-232 serial interfaces.  Cables are simple and cheap.
+	        USB is superior to RS-232 Serial and to Parallel for
+	        printing, but it is not as well supported under &unix;
+	        systems.  A way to avoid this problem is to purchase a
+	        printer that has both a USB interface and a Parallel
+	        interface, as many printers do.</para>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>In general, Parallel interfaces usually offer just
+	    one-way communication (computer to printer) while serial
+	    and USB gives you two-way. Newer parallel ports (EPP and
+	    ECP) and printers
+	    can communicate in both directions under FreeBSD when a
+	    IEEE-1284-compliant cable is used.</para>
+
+	  <indexterm><primary>PostScript</primary></indexterm>
+
+	  <para>Two-way communication to the printer over a parallel
+	    port is generally done in one of two ways.  The first method
+	    uses a custom-built printer driver for FreeBSD that speaks
+	    the proprietary language used by the printer.  This is
+	    common with inkjet printers and can be used for reporting
+	    ink levels and other status information.  The second
+	    method is used when the printer supports
+	    &postscript;.</para>
+
+	  <para>&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 to 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>ppc0</filename> to
+	    FreeBSD; the second is <filename>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>) 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>grep sio<replaceable>N</replaceable> /var/run/dmesg.boot</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>grep ppc<replaceable>N</replaceable> /var/run/dmesg.boot</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-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
+	    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, 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, 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.  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>
+	</sect3>
+
+	<sect3 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>
+
+	  <sect4 id="printing-checking-parallel">
+	    <title>Checking a Parallel Printer</title>
+
+	    <indexterm>
+        <primary>printers</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>
+	  </sect4>
+
+	  <sect4 id="printing-checking-serial">
+	    <title>Checking a Serial Printer</title>
+
+	    <indexterm>
+        <primary>printers</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>
+	  </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>printers</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>ms#</literal> capability 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.
+	    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 and each line end 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
+	     Entries for the Ports
+	    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>printers</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, 38400, 57600, or 115200 bits-per-second.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>ms#<replaceable>stty-mode</replaceable></literal></term>
+
+	      <listitem>
+		<para>Sets the options for the terminal device after
+		  opening the device.  &man.stty.1; explains the
+		  available options.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+
+	  <para>When <application>LPD</application> opens the device
+	    specified by the <literal>lp</literal> capability, it sets
+	    the characteristics of the device to those specified with
+	    the <literal>ms#</literal> capability.  Of particular
+	    interest will be the <literal>parenb</literal>,
+	    <literal>parodd</literal>, <literal>cs5</literal>,
+	    <literal>cs6</literal>, <literal>cs7</literal>,
+	    <literal>cs8</literal>, <literal>cstopb</literal>,
+	    <literal>crtscts</literal>, and <literal>ixon</literal>
+	    modes, which are explained in the &man.stty.1;
+	    manual page.</para>
+
+	  <para>Let us add to our example printer on the sixth serial
+	    port.  We will set the bps rate to 38400.  For the mode,
+	    we will set no parity with <literal>-parenb</literal>,
+	    8-bit characters with <literal>cs8</literal>,
+	    no modem control with <literal>clocal</literal> and
+	    hardware flow control with <literal>crtscts</literal>:</para>
+
+	  <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\
+        :sh:sd=/var/spool/lpd/bamboo:\
+        :lp=/dev/ttyd5:ms#-parenb cs8 clocal crtscts:</programlisting>
+	</sect4>
+
+	<sect4 id="printing-textfilter">
+	  <title>Installing the Text Filter</title>
+	  <indexterm>
+	    <primary>printing</primary>
+	    <secondary>filters</secondary>
+	  </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:ms#-parenb cs8 clocal crtscts:\
+        :if=/usr/local/libexec/if-simple:</programlisting>
+
+	  <note>
+	    <para>A copy of the <filename>if-simple</filename> script
+	      can be found in the <filename
+	      class="directory">/usr/share/examples/printing</filename>
+	      directory.</para>
+	  </note>
+	</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>printing</primary>
+	<secondary>filters</secondary>
+      </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.
+            Some people even write &postscript; code directly.  Unfortunately,
+            &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>
+      
+      <note>
+	<para>A copy of the various scripts described below can be
+	  found in the <filename
+	  class="directory">/usr/share/examples/printing</filename>
+	  directory.</para>
+      </note>
+
+      <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>printing</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>printers</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, Aladdin
+          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/ifhp
+
+#
+#  Treat LF as CR+LF (to avoid the "staircase effect" on HP/PCL
+#  printers):
+#
+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.
+    #
+    /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 Conversion 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" pgwide="1">
+            <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>tf</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:ms#-parenb cs8 clocal crtscts: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>printing</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>printers</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>printers</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>printers</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:ms#-parenb cs8 clocal crtscts: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:ms#-parenb cs8 clocal crtscts: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:ms#-parenb cs8 clocal crtscts: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:ms#-parenb cs8 clocal crtscts: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>printers</primary>
+      <secondary>usage</secondary>
+   </indexterm>
+    <para>This section tells you how to use printers you have set up 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">Administering Printers</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>Administering 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.lprng.org/"></ulink>.</para>
+	</listitem>
+      </varlistentry>
+      <varlistentry>
+	<term>CUPS</term>
+
+ 	<indexterm><primary>CUPS</primary></indexterm>	  
+	<listitem>
+	  <para><application>CUPS</application>, the Common UNIX Printing
+	    System, provides a portable printing layer for &unix;-based
+	    operating systems.  It has been developed by Easy Software
+	    Products to promote a standard printing solution for all &unix;
+	    vendors and users.</para>
+
+	  <para><application>CUPS</application> uses the Internet Printing
+	    Protocol (<acronym>IPP</acronym>) as the basis for managing
+	    print jobs and queues.  The Line Printer Daemon
+	    (<acronym>LPD</acronym>), Server Message Block
+	    (<acronym>SMB</acronym>), and AppSocket (a.k.a. JetDirect)
+	    protocols are also supported with reduced functionality.  CUPS
+	    adds network printer browsing and PostScript Printer Description
+	    (<acronym>PPD</acronym>) based printing options to support
+	    real-world printing under &unix;.</para>
+
+	  <para>The main site for <application>CUPS</application> is <ulink
+	    url="http://www.cups.org/"></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;, &os2;, 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" pgwide="1">
+	    <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, use the <literal>ms#</literal> capability and
+		set the <literal>onlcr</literal> mode
+		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" pgwide="1">
+	    <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 <literal>ixon</literal> mode
+		in the <literal>ms#</literal> capability.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>If the printer supports carrier flow control, specify
+		the <literal>crtscts</literal> mode in the 
+		<literal>ms#</literal> capability.
+		Make sure the cable connecting the printer to the computer
+		is correctly wired for carrier flow control.</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 setting in the
+	    <literal>ms#</literal> capability; 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/pl_PL.ISO8859-2/books/handbook/security/Makefile b/pl_PL.ISO8859-2/books/handbook/security/Makefile
new file mode 100644
index 0000000000..bbf01aa7ab
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/security/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	security/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/security/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/security/chapter.sgml
new file mode 100644
index 0000000000..c28bc1878c
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/security/chapter.sgml
@@ -0,0 +1,4987 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="security">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Matthew</firstname>
+	<surname>Dillon</surname>
+	<contrib>Much of this chapter has been taken from the
+	security(7) manual page by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Security</title>
+  <indexterm><primary>security</primary></indexterm>
+
+  <sect1 id="security-synopsis">
+    <title>Synopsis</title>
+
+    <para>This chapter will provide a basic introduction to system security
+      concepts, some general good rules of thumb, and some advanced topics
+      under &os;.  A lot of the topics covered here can be applied
+      to system and Internet security in general as well.  The Internet
+      is no longer a <quote>friendly</quote> place in which everyone
+      wants to be your kind neighbor.  Securing your system is imperative
+      to protect your data, intellectual property, time, and much more
+      from the hands of hackers and the like.</para>
+
+    <para>&os; provides an array of utilities and mechanisms to ensure
+      the integrity and security of your system and network.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Basic system security concepts, in respect to &os;.</para>
+      </listitem>
+
+      <listitem>
+	<para>About the various crypt mechanisms available in &os;,
+	  such as <acronym>DES</acronym> and <acronym>MD5</acronym>.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up one-time password authentication.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure <acronym>TCP</acronym> Wrappers for use
+	  with <command>inetd</command>.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up <application>KerberosIV</application> on &os;
+	  releases prior to 5.0.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set up <application>Kerberos5</application> on
+	  &os;.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure IPsec and create a <acronym>VPN</acronym> between
+	&os;/&windows; machines.</para>
+      </listitem>
+     
+      <listitem>
+	<para>How to configure and use <application>OpenSSH</application>, &os;'s <acronym>SSH</acronym>
+	  implementation.</para>
+      </listitem>
+
+      <listitem>
+	<para>What file system <acronym>ACL</acronym>s are and how to use them.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use the <application>Portaudit</application>
+	  utility to audit third party software packages installed
+	  from the Ports Collection.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to utilize the &os; security advisories
+	  publications.</para>
+      </listitem>
+
+      <listitem>
+	<para>Have an idea of what Process Accounting is and how to
+	  enable it on &os;.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand basic &os; and Internet concepts.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Additional security topics are covered throughout this book.
+      For example, Mandatory Access Control is discussed in <xref
+      linkend="mac"> and Internet Firewalls are discussed in <xref
+      linkend="firewalls">.</para>
+  </sect1>
+
+  <sect1 id="security-intro">
+    <title>Introduction</title>
+
+    <para>Security is a function that begins and ends with the system
+      administrator.  While all BSD &unix; multi-user systems have some
+      inherent security, the job of building and maintaining additional
+      security mechanisms to keep those users <quote>honest</quote> is
+      probably one of the single largest undertakings of the sysadmin.
+      Machines are only as secure as you make them, and security concerns
+      are ever competing with the human necessity for convenience.  &unix;
+      systems, in general, are capable of running a huge number of
+      simultaneous processes and many of these processes operate as
+      servers &mdash; meaning that external entities can connect and talk
+      to them.  As yesterday's mini-computers and mainframes become
+      today's desktops, and as computers become networked and
+      internetwork, security becomes an even bigger issue.</para>
+
+    <para>Security is best implemented through a layered
+      <quote>onion</quote> approach.  In a nutshell, what you want to do is
+      to create as many layers of security as are convenient and then
+      carefully monitor the system for intrusions.  You do not want to
+      overbuild your security or you will interfere with the detection
+      side, and detection is one of the single most important aspects of
+      any security mechanism.  For example, it makes little sense to set
+      the <literal>schg</literal> flag (see &man.chflags.1;) on every
+      system binary because
+      while this may temporarily protect the binaries, it prevents an
+      attacker who has broken in from making an easily detectable change
+      that may result in your security mechanisms not detecting the attacker
+      at all.</para>
+
+    <para>System security also pertains to dealing with various forms of
+      attack, including attacks that attempt to crash, or otherwise make a
+      system unusable, but do not attempt to compromise the
+      <username>root</username> account (<quote>break root</quote>).
+      Security concerns
+      can be split up into several categories:</para>
+
+    <orderedlist>
+      <listitem>
+	<para>Denial of service attacks.</para>
+      </listitem>
+
+      <listitem>
+	<para>User account compromises.</para>
+      </listitem>
+
+      <listitem>
+	<para>Root compromise through accessible servers.</para>
+      </listitem>
+
+      <listitem>
+	<para>Root compromise via user accounts.</para>
+      </listitem>
+
+      <listitem>
+	<para>Backdoor creation.</para>
+      </listitem>
+    </orderedlist>
+
+    <indexterm>
+      <primary>DoS attacks</primary>
+      <see>Denial of Service (DoS)</see>
+    </indexterm>
+    <indexterm>
+      <primary>security</primary>
+      <secondary>DoS attacks</secondary>
+      <see>Denial of Service (DoS)</see>
+    </indexterm>
+    <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
+
+    <para>A denial of service attack is an action that deprives the
+      machine of needed resources.  Typically, DoS attacks are
+      brute-force mechanisms that attempt to crash or otherwise make a
+      machine unusable by overwhelming its servers or network stack.  Some
+      DoS attacks try to take advantage of bugs in the networking
+      stack to crash a machine with a single packet.  The latter can only
+      be fixed by applying a bug fix to the kernel.  Attacks on servers
+      can often be fixed by properly specifying options to limit the load
+      the servers incur on the system under adverse conditions.
+      Brute-force network attacks are harder to deal with.  A
+      spoofed-packet attack, for example, is nearly impossible to stop,
+      short of cutting your system off from the Internet.  It may not be
+      able to take your machine down, but it can saturate your
+      Internet connection.</para>
+
+    <indexterm>
+      <primary>security</primary>
+      <secondary>account compromises</secondary>
+    </indexterm>
+
+    <para>A user account compromise is even more common than a DoS
+      attack.  Many sysadmins still run standard 
+      <application>telnetd</application>, <application>rlogind</application>,
+      <application>rshd</application>,
+      and <application>ftpd</application> servers on their machines.
+      These servers, by default, do
+      not operate over encrypted connections.  The result is that if you
+      have any moderate-sized user base, one or more of your users logging
+      into your system from a remote location (which is the most common
+      and convenient way to login to a system) will have his or her
+      password sniffed.  The attentive system admin will analyze his
+      remote access logs looking for suspicious source addresses even for
+      successful logins.</para>
+
+    <para>One must always assume that once an attacker has access to a
+      user account, the attacker can break <username>root</username>.
+      However, the reality is that in a well secured and maintained system,
+      access to a user account does not necessarily give the attacker
+      access to <username>root</username>.  The distinction is important
+      because without access to <username>root</username> the attacker
+      cannot generally hide his tracks and may, at best, be able to do
+      nothing more than mess with the user's files, or crash the machine.
+      User account compromises are very common because users tend not to
+      take the precautions that sysadmins take.</para>
+
+    <indexterm>
+      <primary>security</primary>
+      <secondary>backdoors</secondary>
+    </indexterm>
+
+    <para>System administrators must keep in mind that there are
+      potentially many ways to break <username>root</username> on a machine.
+      The attacker may know the <username>root</username> password,
+      the attacker may find a bug in a root-run server and be able
+      to break <username>root</username> over a network
+      connection to that server, or the attacker may know of a bug in
+      a suid-root program that allows the attacker to break
+      <username>root</username> once he has broken into a user's account.
+      If an attacker has found a way to break <username>root</username>
+      on a machine, the attacker may not have a need
+      to install a backdoor.  Many of the <username>root</username> holes
+      found and closed to date involve a considerable amount of work
+      by the attacker to cleanup after himself, so most attackers install
+      backdoors.  A backdoor provides the attacker with a way to easily
+      regain <username>root</username> access to the system, but it
+      also gives the smart system administrator a convenient way
+      to detect the intrusion.
+      Making it impossible for an attacker to install a backdoor may
+      actually be detrimental to your security, because it will not
+      close off the hole the attacker found to break in the first
+      place.</para>
+
+
+    <para>Security remedies should always be implemented with a
+      multi-layered <quote>onion peel</quote> approach and can be
+      categorized as follows:</para>
+
+    <orderedlist>
+      <listitem>
+	<para>Securing <username>root</username> and staff accounts.</para>
+      </listitem>
+
+      <listitem>
+	<para>Securing <username>root</username>&ndash;run servers
+	  and suid/sgid binaries.</para>
+      </listitem>
+
+      <listitem>
+	<para>Securing user accounts.</para>
+      </listitem>
+
+      <listitem>
+	<para>Securing the password file.</para>
+      </listitem>
+
+      <listitem>
+	<para>Securing the kernel core, raw devices, and
+	  file systems.</para>
+      </listitem>
+
+      <listitem>
+	<para>Quick detection of inappropriate changes made to the
+	  system.</para>
+      </listitem>
+
+      <listitem>
+	<para>Paranoia.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>The next section of this chapter will cover the above bullet
+      items in greater depth.</para>
+  </sect1>
+
+  <sect1 id="securing-freebsd">
+    <title>Securing &os;</title>
+    <indexterm>
+      <primary>security</primary>
+      <secondary>securing &os;</secondary>
+    </indexterm>
+
+    <note>
+      <title>Command vs. Protocol</title>
+      <para>Throughout this document, we will use
+       <application>bold</application> text to refer to an
+       application, and a <command>monospaced</command> font to refer
+       to specific commands.  Protocols will use a normal font.  This
+       typographical distinction is useful for instances such as ssh,
+       since it is
+       a protocol as well as command.</para>
+    </note>
+
+    <para>The sections that follow will cover the methods of securing your
+      &os; system that were mentioned in the <link
+        linkend="security-intro">last section</link> of this chapter.</para>
+
+    <sect2 id="securing-root-and-staff">
+      <title>Securing the <username>root</username> Account and
+	Staff Accounts</title>
+      <indexterm>
+        <primary><command>su</command></primary>
+      </indexterm>
+
+      <para>First off, do not bother securing staff accounts if you have
+	not secured the <username>root</username> account.
+	Most systems have a password assigned to the <username>root</username>
+	account.  The first thing you do is assume
+	that the password is <emphasis>always</emphasis> compromised.
+	This does not mean that you should remove the password.  The
+	password is almost always necessary for console access to the
+	machine.  What it does mean is that you should not make it
+	possible to use the password outside of the console or possibly
+	even with the &man.su.1; command.  For example, make sure that
+	your ptys are specified as being insecure in the
+	<filename>/etc/ttys</filename> file so that direct
+	<username>root</username> logins
+	via <command>telnet</command> or <command>rlogin</command> are
+	disallowed.  If using other login services such as
+        <application>sshd</application>, make sure that direct
+	<username>root</username> logins are disabled there as well.
+	You can do this by editing
+        your <filename>/etc/ssh/sshd_config</filename> file, and making
+        sure that <literal>PermitRootLogin</literal> is set to
+        <literal>NO</literal>.  Consider every access method &mdash;
+        services such as FTP often fall through the cracks.
+	Direct <username>root</username> logins should only be allowed
+	via the system console.</para>
+      <indexterm>
+        <primary><groupname>wheel</groupname></primary>
+      </indexterm>
+
+      <para>Of course, as a sysadmin you have to be able to get to
+	<username>root</username>, so we open up a few holes.
+	But we make sure these holes require additional password
+	verification to operate.  One way to make <username>root</username>
+	accessible is to add appropriate staff accounts to the
+	<groupname>wheel</groupname> group (in
+	<filename>/etc/group</filename>).  The staff members placed in the
+	<groupname>wheel</groupname> group are allowed to
+	<command>su</command> to <username>root</username>.
+	You should never give staff
+	members native <groupname>wheel</groupname> access by putting them in the
+	<groupname>wheel</groupname> group in their password entry.  Staff
+	accounts should be placed in a <groupname>staff</groupname> group, and
+	then added to the <groupname>wheel</groupname> group via the
+	<filename>/etc/group</filename> file.  Only those staff members
+	who actually need to have <username>root</username> access
+	should be placed in the
+	<groupname>wheel</groupname> group.  It is also possible, when using
+	an authentication method such as Kerberos, to use Kerberos'
+	<filename>.k5login</filename> file in the <username>root</username>
+	account to allow a &man.ksu.1; to <username>root</username>
+	without having to place anyone at all in the
+	<groupname>wheel</groupname> group.  This may be the better solution
+	since the <groupname>wheel</groupname> mechanism still allows an
+	intruder to break <username>root</username> if the intruder
+	has gotten hold of your
+	password file and can break into a staff account.  While having
+	the <groupname>wheel</groupname> mechanism is better than having
+	nothing at all, it is not necessarily the safest option.</para>
+
+      <!-- XXX:
+	This will need updating depending on the outcome of PR bin/71147.
+	Personally I know what I'd like to see, which puts this in definite
+	need of a rewrite, but we'll have to wait and see.  ceri@
+      -->
+
+      <para>An indirect way to secure staff accounts, and ultimately
+        <username>root</username> access is to use an alternative
+	login access method and
+        do what is known as <quote>starring</quote> out the encrypted
+        password for the staff accounts.  Using the &man.vipw.8;
+        command, one can replace each instance of an encrypted password
+        with a single <quote><literal>*</literal></quote> character.
+	This command will update the <filename>/etc/master.passwd</filename>
+	file and user/password database to disable password-authenticated
+        logins.</para>
+
+      <para>A staff account entry such as:</para>
+
+      <programlisting>foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>
+
+      <para>Should be changed to this:</para>
+
+      <programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting>
+
+      <para>This change will prevent normal logins from occurring,
+        since the encrypted password will never match
+        <quote><literal>*</literal></quote>.  With this done,
+	staff members must use
+        another mechanism to authenticate themselves such as
+        &man.kerberos.1; or &man.ssh.1; using a public/private key
+        pair.  When using something like Kerberos, one generally must
+        secure the machines which run the Kerberos servers and your
+        desktop workstation.  When using a public/private key pair
+        with ssh, one must generally secure
+        the machine used to login <emphasis>from</emphasis> (typically
+        one's workstation).  An additional layer of protection can be
+        added to the key pair by password protecting the key pair when
+        creating it with &man.ssh-keygen.1;.  Being able to
+        <quote>star</quote> out the passwords for staff accounts also
+        guarantees that staff members can only login through secure
+        access methods that you have set up.  This forces all staff
+        members to use secure, encrypted connections for all of their
+        sessions, which closes an important hole used by many
+        intruders: sniffing the network from an unrelated,
+        less secure machine.</para>
+
+      <para>The more indirect security mechanisms also assume that you are
+	logging in from a more restrictive server to a less restrictive
+	server.  For example, if your main box is running all sorts of
+	servers, your workstation should not be running any.  In order for
+	your workstation to be reasonably secure you should run as few
+	servers as possible, up to and including no servers at all, and
+	you should run a password-protected screen blanker.  Of course,
+	given physical access to a workstation an attacker can break any
+	sort of security you put on it.  This is definitely a problem that
+	you should consider, but you should also consider the fact that the
+	vast majority of break-ins occur remotely, over a network, from
+	people who do not have physical access to your workstation or
+	servers.</para>
+      <indexterm><primary>KerberosIV</primary></indexterm>
+
+      <para>Using something like Kerberos also gives you the ability to
+	disable or change the password for a staff account in one place,
+	and have it immediately affect all the machines on which the staff
+	member may have an account.  If a staff member's account gets
+	compromised, the ability to instantly change his password on all
+	machines should not be underrated.  With discrete passwords,
+	changing a password on N machines can be a mess.  You can also
+	impose re-passwording restrictions with Kerberos:  not only can a
+	Kerberos ticket be made to timeout after a while, but the Kerberos
+	system can require that the user choose a new password after a
+	certain period of time (say, once a month).</para>
+    </sect2>
+
+    <sect2>
+      <title>Securing Root-run Servers and SUID/SGID Binaries</title>
+
+      <indexterm>
+        <primary><command>ntalk</command></primary>
+      </indexterm>
+      <indexterm>
+        <primary><command>comsat</command></primary>
+      </indexterm>
+      <indexterm>
+        <primary><command>finger</command></primary>
+      </indexterm>
+      <indexterm>
+        <primary>sandboxes</primary>
+      </indexterm>
+      <indexterm>
+        <primary><application>sshd</application></primary>
+      </indexterm>
+      <indexterm>
+        <primary><application>telnetd</application></primary>
+      </indexterm>
+      <indexterm>
+        <primary><application>rshd</application></primary>
+      </indexterm>
+      <indexterm>
+        <primary><application>rlogind</application></primary>
+      </indexterm>
+
+      <para>The prudent sysadmin only runs the servers he needs to, no
+	more, no less.  Be aware that third party servers are often the
+	most bug-prone.  For example, running an old version of
+	<application>imapd</application> or
+	<application>popper</application> is like giving a universal
+	<username>root</username> ticket out to the entire world.
+	Never run a server that you have not checked out carefully.
+	Many servers do not need to be run as <username>root</username>.
+	For example, the <application>ntalk</application>,
+	<application>comsat</application>, and
+	<application>finger</application> daemons can be run in special
+	user <firstterm>sandboxes</firstterm>.  A sandbox is not perfect,
+	unless you go through a large amount of trouble, but the onion
+	approach to security still stands: If someone is able to break
+	in through a server running in a sandbox, they still have to
+	break out of the sandbox.  The more layers the attacker must
+	break through, the lower the likelihood of his success.  Root
+	holes have historically been found in virtually every server
+	ever run as <username>root</username>, including basic system servers.
+	If you are running a machine through which people only login via
+	<application>sshd</application> and never login via
+	<application>telnetd</application> or
+	<application>rshd</application> or
+	<application>rlogind</application>, then turn off those
+	services!</para>
+      
+      <para>&os; now defaults to running
+	<application>ntalkd</application>,
+	<application>comsat</application>, and
+	<application>finger</application> in a sandbox.  Another program
+	which may be a candidate for running in a sandbox is &man.named.8;.
+	<filename>/etc/defaults/rc.conf</filename> includes the arguments
+	necessary to run <application>named</application> in a sandbox in a
+	commented-out form.  Depending on whether you are installing a new
+	system or upgrading an existing system, the special user accounts
+	used by these sandboxes may not be installed.  The prudent
+	sysadmin would research and implement sandboxes for servers
+	whenever possible.</para>
+      <indexterm>
+        <primary><application>sendmail</application></primary>
+      </indexterm>
+
+      <para>There are a number of other servers that typically do not run
+	in sandboxes: <application>sendmail</application>,
+	<application>popper</application>,
+	<application>imapd</application>, <application>ftpd</application>,
+	and others.  There are alternatives to some of these, but
+	installing them may require more work than you are willing to
+	perform (the convenience factor strikes again).  You may have to
+	run these servers as <username>root</username> and rely on other
+	mechanisms to detect break-ins that might occur through them.</para>
+
+      <para>The other big potential <username>root</username> holes in a
+	system are the
+	suid-root and sgid binaries installed on the system.  Most of
+	these binaries, such as <application>rlogin</application>, reside
+	in <filename>/bin</filename>, <filename>/sbin</filename>,
+	<filename>/usr/bin</filename>, or <filename>/usr/sbin</filename>.
+	While nothing is 100% safe, the system-default suid and sgid
+	binaries can be considered reasonably safe.  Still,
+	<username>root</username> holes are occasionally found in these
+	binaries.  A <username>root</username> hole was found in
+	<literal>Xlib</literal> in 1998 that made
+	<application>xterm</application> (which is typically suid)
+	vulnerable.  It is better to be safe than sorry and the prudent
+	sysadmin will restrict suid binaries, that only staff should run,
+	to a special group that only staff can access, and get rid of
+	(<command>chmod 000</command>) any suid binaries that nobody uses.
+	A server with no display generally does not need an
+	<application>xterm</application> binary.  Sgid binaries can be
+	almost as dangerous.  If an intruder can break an sgid-kmem binary,
+	the intruder might be able to read <filename>/dev/kmem</filename>
+	and thus read the encrypted password file, potentially compromising
+	any passworded account.  Alternatively an intruder who breaks
+	group <literal>kmem</literal> can monitor keystrokes sent through
+	ptys, including ptys used by users who login through secure
+	methods.  An intruder that breaks the <groupname>tty</groupname>
+	group can write to
+	almost any user's tty.  If a user is running a terminal program or
+	emulator with a keyboard-simulation feature, the intruder can
+	potentially generate a data stream that causes the user's terminal
+	to echo a command, which is then run as that user.</para>
+    </sect2>
+
+    <sect2 id="secure-users">
+      <title>Securing User Accounts</title>
+
+      <para>User accounts are usually the most difficult to secure.  While
+	you can impose Draconian access restrictions on your staff and
+	<quote>star</quote> out their passwords, you may not be able to
+	do so with any general user accounts you might have.  If you do
+	have sufficient control, then you may win out and be able to secure
+	the user accounts properly.  If not, you simply have to be more
+	vigilant in your monitoring of those accounts.  Use of
+	ssh and Kerberos for user accounts is
+	more problematic, due to the extra administration and technical
+	support required, but still a very good solution compared to a
+	crypted password file.</para>
+    </sect2>
+
+    <sect2>
+      <title>Securing the Password File</title>
+
+      <para>The only sure fire way is to <literal>*</literal> out as many
+	passwords as you can and use ssh or
+	Kerberos for access to those accounts.  Even though the encrypted
+	password file (<filename>/etc/spwd.db</filename>) can only be read
+	by <username>root</username>, it may be possible for an intruder
+	to obtain read access to that file even if the attacker cannot
+	obtain root-write access.</para>
+
+      <para>Your security scripts should always check for and report
+	changes to the password file (see the <link
+	  linkend="security-integrity">Checking file integrity</link> section
+	below).</para>
+    </sect2>
+
+    <sect2>
+      <title>Securing the Kernel Core, Raw Devices, and
+	File systems</title>
+
+      <para>If an attacker breaks <username>root</username> he can do
+        just about anything, but
+	there are certain conveniences.  For example, most modern kernels
+	have a packet sniffing device driver built in.  Under &os; it
+	is called the <devicename>bpf</devicename> device.  An intruder
+	will commonly attempt to run a packet sniffer on a compromised
+	machine.  You do not need to give the intruder the capability and
+	most systems do not have the need for the
+	<devicename>bpf</devicename> device compiled in.</para>
+
+      <indexterm>
+        <primary><command>sysctl</command></primary>
+      </indexterm>
+      <para>But even if you turn off the <devicename>bpf</devicename>
+	device, you still have
+	<filename>/dev/mem</filename> and 
+	<filename>/dev/kmem</filename>
+	to worry about.  For that matter, the intruder can still write to
+	raw disk devices.  Also, there is another kernel feature called
+	the module loader, &man.kldload.8;.  An enterprising intruder can
+	use a KLD module to install his own <devicename>bpf</devicename>
+	device, or other sniffing
+	device, on a running kernel.  To avoid these problems you have to
+	run the kernel at a higher secure level, at least securelevel 1.
+	The securelevel can be set with a <command>sysctl</command> on
+	the <varname>kern.securelevel</varname> variable.  Once you have
+	set the securelevel to 1, write access to raw devices will be
+	denied and special <command>chflags</command> flags,
+	such as <literal>schg</literal>,
+	will be enforced.  You must also ensure that the
+	<literal>schg</literal> flag is set on critical startup binaries,
+	directories, and script files &mdash; everything that gets run up
+	to the point where the securelevel is set.  This might be overdoing
+	it, and upgrading the system is much more difficult when you
+	operate at a higher secure level.  You may compromise and run the
+	system at a higher secure level but not set the
+	<literal>schg</literal> flag for every system file and directory
+	under the sun.  Another possibility is to simply mount
+	<filename>/</filename> and <filename>/usr</filename> read-only.
+	It should be noted that being too Draconian in what you attempt to
+	protect may prevent the all-important detection of an
+	intrusion.</para>
+    </sect2>
+
+    <sect2 id="security-integrity">
+      <title>Checking File Integrity: Binaries, Configuration Files,
+	Etc.</title>
+
+      <para>When it comes right down to it, you can only protect your core
+	system configuration and control files so much before the
+	convenience factor rears its ugly head.  For example, using
+	<command>chflags</command> to set the <literal>schg</literal> bit
+	on most of the files in <filename>/</filename> and
+	<filename>/usr</filename> is probably counterproductive, because
+	while it may protect the files, it also closes a detection window.
+	The last layer of your security onion is perhaps the most
+	important &mdash; detection.  The rest of your security is pretty
+	much useless (or, worse, presents you with a false sense of
+	safety) if you cannot detect potential incursions.  Half the job
+	of the onion is to slow down the attacker, rather than stop him, in
+	order to give the detection side of the equation a chance to catch
+	him in the act.</para>
+
+      <para>The best way to detect an incursion is to look for modified,
+	missing, or unexpected files.  The best way to look for modified
+	files is from another (often centralized) limited-access system.
+	Writing your security scripts on the extra-secure limited-access
+	system makes them mostly invisible to potential attackers, and this
+	is important.  In order to take maximum advantage you generally
+	have to give the limited-access box significant access to the
+	other machines in the business, usually either by doing a
+	read-only NFS export of the other machines to the limited-access
+	box, or by setting up ssh key-pairs to
+	allow the limited-access box to ssh to
+	the other machines.  Except for its network traffic, NFS is the
+	least visible method &mdash; allowing you to monitor the
+	file systems on each client box virtually undetected.  If your
+	limited-access server is connected to the client boxes through a
+	switch, the NFS method is often the better choice.  If your
+	limited-access server is connected to the client boxes through a
+	hub, or through several layers of routing, the NFS method may be
+	too insecure (network-wise) and using
+	ssh may be the better choice even with
+	the audit-trail tracks that ssh
+	lays.</para>
+
+      <para>Once you give a limited-access box, at least read access to the
+	client systems it is supposed to monitor, you must write scripts
+	to do the actual monitoring.  Given an NFS mount, you can write
+	scripts out of simple system utilities such as &man.find.1; and
+	&man.md5.1;.  It is best to physically md5 the client-box files
+	at least once a day, and to test control files such as those
+	found in <filename>/etc</filename> and
+	<filename>/usr/local/etc</filename> even more often.  When
+	mismatches are found, relative to the base md5 information the
+	limited-access machine knows is valid, it should scream at a
+	sysadmin to go check it out.  A good security script will also
+	check for inappropriate suid binaries and for new or deleted files
+	on system partitions such as <filename>/</filename> and
+	<filename>/usr</filename>.</para>
+
+      <para>When using ssh rather than NFS,
+	writing the security script is much more difficult.   You
+	essentially have to <command>scp</command> the scripts to the client 
+	box in order to
+	run them, making them visible, and for safety you also need to
+	<command>scp</command> the binaries (such as find) that those
+	scripts use.  The <application>ssh</application> client on the
+	client box may already be compromised.  All in all, using
+	ssh may be necessary when running over
+	insecure links, but it is also a lot harder to deal with.</para>
+
+      <para>A good security script will also check for changes to user and
+	staff members access configuration files:
+	<filename>.rhosts</filename>, <filename>.shosts</filename>,
+	<filename>.ssh/authorized_keys</filename> and so forth&hellip;
+	files that might fall outside the purview of the
+	<literal>MD5</literal> check.</para>
+
+      <para>If you have a huge amount of user disk space, it may take too
+	long to run through every file on those partitions.  In this case,
+	setting mount flags to disallow suid binaries and devices on those
+	partitions is a good idea.  The <literal>nodev</literal> and
+	<literal>nosuid</literal> options (see &man.mount.8;) are what you
+	want to look into.  You should probably scan them anyway, at least
+	once a week, since the object of this layer is to detect a break-in
+	whether or not the break-in is effective.</para>
+
+      <para>Process accounting (see &man.accton.8;) is a relatively
+	low-overhead feature of the operating system which might help
+	as a post-break-in evaluation mechanism.  It is especially
+	useful in tracking down how an intruder has actually broken into
+	a system, assuming the file is still intact after the break-in
+	occurs.</para>
+
+      <para>Finally, security scripts should process the log files, and the
+	logs themselves should be generated in as secure a manner as
+	possible &mdash; remote syslog can be very useful.  An intruder
+	tries to cover his tracks, and log files are critical to the
+	sysadmin trying to track down the time and method of the initial
+	break-in.  One way to keep a permanent record of the log files is
+	to run the system console to a serial port and collect the
+	information on a continuing basis through a secure machine
+	monitoring the consoles.</para>
+    </sect2>
+
+    <sect2>
+      <title>Paranoia</title>
+
+      <para>A little paranoia never hurts.  As a rule, a sysadmin can add
+	any number of security features, as long as they do not affect
+	convenience, and can add security features that
+	<emphasis>do</emphasis> affect convenience with some added thought.
+	Even more importantly, a security administrator should mix it up a
+	bit &mdash; if you use recommendations such as those given by this
+	document verbatim, you give away your methodologies to the
+	prospective attacker who also has access to this document.</para>
+    </sect2>
+
+    <sect2>
+      <title>Denial of Service Attacks</title>
+      <indexterm><primary>Denial of Service (DoS)</primary></indexterm>
+
+      <para>This section covers Denial of Service attacks.  A DoS attack
+	is typically a packet attack.  While there is not much you can do
+	about modern spoofed packet attacks that saturate your network,
+	you can generally limit the damage by ensuring that the attacks
+	cannot take down your servers.</para>
+
+      <orderedlist>
+	<listitem>
+	  <para>Limiting server forks.</para>
+	</listitem>
+
+	<listitem>
+	  <para>Limiting springboard attacks (ICMP response attacks, ping
+	    broadcast, etc.).</para>
+	</listitem>
+
+	<listitem>
+	  <para>Kernel Route Cache.</para>
+	</listitem>
+      </orderedlist>
+
+      <para>A common DoS attack is against a forking server that attempts
+	to cause the server to eat processes, file descriptors, and memory,
+	until the machine dies.  <application>inetd</application>
+	(see &man.inetd.8;) has several
+	options to limit this sort of attack.  It should be noted that
+	while it is possible to prevent a machine from going down, it is
+	not generally possible to prevent a service from being disrupted
+	by the attack.  Read the <application>inetd</application> manual
+	page carefully and pay
+	specific attention to the <option>-c</option>, <option>-C</option>,
+	and <option>-R</option> options.  Note that spoofed-IP attacks
+	will circumvent the <option>-C</option> option to 
+	<application>inetd</application>, so
+	typically a combination of options must be used.  Some standalone
+	servers have self-fork-limitation parameters.</para>
+
+      <para><application>Sendmail</application> has its
+	<option>-OMaxDaemonChildren</option> option, which tends to work
+	much better than trying to use sendmail's load limiting options
+	due to the load lag.  You should specify a
+	<literal>MaxDaemonChildren</literal> parameter, when you start
+	<application>sendmail</application>, high enough to handle your
+	expected load, but not so high that the computer cannot handle that
+	number of <application>sendmails</application> without falling on
+	its face.  It is also prudent to run sendmail in queued mode
+	(<option>-ODeliveryMode=queued</option>) and to run the daemon
+	(<command>sendmail -bd</command>) separate from the queue-runs
+	(<command>sendmail -q15m</command>).  If you still want real-time
+	delivery you can run the queue at a much lower interval, such as
+	<option>-q1m</option>, but be sure to specify a reasonable
+	<literal>MaxDaemonChildren</literal> option for
+	<emphasis>that</emphasis> sendmail to prevent cascade failures.</para>
+
+      <para><application>Syslogd</application> can be attacked directly
+	and it is strongly recommended that you use the <option>-s</option>
+	option whenever possible, and the <option>-a</option> option
+	otherwise.</para>
+
+      <para>You should also be fairly careful with connect-back services
+	such as <application>TCP Wrapper</application>'s reverse-identd,
+	which can be attacked directly.  You generally do not want to use
+	the reverse-ident feature of
+	<application>TCP Wrapper</application> for this reason.</para>
+
+      <para>It is a very good idea to protect internal services from
+	external access by firewalling them off at your border routers.
+	The idea here is to prevent saturation attacks from outside your
+	LAN, not so much to protect internal services from network-based
+	<username>root</username> compromise.
+	Always configure an exclusive firewall, i.e.,
+	<quote>firewall everything <emphasis>except</emphasis> ports A, B,
+	C, D, and M-Z</quote>.  This way you can firewall off all of your
+	low ports except for certain specific services such as
+	<application>named</application> (if you are primary for a zone),
+	<application>ntalkd</application>,
+	<application>sendmail</application>, and other Internet-accessible
+	services.  If you try to configure the firewall the other way
+	&mdash; as an inclusive or permissive firewall, there is a good
+	chance that you will forget to <quote>close</quote> a couple of
+	services, or that you will add a new internal service and forget
+	to update the firewall.  You can still open up the high-numbered
+	port range on the firewall, to allow permissive-like operation,
+	without compromising your low ports.  Also take note that &os;
+	allows you to control the range of port numbers used for dynamic
+	binding, via the various <varname>net.inet.ip.portrange</varname>
+	<command>sysctl</command>'s (<command>sysctl -a | fgrep
+	portrange</command>), which can also ease the complexity of your
+	firewall's configuration.  For example, you might use a normal
+	first/last range of 4000 to 5000, and a hiport range of 49152 to
+	65535, then block off everything under 4000 in your firewall
+	(except for certain specific Internet-accessible ports, of
+	course).</para>
+
+      <para>Another common DoS attack is called a springboard attack
+	&mdash; to attack a server in a manner that causes the server to
+	generate responses which overloads the server, the local
+	network, or some other machine.  The most common attack of this
+	nature is the <emphasis>ICMP ping broadcast attack</emphasis>.
+	The attacker spoofs ping packets sent to your LAN's broadcast
+	address with the source IP address set to the actual machine they
+	wish to attack.  If your border routers are not configured to
+	stomp on ping's to broadcast addresses, your LAN winds up
+	generating sufficient responses to the spoofed source address to
+	saturate the victim, especially when the attacker uses the same
+	trick on several dozen broadcast addresses over several dozen
+	different networks at once.  Broadcast attacks of over a hundred
+	and twenty megabits have been measured.  A second common
+	springboard attack is against the ICMP error reporting system.
+	By constructing packets that generate ICMP error responses, an
+	attacker can saturate a server's incoming network and cause the
+	server to saturate its outgoing network with ICMP responses.  This
+	type of attack can also crash the server by running it out of
+	mbuf's, especially if the server cannot drain the ICMP responses
+	it generates fast enough.
+	Use the <application>sysctl</application>
+	variable <literal>net.inet.icmp.icmplim</literal> to limit these attacks.
+	The last major class of springboard
+	attacks is related to certain internal 
+	<application>inetd</application> services such as the
+	udp echo service.  An attacker simply spoofs a UDP packet with the
+	source address being server A's echo port, and the destination
+	address being server B's echo port, where server A and B are both
+	on your LAN.  The two servers then bounce this one packet back and
+	forth between each other.  The attacker can overload both servers
+	and their LANs simply by injecting a few packets in this manner.
+	Similar problems exist with the internal 
+	<application>chargen</application> port.  A
+	competent sysadmin will turn off all of these inetd-internal test
+	services.</para>
+
+      <para>Spoofed packet attacks may also be used to overload the kernel
+	route cache.  Refer to the <varname>net.inet.ip.rtexpire</varname>,
+	<varname>rtminexpire</varname>, and <varname>rtmaxcache</varname>
+	<command>sysctl</command> parameters.  A spoofed packet attack
+	that uses a random source IP will cause the kernel to generate a
+	temporary cached route in the route table, viewable with
+	<command>netstat -rna | fgrep W3</command>.  These routes
+	typically timeout in 1600 seconds or so.  If the kernel detects
+	that the cached route table has gotten too big it will dynamically
+	reduce the <varname>rtexpire</varname> but will never decrease it 
+	to less than <varname>rtminexpire</varname>.  There are two 
+	problems:</para>
+	
+      <orderedlist>
+	<listitem>
+	  <para>The kernel does not react quickly enough when a lightly
+	    loaded server is suddenly attacked.</para>
+	</listitem>
+	
+	<listitem>
+	  <para>The <varname>rtminexpire</varname> is not low enough for
+	    the kernel to survive a sustained attack.</para>
+	</listitem>
+      </orderedlist>
+      
+      <para>If your servers are connected to the Internet via a T3 or
+        better, it may be prudent to manually override both
+	<varname>rtexpire</varname> and <varname>rtminexpire</varname>
+	via &man.sysctl.8;.  Never set either parameter to zero (unless
+	you want to crash the machine).  Setting both
+	parameters to 2 seconds should be sufficient to protect the route
+	table from attack.</para>
+    </sect2>
+
+    <sect2>
+      <title>Access Issues with Kerberos and SSH</title>
+      <indexterm><primary><command>ssh</command></primary></indexterm>
+      <indexterm><primary>KerberosIV</primary></indexterm>
+
+      <para>There are a few issues with both Kerberos and
+	ssh that need to be addressed if
+	you intend to use them.  Kerberos V is an excellent
+	authentication protocol, but there are bugs in the kerberized
+	<application>telnet</application> and
+	<application>rlogin</application> applications that make them
+	unsuitable for dealing with binary streams.  Also, by default
+	Kerberos does not encrypt a session unless you use the
+	<option>-x</option> option.  <application>ssh</application>
+	encrypts everything by default.</para>
+
+      <para>ssh works quite well in every
+	respect except that it forwards encryption keys by default.  What
+	this means is that if you have a secure workstation holding keys
+	that give you access to the rest of the system, and you
+	ssh to an insecure machine, your keys
+	are usable.  The actual keys themselves are not exposed, but
+	ssh installs a forwarding port for the
+	duration of your login, and if an attacker has broken
+	<username>root</username> on the
+	insecure machine he can utilize that port to use your keys to gain
+	access to any other machine that your keys unlock.</para>
+
+      <para>We recommend that you use ssh in
+	combination with Kerberos whenever possible for staff logins.
+	<application>ssh</application> can be compiled with Kerberos
+	support.  This reduces your reliance on potentially exposed
+	ssh keys while at the same time
+	protecting passwords via Kerberos.  ssh
+	keys should only be used for automated tasks from secure machines
+	(something that Kerberos is unsuited to do).  We also recommend that
+	you either turn off key-forwarding in the
+	ssh configuration, or that you make use
+	of the <literal>from=IP/DOMAIN</literal> option that
+	ssh allows in its
+	<filename>authorized_keys</filename> file to make the key only
+	usable to entities logging in from specific machines.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="crypt">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Bill</firstname>
+	  <surname>Swingle</surname>
+	  <contrib>Parts rewritten and updated by </contrib>
+	</author>
+      </authorgroup>
+      <!-- 21 Mar 2000 -->
+    </sect1info>
+
+    <title>DES, MD5, and Crypt</title>
+    <indexterm>
+      <primary>security</primary>
+      <secondary>crypt</secondary>
+    </indexterm>
+
+    <indexterm><primary>crypt</primary></indexterm>
+    <indexterm><primary>DES</primary></indexterm>
+    <indexterm><primary>MD5</primary></indexterm>
+
+    <para>Every user on a &unix; system has a password associated with
+      their account.  It seems obvious that these passwords need to be
+      known only to the user and the actual operating system.  In
+      order to keep these passwords secret, they are encrypted with
+      what is known as a <quote>one-way hash</quote>, that is, they can
+      only be easily encrypted but not decrypted.  In other words, what
+      we told you a moment ago was obvious is not even true:  the
+      operating system itself does not <emphasis>really</emphasis> know
+      the password.  It only knows the <emphasis>encrypted</emphasis>
+      form of the password.  The only way to get the
+      <quote>plain-text</quote> password is by a brute force search of the
+      space of possible passwords.</para>
+
+    <para>Unfortunately the only secure way to encrypt passwords when
+      &unix; came into being was based on DES, the Data Encryption
+      Standard.  This was not such a problem for users resident in
+      the US, but since the source code for DES could not be exported
+      outside the US, &os; had to find a way to both comply with 
+      US law and retain compatibility with all the other &unix;
+      variants that still used DES.</para>
+
+    <para>The solution was to divide up the encryption libraries 
+      so that US users could install the DES libraries and use
+      DES but international users still had an encryption method
+      that could be exported abroad.  This is how &os; came to
+      use MD5 as its default encryption method.  MD5 is believed to
+      be more secure than DES, so installing DES is offered primarily
+      for compatibility reasons.</para>
+
+    <sect2>
+      <title>Recognizing Your Crypt Mechanism</title>
+
+      <para>Currently the library supports DES, MD5 and Blowfish hash
+	functions.  By default &os; uses MD5 to encrypt
+	passwords.</para>
+
+      <para>It is pretty easy to identify which encryption method 
+	&os; is set up to use.  Examining the encrypted passwords in
+	the <filename>/etc/master.passwd</filename> file is one way.
+	Passwords encrypted with the MD5 hash are longer than those
+	encrypted with the DES hash and also begin with the characters
+	<literal>&dollar;1&dollar;</literal>.  Passwords starting with
+	<literal>&dollar;2a&dollar;</literal> are encrypted with the
+	Blowfish hash function.  DES password strings do not
+	have any particular identifying characteristics, but they are
+	shorter than MD5 passwords, and are coded in a 64-character
+	alphabet which does not include the <literal>&dollar;</literal>
+	character, so a relatively short string which does not begin with
+	a dollar sign is very likely a DES password.</para>
+
+      <para>The password format used for new passwords is controlled
+	by the <literal>passwd_format</literal> login capability in
+	<filename>/etc/login.conf</filename>, which takes values of
+	<literal>des</literal>, <literal>md5</literal> or
+	<literal>blf</literal>.  See the &man.login.conf.5; manual page
+	for more information about login capabilities.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="one-time-passwords">
+    <title>One-time Passwords</title>
+    <indexterm><primary>one-time passwords</primary></indexterm>
+    <indexterm>
+      <primary>security</primary>
+      <secondary>one-time passwords</secondary>
+    </indexterm>
+
+    <para>By default, &os; includes suppor for OPIE (One-time Passwords
+      In Everything), which uses the MD5 hash by default.</para>
+
+    <para>There are three different sorts of passwords which we will discuss
+      below.  The first is your usual &unix; style or
+      Kerberos password; we will call this a <quote>&unix; password</quote>.
+      The second sort is the one-time password which is generated by the OPIE
+      &man.opiekey.1; program and accepted by the
+      &man.opiepasswd.1; program
+      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>opiekey</command> program (and
+      sometimes the
+      <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.
+      OPIE secret passwords are not limited to 8 characters like old
+      &unix; passwords<footnote><para>Under &os; the standard login
+      password may be up to 128 characters in length.</para></footnote>,
+      they can be as long as you like.  Passwords of six or
+      seven word long phrases are fairly common.  For the most part, the
+      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 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.  OPIE creates the
+      one-time password by concatenating the seed and the secret password,
+      then applying the 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, OPIE must be
+      reinitialized.</para>
+
+    <para>There are a few programs involved in each system
+      which we will discuss below.  The
+      <command>opiekey</command> program accepts an iteration
+      count, a seed, and a secret password, and generates a one-time
+      password or a consecutive list of one-time passwords.  The
+      <command>opiepasswd</command>
+      program is used to initialize OPIE,
+      and to change passwords, iteration counts, or seeds; it
+      takes either a secret passphrase, or an iteration count,
+      seed, and a one-time password.  The
+      <command>opieinfo</command> program will examine the
+      relevant credentials files
+      (<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>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>opiepasswd</command> over an insecure connection, in
+      conjunction with <command>opiekey</command>
+      over a secure connection,  to do the same.  The third is using
+      <command>opiekey</command> to log in over
+      an insecure connection.  The fourth is using
+      <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 OPIE for the first time, execute the
+        <command>opiepasswd</command> command:</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>opiekey</command>; this might be in the form of 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 <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 press <keycap>Return</keycap>.
+	Then before entering an
+	access password, move over to your secure connection and give it
+	the same parameters:</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 OPIE and 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>
+otp-md5 498 gr4269 ext
+Password: </screen>
+
+      <para>As a side note, the 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>opiekey</command> on.  (There are versions of these for DOS,
+	&windows; and &macos; as well.) They need 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>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>
+    </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>opiekey</command> command to
+	generate a number of one-time passwords beforehand to be printed
+	out and taken with you.  For example:</para>
+
+      <screen>&prompt.user; <userinput>opiekey -n 5 30 zz99999</userinput>
+Using the MD5 algorithm to compute response.
+Reminder: Don't use opiekey from telnet or dial-in sessions.
+Enter secret pass phrase: <userinput>&lt;secret password&gt;</userinput>
+26: JOAN BORE FOSS DES NAY QUIT
+27: LATE BIAS SLAY FOLK MUCH TRIG
+28: SALT TIN ANTI LOON NEAL USE
+29: RIO ODIN GO BYE FURY TIC
+30: GREW JIVE SAN GIRD BOIL PHI</screen>
+
+      <para>The <option>-n 5</option> requests five keys in sequence, the
+	<option>30</option> specifies what the last iteration number
+	should be.  Note that these are printed out in
+	<emphasis>reverse</emphasis> order of eventual use.  If you are
+	really paranoid, you might want to write the results down by hand;
+	otherwise you can cut-and-paste into <command>lpr</command>.  Note
+	that each line shows both the iteration count and the one-time
+	password; you may still find it handy to scratch off passwords as
+	you use them.</para>
+    </sect2>
+
+    <sect2>
+      <title>Restricting Use of &unix; Passwords</title>
+
+      <para>OPIE can restrict the use of &unix; passwords based on the IP
+	address of a login session.  The relevant file
+	is <filename>/etc/opieaccess</filename>, which is present by default.
+	Please check &man.opieaccess.5;
+	for more information on this file and which security considerations
+	you should be aware of when using it.</para>
+	
+      <para>Here is a sample <filename>opieaccess</filename> file:</para>
+
+      <programlisting>permit 192.168.0.0 255.255.0.0</programlisting>
+
+      <para>This line allows users whose IP source address (which is
+	vulnerable to spoofing) matches the specified value and mask,
+	to use &unix; passwords at any time.</para>
+	
+      <para>If no rules in <filename>opieaccess</filename> are matched,
+	the default is to deny non-OPIE logins.</para>
+
+    </sect2>
+  </sect1>
+
+  <sect1 id="tcpwrappers">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Written by: </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <indexterm><primary>TCP Wrappers</primary></indexterm>
+      
+    <title>TCP Wrappers</title>
+
+    <para>Anyone familiar with &man.inetd.8; has probably heard
+      of <acronym>TCP</acronym> Wrappers at some point.  But few
+      individuals seem to fully comprehend its usefulness in a
+      network environment.  It seems that everyone wants to
+      install a firewall to handle network connections.  While a
+      firewall has a wide variety of uses, there are some things
+      that a firewall not handle such as sending text back to the
+      connection originator.  The <acronym>TCP</acronym> software
+      does this and much more.  In the next few sections many of
+      the <acronym>TCP</acronym> Wrappers features will be discussed,
+      and, when applicable, example configuration lines will be
+      provided.</para>
+
+    <para>The <acronym>TCP</acronym> Wrappers software extends the
+      abilities of <command>inetd</command> to provide support for
+      every server daemon under its control.  Using this method it
+      is possible to provide logging support, return messages to
+      connections, permit a daemon to only accept internal connections,
+      etc.  While some of these features can be provided by implementing
+      a firewall, this will add not only an extra layer of protection
+      but go beyond the amount of control a firewall can
+      provide.</para>
+
+    <para>The added functionality of <acronym>TCP</acronym> Wrappers
+      should not be considered a replacement for a good firewall.
+      <acronym>TCP</acronym> Wrappers can be used in conjunction
+      with a firewall or other security enhancements though and
+      it can serve nicely as an extra layer of protection
+      for the system.</para>
+
+    <para>Since this is an extension to the configuration of
+      <command>inetd</command>, the reader is expected have
+      read the <link linkend="network-inetd">inetd configuration</link>
+      section.</para>
+
+    <note>
+      <para>While programs run by &man.inetd.8; are not exactly
+	<quote>daemons</quote>, they have traditionally been called
+	daemons.  This is the term we will use in this section too.</para>
+    </note>
+
+    <sect2>
+      <title>Initial Configuration</title>
+
+      <para>The only requirement of using <acronym>TCP</acronym>
+	Wrappers in &os; is to ensure the <command>inetd</command>
+	server is started from <filename>rc.conf</filename> with the
+	<option>-Ww</option> option; this is the default setting.  Of
+	course,	proper configuration of
+	<filename>/etc/hosts.allow</filename> is also expected, but
+	&man.syslogd.8; will throw messages in the system logs in
+	these cases.</para>
+
+      <note>
+	<para>Unlike other implementations of <acronym>TCP</acronym>
+	  Wrappers, the use of <filename>hosts.deny</filename> has
+	  been deprecated.  All configuration options should be placed
+	  in <filename>/etc/hosts.allow</filename>.</para>
+      </note>
+
+      <para>In the simplest configuration, daemon connection policies
+	are set to either be permitted or blocked depending on the
+	options in <filename>/etc/hosts.allow</filename>.  The default
+	configuration in &os; is to allow a connection to every daemon
+	started with <command>inetd</command>.  Changing this will be
+	discussed only after the basic configuration is covered.</para>
+
+      <para>Basic configuration usually takes the form of
+	<literal>daemon : address : action</literal>.  Where
+	<literal>daemon</literal> is the daemon name which
+	<command>inetd</command> started.  The
+	<literal>address</literal> can be a valid hostname, an
+	<acronym>IP</acronym> address or an IPv6 address enclosed in
+	brackets ([&nbsp;]).  The action field can be either allow
+	or deny	to grant or deny access appropriately.  Keep in mind
+	that configuration works off a first rule match semantic,
+	meaning that the configuration file is scanned in ascending
+	order for a matching rule.  When a match is found the rule
+	is applied and the search process will halt.</para>
+
+      <para>Several other options exist but they will be explained
+	in a later section.  A simple configuration line may easily be
+	constructed from that information alone.  For example, to
+	allow <acronym>POP</acronym>3 connections via the
+	<filename role="package">mail/qpopper</filename> daemon,
+	the following lines should be appended to
+	<filename>hosts.allow</filename>:</para>
+
+      <programlisting># This line is required for POP3 connections:
+qpopper : ALL : allow</programlisting>
+
+      <para>After adding this line, <command>inetd</command> will need
+	restarted.  This can be accomplished by use of the &man.kill.1;
+	command, or with the <parameter>restart</parameter> parameter
+	with <filename>/etc/rc.d/inetd</filename>.</para>
+      </sect2>
+
+      <sect2>
+        <title>Advanced Configuration</title>
+
+      <para><acronym>TCP</acronym> Wrappers has advanced
+	options too; they will allow for more control over the
+	way connections are handled.  In some cases it may be
+	a good idea to return a comment to certain hosts or
+	daemon connections.  In other cases, perhaps a log file
+	should be recorded or an email sent to the administrator.
+	Other situations may require the use of a service for local
+	connections only.  This	is all possible through the use of
+	configuration options known as <literal>wildcards</literal>,
+	expansion characters and external command execution.  The
+	next two sections are written to cover these situations.</para>
+	
+      <sect3>
+	<title>External Commands</title>
+
+	<para>Suppose that a situation occurs where a connection
+	  should be denied yet a reason should be sent to the
+	  individual who attempted to establish that connection.  How
+	  could it be done?  That action can be made possible by
+	  using the <option>twist</option> option.  When a connection
+	  attempt is made, <option>twist</option> will be called to
+	  execute a shell command or script.  An example already exists
+	  in the <filename>hosts.allow</filename> file:</para>
+
+	<programlisting># The rest of the daemons are protected.
+ALL : ALL \
+        : severity auth.info \
+        : twist /bin/echo "You are not welcome to use %d from %h."</programlisting>
+
+	<para>This example shows that the message,
+	  <quote>You are not allowed to use <literal>daemon</literal>
+	  from <literal>hostname</literal>.</quote> will be returned
+	  for any daemon not previously configured in the access file.
+	  This is extremely useful for sending a reply back to the
+	  connection initiator right after the established connection
+	  is dropped.  Note that any message returned
+	  <emphasis>must</emphasis> be wrapped in quote
+	  <literal>"</literal> characters; there are no exceptions to
+	  this rule.</para>
+
+	<warning>
+	  <para>It may be possible to launch a denial of service attack
+	    on the server if an attacker, or group of attackers could
+	    flood these daemons with connection requests.</para>
+	</warning>
+
+	<para>Another possibility is to use the <option>spawn</option>
+	  option in these cases.  Like <option>twist</option>, the
+	  <option>spawn</option> implicitly denies the connection and
+	  may be used to run external shell commands or scripts.
+	  Unlike <option>twist</option>, <option>spawn</option> will
+	  not send a reply back to the individual who established the
+	  connection.  For an example, consider the following
+	  configuration line:</para>
+
+	<programlisting># We do not allow connections from example.com:
+ALL : .example.com \
+	: spawn (/bin/echo %a from %h attempted to access %d &gt;&gt; \
+	  /var/log/connections.log) \
+	: deny</programlisting>
+
+	<para>This will deny all connection attempts from the
+	  <hostid role="fqdn">*.example.com</hostid> domain;
+	  simultaneously logging the hostname, <acronym>IP</acronym>
+	  address and the daemon which they attempted to access in the
+	  <filename>/var/log/connections.log</filename> file.</para>
+
+	<para>Aside from the already explained substitution characters
+	  above, e.g. %a, a few others exist.  See the
+	  &man.hosts.access.5; manual page for the complete list.</para>
+      </sect3>
+
+      <sect3>
+	<title>Wildcard Options</title>
+
+	<para>Thus far the <literal>ALL</literal> example has been used
+	  continuously throughout the examples.  Other options exist
+	  which could extend the functionality a bit further.  For
+	  instance, <literal>ALL</literal> may be used to match every
+	  instance of either a daemon, domain or an
+	  <acronym>IP</acronym> address. Another wildcard available is
+	  <literal>PARANOID</literal> which may be used to match any
+	  host which provides an <acronym>IP</acronym> address that may
+	  be forged.  In other words, <literal>paranoid</literal> may
+	  be used to define an action to be taken whenever a connection
+	  is made from an <acronym>IP</acronym> address that differs
+	  from its hostname.  The following example may shed some more
+	  light on this discussion:</para>
+
+	<programlisting># Block possibly spoofed requests to sendmail:
+sendmail : PARANOID : deny</programlisting>
+
+	<para>In that example all connection requests to
+	  <command>sendmail</command> which have an
+	  <acronym>IP</acronym> address that varies from its hostname
+	  will be denied.</para>
+
+	<caution>
+	  <para>Using the <literal>PARANOID</literal> may severely
+	    cripple servers if the client or server has a broken
+	    <acronym>DNS</acronym> setup.  Administrator discretion
+	    is advised.</para>
+	</caution>
+
+	<para>To learn more about wildcards and their associated
+	  functionality, see the &man.hosts.access.5; manual
+	  page.</para>
+
+	<para>Before any of the specific configuration lines above will
+	  work, the first configuration line should be commented out
+	  in <filename>hosts.allow</filename>.  This was noted at the
+	  beginning of this section.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="kerberosIV">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Mark</firstname>
+	  <surname>Murray</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Mark</firstname>
+	  <surname>Dapoz</surname>
+	  <contrib>Based on a contribution by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title><application>KerberosIV</application></title>
+
+    <para>Kerberos is a network add-on system/protocol that allows users to
+      authenticate themselves through the services of a secure server.
+      Services such as remote login, remote copy, secure inter-system file
+      copying and other high-risk tasks are made considerably safer and more
+      controllable.</para>
+
+    <para>The following instructions can be used as a guide on how to set up
+      Kerberos as distributed for &os;. However, you should refer to the
+      relevant manual pages for a complete description.</para>
+
+    <sect2>
+      <title>Installing <application>KerberosIV</application></title>
+
+      <indexterm><primary>MIT</primary></indexterm>
+      <indexterm>
+	<primary>KerberosIV</primary>
+	<secondary>installing</secondary>
+      </indexterm>
+      <para>Kerberos is an optional component of &os;.  The easiest
+        way to install this software is by selecting the <literal>krb4</literal> or
+        <literal>krb5</literal> distribution in <application>sysinstall</application>
+        during the initial installation of &os;. This will install
+        the <quote>eBones</quote> (KerberosIV) or <quote>Heimdal</quote> (Kerberos5)
+        implementation of Kerberos.  These implementations are
+        included because they are developed outside the USA/Canada and
+        were thus available to system owners outside those countries
+        during the era of restrictive export controls on cryptographic
+        code from the USA.</para>
+
+      <para>Alternatively, the MIT implementation of Kerberos is
+        available from the Ports Collection as
+        <filename role="package">security/krb5</filename>.</para>
+    </sect2>
+
+    <sect2>
+      <title>Creating the Initial Database</title>
+      
+      <para>This is done on the Kerberos server only.  First make sure that
+	you do not have any old Kerberos databases around.  You should change
+	to the directory <filename>/etc/kerberosIV</filename> and check that
+	only the following files are present:</para>
+	  
+      <screen>&prompt.root; <userinput>cd /etc/kerberosIV</userinput>
+&prompt.root; <userinput>ls</userinput>
+README		krb.conf        krb.realms</screen>
+	  
+      <para>If any additional files (such as <filename>principal.*</filename>
+	or <filename>master_key</filename>) exist, then use the
+	<command>kdb_destroy</command> command to destroy the old Kerberos
+	database, or if Kerberos is not running, simply delete the extra
+	files.</para>
+	  
+      <para>You should now edit the <filename>krb.conf</filename> and
+	<filename>krb.realms</filename> files to define your Kerberos realm.
+	In this case the realm will be <literal>EXAMPLE.COM</literal> and the
+	server is <hostid role="fqdn">grunt.example.com</hostid>.  We edit
+	or create the <filename>krb.conf</filename> file:</para>
+	  
+      <screen>&prompt.root; <userinput>cat krb.conf</userinput>
+EXAMPLE.COM
+EXAMPLE.COM grunt.example.com admin server
+CS.BERKELEY.EDU okeeffe.berkeley.edu
+ATHENA.MIT.EDU kerberos.mit.edu
+ATHENA.MIT.EDU kerberos-1.mit.edu
+ATHENA.MIT.EDU kerberos-2.mit.edu
+ATHENA.MIT.EDU kerberos-3.mit.edu
+LCS.MIT.EDU kerberos.lcs.mit.edu
+TELECOM.MIT.EDU bitsy.mit.edu
+ARC.NASA.GOV trident.arc.nasa.gov</screen>
+	  
+      <para>In this case, the other realms do not need to be there.  They are
+	here as an example of how a machine may be made aware of multiple
+	realms.  You may wish to not include them for simplicity.</para>
+	  
+      <para>The first line names the realm in which this system works.  The
+	other lines contain realm/host entries.  The first item on a line is a
+	realm, and the second is a host in that realm that is acting as a
+	<quote>key distribution center</quote>.  The words <literal>admin
+	  server</literal> following a host's name means that host also
+	provides an administrative database server.  For further explanation
+	of these terms, please consult the Kerberos manual pages.</para>
+	  
+      <para>Now we have to add <hostid role="fqdn">grunt.example.com</hostid>
+	to the <literal>EXAMPLE.COM</literal> realm and also add an entry to
+	put all hosts in the <hostid role="domainname">.example.com</hostid>
+	domain in the <literal>EXAMPLE.COM</literal> realm.  The
+	<filename>krb.realms</filename> file would be updated as
+	follows:</para>
+	  
+      <screen>&prompt.root; <userinput>cat krb.realms</userinput>
+grunt.example.com EXAMPLE.COM
+.example.com EXAMPLE.COM
+.berkeley.edu CS.BERKELEY.EDU
+.MIT.EDU ATHENA.MIT.EDU
+.mit.edu ATHENA.MIT.EDU</screen>
+	  
+      <para>Again, the other realms do not need to be there.  They are here as
+	an example of how a machine may be made aware of multiple realms.  You
+	may wish to remove them to simplify things.</para>
+	  
+      <para>The first line puts the <emphasis>specific</emphasis> system into
+	the named realm.  The rest of the lines show how to default systems of
+	a particular subdomain to a named realm.</para>
+	  
+      <para>Now we are ready to create the database.  This only needs to run
+	on the Kerberos server (or Key Distribution Center).  Issue the
+	<command>kdb_init</command> command to do this:</para>
+	  
+      <screen>&prompt.root; <userinput>kdb_init</userinput>
+<prompt>Realm name [default  ATHENA.MIT.EDU ]:</prompt> <userinput>EXAMPLE.COM</userinput>
+You will be prompted for the database Master Password.
+It is important that you NOT FORGET this password.
+		
+<prompt>Enter Kerberos master key:</prompt> </screen>
+	  
+      <para>Now we have to save the key so that servers on the local machine
+	can pick it up.  Use the <command>kstash</command> command to do
+	this:</para>
+	
+      <screen>&prompt.root; <userinput>kstash</userinput>
+	      
+<prompt>Enter Kerberos master key:</prompt>
+
+Current Kerberos master key version is 1.
+
+Master key entered. BEWARE!</screen>
+	
+      <para>This saves the encrypted master password in
+	<filename>/etc/kerberosIV/master_key</filename>.</para>
+    </sect2>
+    
+    <sect2>
+      <title>Making It All Run</title>
+	
+      <indexterm>
+	<primary>KerberosIV</primary>
+	<secondary>initial startup</secondary>
+      </indexterm>
+
+      <para>Two principals need to be added to the database for
+	<emphasis>each</emphasis> system that will be secured with Kerberos.
+	Their names are <literal>kpasswd</literal> and <literal>rcmd</literal>.
+	These two principals are made for each system, with the instance being
+	the name of the individual system.</para>
+	  
+      <para>These daemons, <application>kpasswd</application> and
+	<application>rcmd</application> allow other systems to change Kerberos
+	passwords and run commands like &man.rcp.1;,
+	&man.rlogin.1; and &man.rsh.1;.</para>
+	  
+      <para>Now let us add these entries:</para>
+	    
+      <screen>&prompt.root; <userinput>kdb_edit</userinput>
+Opening database...
+
+<prompt>Enter Kerberos master key:</prompt>
+
+Current Kerberos master key version is 1.
+
+Master key entered.  BEWARE!
+Previous or default values are in [brackets] ,
+enter return to leave the same, or new value.
+
+<prompt>Principal name:</prompt> <userinput>passwd</userinput>
+<prompt>Instance:</prompt> <userinput>grunt</userinput>
+
+&lt;Not found&gt;, <prompt>Create [y] ?</prompt> <userinput>y</userinput>
+
+Principal: passwd, Instance: grunt, kdc_key_ver: 1
+<prompt>New Password:</prompt>                    &lt;---- enter RANDOM here
+Verifying password
+
+<prompt>New Password:</prompt> &lt;---- enter RANDOM here
+
+<prompt>Random password [y] ?</prompt> <userinput>y</userinput>
+
+Principal's new key version = 1
+<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
+<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
+<prompt>Attributes [ 0 ] ?</prompt>
+Edit O.K.
+<prompt>Principal name:</prompt> <userinput>rcmd</userinput>
+<prompt>Instance:</prompt> <userinput>grunt</userinput>
+
+&lt;Not found&gt;, <prompt>Create [y] ?</prompt>
+
+Principal: rcmd, Instance: grunt, kdc_key_ver: 1
+<prompt>New Password:</prompt>		&lt;---- enter RANDOM here
+Verifying password
+
+<prompt>New Password:</prompt>           &lt;---- enter RANDOM here
+
+<prompt>Random password [y] ?</prompt>
+
+Principal's new key version = 1
+<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
+<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
+<prompt>Attributes [ 0 ] ?</prompt>
+Edit O.K.
+<prompt>Principal name:</prompt>         &lt;---- null entry here will cause an exit</screen>
+    </sect2>
+
+    <sect2>
+      <title>Creating the Server File</title>
+      
+      <para>We now have to extract all the instances which define the
+	services on each machine.  For this we use the
+	<command>ext_srvtab</command> command.  This will create a file
+	which must be copied or moved <emphasis>by secure
+	  means</emphasis> to each Kerberos client's
+	<filename>/etc/kerberosIV</filename> directory.  This file must
+	be present on each server and client, and is crucial to the
+	operation of Kerberos.</para>
+	  
+	  
+      <screen>&prompt.root; <userinput>ext_srvtab grunt</userinput>
+<prompt>Enter Kerberos master key:</prompt>
+		
+Current Kerberos master key version is 1.
+
+Master key entered. BEWARE!
+Generating 'grunt-new-srvtab'....</screen>
+	  
+      <para>Now, this command only generates a temporary file which must be
+	renamed to <filename>srvtab</filename> so that all the servers can pick
+	it up.  Use the &man.mv.1; command to move it into place on
+	the original system:</para>
+	  
+      <screen>&prompt.root; <userinput>mv grunt-new-srvtab srvtab</userinput></screen>
+	  
+      <para>If the file is for a client system, and the network is not deemed
+	safe, then copy the
+	<filename><replaceable>client</replaceable>-new-srvtab</filename> to
+	removable media and transport it by secure physical means.  Be sure to
+	rename it to <filename>srvtab</filename> in the client's
+	<filename>/etc/kerberosIV</filename> directory, and make sure it is
+	mode 600:</para>
+	  
+      <screen>&prompt.root; <userinput>mv grumble-new-srvtab srvtab</userinput>
+&prompt.root; <userinput>chmod 600 srvtab</userinput></screen>
+    </sect2>
+    
+    <sect2>
+      <title>Populating the Database</title>
+      
+      <para>We now have to add some user entries into the database.  First
+	let us create an entry for the user <username>jane</username>.  Use the
+	<command>kdb_edit</command> command to do this:</para>
+	  
+      <screen>&prompt.root; <userinput>kdb_edit</userinput>
+Opening database...
+
+<prompt>Enter Kerberos master key:</prompt>
+
+Current Kerberos master key version is 1.
+
+Master key entered.  BEWARE!
+Previous or default values are in [brackets] ,
+enter return to leave the same, or new value.
+
+<prompt>Principal name:</prompt> <userinput>jane</userinput>
+<prompt>Instance:</prompt>
+
+&lt;Not found&gt;, <prompt>Create [y] ?</prompt> <userinput>y</userinput>
+
+Principal: jane, Instance: , kdc_key_ver: 1
+<prompt>New Password:</prompt>                &lt;---- enter a secure password here
+Verifying password
+
+<prompt>New Password:</prompt>                &lt;---- re-enter the password here
+Principal's new key version = 1
+<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
+<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt>
+<prompt>Attributes [ 0 ] ?</prompt>
+Edit O.K.
+<prompt>Principal name:</prompt>		   &lt;---- null entry here will cause an exit</screen>
+    </sect2>
+
+    <sect2>
+      <title>Testing It All Out</title>
+      
+      <para>First we have to start the Kerberos daemons.  Note that if you
+	have correctly edited your <filename>/etc/rc.conf</filename> then this
+	will happen automatically when you reboot.  This is only necessary on
+	the Kerberos server.  Kerberos clients will automatically get what
+	they need from the <filename>/etc/kerberosIV</filename>
+	directory.</para>
+	  
+      <screen>&prompt.root; <userinput>kerberos &amp;</userinput>
+Kerberos server starting
+Sleep forever on error
+Log file is /var/log/kerberos.log
+Current Kerberos master key version is 1.
+
+Master key entered. BEWARE!
+
+Current Kerberos master key version is 1
+Local realm: EXAMPLE.COM
+&prompt.root; <userinput>kadmind -n &amp;</userinput>
+KADM Server KADM0.0A initializing
+Please do not use 'kill -9' to kill this job, use a
+regular kill instead
+
+Current Kerberos master key version is 1.
+
+Master key entered.  BEWARE!</screen>
+	  
+      <para>Now we can try using the <command>kinit</command> command to get a
+	ticket for the ID <username>jane</username> that we created
+	above:</para>
+	  
+      <screen>&prompt.user; <userinput>kinit jane</userinput>
+MIT Project Athena (grunt.example.com)
+Kerberos Initialization for "jane"
+<prompt>Password:</prompt> </screen>
+	  
+      <para>Try listing the tokens using <command>klist</command> to see if we
+	really have them:</para>
+	  
+      <screen>&prompt.user; <userinput>klist</userinput>
+Ticket file:    /tmp/tkt245
+Principal:      jane@EXAMPLE.COM
+
+  Issued           Expires          Principal
+Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
+	  
+      <para>Now try changing the password using &man.passwd.1; to
+	check if the <application>kpasswd</application> daemon can get 
+	authorization to the Kerberos database:</para>
+	  
+      <screen>&prompt.user; <userinput>passwd</userinput>
+realm EXAMPLE.COM
+<prompt>Old password for jane:</prompt>
+<prompt>New Password for jane:</prompt>
+Verifying password
+<prompt>New Password for jane:</prompt>
+Password changed.</screen>
+    </sect2>
+
+    <sect2>
+      <title>Adding <command>su</command> Privileges</title>
+      
+      <para>Kerberos allows us to give <emphasis>each</emphasis> user
+	who needs <username>root</username> privileges their own
+	<emphasis>separate</emphasis> &man.su.1; password.
+	We could now add an ID which is authorized to
+	&man.su.1; to <username>root</username>.  This is
+	controlled by having an instance of <username>root</username>
+	associated with a principal.  Using <command>kdb_edit</command>
+	we can create the entry <literal>jane.root</literal> in the
+	Kerberos database:</para>
+	  
+      <screen>&prompt.root; <userinput>kdb_edit</userinput>
+Opening database...
+
+<prompt>Enter Kerberos master key:</prompt>
+
+Current Kerberos master key version is 1.
+
+Master key entered.  BEWARE!
+Previous or default values are in [brackets] ,
+enter return to leave the same, or new value.
+
+<prompt>Principal name:</prompt> <userinput>jane</userinput>
+<prompt>Instance:</prompt> <userinput>root</userinput>
+
+&lt;Not found&gt;, Create [y] ? y
+
+Principal: jane, Instance: root, kdc_key_ver: 1
+<prompt>New Password:</prompt>                    &lt;---- enter a SECURE password here
+Verifying password
+
+<prompt>New Password:</prompt>    	 	 &lt;---- re-enter the password here
+
+Principal's new key version = 1
+<prompt>Expiration date (enter yyyy-mm-dd) [ 2000-01-01 ] ?</prompt>
+<prompt>Max ticket lifetime (*5 minutes) [ 255 ] ?</prompt> <userinput>12</userinput> &lt;--- Keep this short!
+<prompt>Attributes [ 0 ] ?</prompt>
+Edit O.K.
+<prompt>Principal name:</prompt>		         &lt;---- null entry here will cause an exit</screen>
+	  
+      <para>Now try getting tokens for it to make sure it works:</para>
+      
+      <screen>&prompt.root; <userinput>kinit jane.root</userinput>
+MIT Project Athena (grunt.example.com)
+Kerberos Initialization for "jane.root"
+<prompt>Password:</prompt></screen>
+	  
+      <para>Now we need to add the user to <username>root</username>'s
+	  <filename>.klogin</filename> file:</para>
+	  
+      <screen>&prompt.root; <userinput>cat /root/.klogin</userinput>
+jane.root@EXAMPLE.COM</screen>
+	  
+      <para>Now try doing the &man.su.1;:</para>
+	  
+      <screen>&prompt.user; <userinput>su</userinput>
+<prompt>Password:</prompt></screen>
+	  
+      <para>and take a look at what tokens we have:</para>
+	  
+      <screen>&prompt.root; <userinput>klist</userinput>
+Ticket file:	/tmp/tkt_root_245
+Principal:      jane.root@EXAMPLE.COM
+
+  Issued           Expires          Principal
+May  2 20:43:12  May  3 04:43:12  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>
+    </sect2>
+
+    <sect2>
+      <title>Using Other Commands</title>
+      
+      <para>In an earlier example, we created a principal called
+	<literal>jane</literal> with an instance <literal>root</literal>.
+	This was based on a user with the same name as the principal, and this
+	is a Kerberos default; that a
+	<literal>&lt;principal&gt;.&lt;instance&gt;</literal> of the form
+	<literal>&lt;username&gt;.</literal><username>root</username> will allow
+	that <literal>&lt;username&gt;</literal> to &man.su.1; to
+	<username>root</username> if the necessary entries are in the
+	<filename>.klogin</filename> file in <username>root</username>'s
+	home directory:</para>
+	  
+      <screen>&prompt.root; <userinput>cat /root/.klogin</userinput>
+jane.root@EXAMPLE.COM</screen>
+      
+      <para>Likewise, if a user has in their own home directory lines of the
+	form:</para>
+      
+      <screen>&prompt.user; <userinput>cat ~/.klogin</userinput>
+jane@EXAMPLE.COM
+jack@EXAMPLE.COM</screen>
+	  
+      <para>This allows anyone in the <literal>EXAMPLE.COM</literal> realm
+	who has authenticated themselves as <username>jane</username> or
+	<username>jack</username> (via <command>kinit</command>, see above)
+	to access to <username>jane</username>'s
+	account or files on this system (<hostid>grunt</hostid>) via
+	&man.rlogin.1;, &man.rsh.1; or
+	&man.rcp.1;.</para>
+	  
+      <para>For example, <username>jane</username> now logs into another system using
+	Kerberos:</para>
+	  
+	    <screen>&prompt.user; <userinput>kinit</userinput>
+MIT Project Athena (grunt.example.com)
+<prompt>Password:</prompt>
+&prompt.user; <userinput>rlogin grunt</userinput>
+Last login: Mon May  1 21:14:47 from grumble
+Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+        The Regents of the University of California.   All rights reserved.
+
+FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
+	  
+      <para>Or <username>jack</username> logs into <username>jane</username>'s account on the same machine
+	(<username>jane</username> having
+	set up the <filename>.klogin</filename> file as above, and the person
+	in charge of Kerberos having set up principal
+	<emphasis>jack</emphasis> with a null instance):</para>
+	  
+      <screen>&prompt.user; <userinput>kinit</userinput>
+&prompt.user; <userinput>rlogin grunt -l jane</userinput>
+MIT Project Athena (grunt.example.com)
+<prompt>Password:</prompt>
+Last login: Mon May  1 21:16:55 from grumble
+Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994
+        The Regents of the University of California.   All rights reserved.
+FreeBSD BUILT-19950429 (GR386) #0: Sat Apr 29 17:50:09 SAT 1995</screen>
+    </sect2>
+  </sect1>
+
+  <sect1 id="kerberos5">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tillman</firstname>
+	  <surname>Hodgson</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Mark</firstname>
+	  <surname>Murray</surname>
+	  <contrib>Based on a contribution by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <title><application>Kerberos5</application></title>
+
+    <para>Every &os; release beyond &os;-5.1 includes support
+      only for <application>Kerberos5</application>.  Hence
+      <application>Kerberos5</application> is the only version
+      included, and its configuration is similar in many aspects
+      to that of <application>KerberosIV</application>.  The following
+      information only applies to
+      <application>Kerberos5</application> in post &os;-5.0
+      releases.  Users who wish to use the
+      <application>KerberosIV</application> package may install the
+      <filename role="package">security/krb4</filename> port.</para>
+
+    <para><application>Kerberos</application> is a network add-on
+      system/protocol that allows users to authenticate themselves
+      through the services of a secure server.  Services such as remote
+      login, remote copy, secure inter-system file copying and other
+      high-risk tasks are made considerably safer and more
+      controllable.</para>
+
+    <para><application>Kerberos</application> can be described as an
+      identity-verifying proxy system.  It can also be described as a
+      trusted third-party authentication system.
+      <application>Kerberos</application> provides only one
+      function &mdash; the secure authentication of users on the network.
+      It does not provide authorization functions (what users are
+      allowed to do) or auditing functions (what those users did).
+      After a client and server have used
+      <application>Kerberos</application> to prove their identity, they
+      can also encrypt all of their communications to assure privacy
+      and data integrity as they go about their business.</para>
+
+    <para>Therefore it is highly recommended that
+      <application>Kerberos</application> be used with other security
+      methods which provide authorization and audit services.</para>
+
+    <para>The following instructions can be used as a guide on how to set
+      up <application>Kerberos</application> as distributed for &os;.
+      However, you should refer to the relevant manual pages for a complete
+      description.</para>
+
+    <para>For purposes of demonstrating a <application>Kerberos</application>
+      installation, the various name spaces will be handled as follows:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The <acronym>DNS</acronym> domain (<quote>zone</quote>)
+	  will be example.org.</para>
+      </listitem>
+
+      <listitem>
+	<para>The <application>Kerberos</application> realm will be
+	  EXAMPLE.ORG.</para>
+      </listitem>
+    </itemizedlist>
+
+    <note>
+      <para>Please use real domain names when setting up
+	<application>Kerberos</application> even if you intend to run
+	it internally.  This avoids <acronym>DNS</acronym> problems
+	and assures inter-operation with other
+	<application>Kerberos</application> realms.</para>
+    </note>
+
+    <sect2>
+      <title>History</title>
+      <indexterm>
+	<primary>Kerberos5</primary>
+	<secondary>history</secondary>
+      </indexterm>
+
+      <para><application>Kerberos</application> was created by
+	<acronym>MIT</acronym> as a solution to network security problems.
+	The <application>Kerberos</application> protocol uses strong
+	cryptography so that a client can prove its identity to a server
+	(and vice versa) across an insecure network connection.</para>
+
+      <para><application>Kerberos</application> is both the name of a
+	network authentication protocol and an adjective to describe
+	programs that implement the program
+	(<application>Kerberos</application> telnet, for example).  The
+	current version of the protocol is version 5, described in
+	<acronym>RFC</acronym>&nbsp;1510.</para>
+
+      <para>Several free implementations of this protocol are available,
+	covering a wide range of operating systems.  The Massachusetts
+	Institute of Technology (<acronym>MIT</acronym>), where
+	<application>Kerberos</application> was originally developed,
+	continues to develop their <application>Kerberos</application>
+	package.  It is commonly used in the <acronym>US</acronym>
+	as a cryptography product, as such it
+	has historically been affected by <acronym>US</acronym> export
+	regulations.  The <acronym>MIT</acronym>
+	<application>Kerberos</application> is available as a port
+	(<filename role="package">security/krb5</filename>).  Heimdal
+	<application>Kerberos</application> is another version 5
+	implementation, and was explicitly developed outside of the
+	<acronym>US</acronym> to avoid export
+	regulations (and is thus often included in non-commercial &unix;
+	variants).  The Heimdal <application>Kerberos</application>
+	distribution is available as a port
+	(<filename role="package">security/heimdal</filename>), and a
+	minimal installation of it is included in the base &os;
+	install.</para>
+
+    <para>In order to reach the widest audience, these instructions assume
+	the use of the Heimdal distribution included in &os;.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Setting up a Heimdal <acronym>KDC</acronym></title>
+      <indexterm>
+	<primary>Kerberos5</primary>
+	<secondary>Key Distribution Center</secondary>
+      </indexterm>
+
+      <para>The Key Distribution Center (<acronym>KDC</acronym>) is the
+	centralized authentication service that
+	<application>Kerberos</application> provides &mdash; it is the
+	computer that issues <application>Kerberos</application> tickets.
+	The <acronym>KDC</acronym> is considered <quote>trusted</quote> by
+	all other computers in the <application>Kerberos</application>
+	realm, and thus has heightened security concerns.</para>
+
+    <para>Note that while running the <application>Kerberos</application>
+	server requires very few computing resources, a dedicated machine
+	acting only as a <acronym>KDC</acronym> is recommended for security
+	reasons.</para>
+
+    <para>To begin setting up a <acronym>KDC</acronym>, ensure that your
+	<filename>/etc/rc.conf</filename> file contains the correct
+	settings to act as a <acronym>KDC</acronym> (you may need to adjust
+	paths to reflect your own system):</para>
+
+    <programlisting>kerberos5_server_enable="YES"
+kadmind5_server_enable="YES"</programlisting>
+
+      <para>Next we will set up your <application>Kerberos</application>
+	config file, <filename>/etc/krb5.conf</filename>:</para>
+
+      <programlisting>[libdefaults]
+    default_realm = EXAMPLE.ORG
+[realms]
+    EXAMPLE.ORG = {
+        kdc = kerberos.example.org
+        admin_server = kerberos.example.org
+    }
+[domain_realm]
+    .example.org = EXAMPLE.ORG</programlisting>
+
+      <para>Note that this <filename>/etc/krb5.conf</filename> file implies
+	that your <acronym>KDC</acronym> will have the fully-qualified
+	hostname of <hostid role="fqdn">kerberos.example.org</hostid>.
+	You will need to add a CNAME (alias) entry to your zone file to
+	accomplish this if your <acronym>KDC</acronym> has a different
+	hostname.</para>
+
+      <note>
+	<para>For large networks with a properly configured
+	  <acronym>BIND</acronym> <acronym>DNS</acronym> server, the
+	  above example could be trimmed to:</para>
+
+	<programlisting>[libdefaults]
+      default_realm = EXAMPLE.ORG</programlisting>
+
+	<para>With the following lines being appended to the
+	  <hostid role="fqdn">example.org</hostid> zonefile:</para>
+
+	<programlisting>_kerberos._udp      IN  SRV     01 00 88 kerberos.example.org.
+_kerberos._tcp      IN  SRV     01 00 88 kerberos.example.org.
+_kpasswd._udp       IN  SRV     01 00 464 kerberos.example.org.
+_kerberos-adm._tcp  IN  SRV     01 00 749 kerberos.example.org.
+_kerberos           IN  TXT     EXAMPLE.ORG</programlisting></note>
+
+      <note>
+        <para>For clients to be able to find the
+          <application>Kerberos</application> services, you
+          <emphasis>must</emphasis> have either a fully configured
+          <filename>/etc/krb5.conf</filename> or a minimally configured
+          <filename>/etc/krb5.conf</filename> <emphasis>and</emphasis> a
+          properly configured DNS server.</para>
+      </note>
+
+      <para>Next we will create the <application>Kerberos</application>
+	database.  This database contains the keys of all principals encrypted
+	with a master password.  You are not
+	required to remember this password, it will be stored in a file
+	(<filename>/var/heimdal/m-key</filename>).  To create the master
+	key, run <command>kstash</command> and enter a password.</para>
+
+      <para>Once the master key has been created, you can initialize the
+	database using the <command>kadmin</command> program with the
+	<literal>-l</literal> option (standing for <quote>local</quote>).
+	This option instructs <command>kadmin</command> to modify the
+	database files directly rather than going through the
+	<command>kadmind</command> network service.  This handles the
+	chicken-and-egg problem of trying to connect to the database
+	before it is created.  Once you have the <command>kadmin</command>
+	prompt, use the <command>init</command> command to create your
+	realms initial database.</para>
+
+      <para>Lastly, while still in <command>kadmin</command>, create your
+	first principal using the <command>add</command> command.  Stick
+	to the defaults options for the principal for now, you can always
+	change them later with the <command>modify</command> command.
+	Note that you can use the <literal>?</literal> command at any
+	prompt to see the available options.</para>
+
+      <para>A sample database creation session is shown below:</para>
+
+      <screen>&prompt.root; <userinput>kstash</userinput>
+Master key: <userinput>xxxxxxxx</userinput>
+Verifying password - Master key: <userinput>xxxxxxxx</userinput>
+
+&prompt.root; <userinput>kadmin -l</userinput>
+kadmin> <userinput>init EXAMPLE.ORG</userinput>
+Realm max ticket life [unlimited]:
+kadmin> <userinput>add tillman</userinput>
+Max ticket life [unlimited]:
+Max renewable life [unlimited]:
+Attributes []:
+Password: <userinput>xxxxxxxx</userinput>
+Verifying password - Password: <userinput>xxxxxxxx</userinput></screen>
+
+      <para>Now it is time to start up the <acronym>KDC</acronym> services.
+	Run <command>/etc/rc.d/kerberos start</command> and
+	<command>/etc/rc.d/kadmind start</command> to bring up the
+	services.  Note that you will not have any kerberized daemons running
+	at this point but you should be able to confirm the that the
+	<acronym>KDC</acronym> is functioning by obtaining and listing a
+	ticket for the principal (user) that you just created from the
+	command-line of the <acronym>KDC</acronym> itself:</para>
+
+      <screen>&prompt.user; <userinput>k5init <replaceable>tillman</replaceable></userinput>
+tillman@EXAMPLE.ORG's Password:
+
+&prompt.user; <userinput>k5list</userinput>
+Credentials cache: FILE:<filename>/tmp/krb5cc_500</filename>
+	Principal: tillman@EXAMPLE.ORG
+
+  Issued           Expires          Principal
+Aug 27 15:37:58  Aug 28 01:37:58  krbtgt/EXAMPLE.ORG@EXAMPLE.ORG</screen>
+
+      </sect2>
+
+      <sect2>
+	<title><application>Kerberos</application> enabling a server with
+	  Heimdal services</title>
+
+        <indexterm>
+	  <primary>Kerberos5</primary>
+	  <secondary>enabling services</secondary>
+        </indexterm>
+
+	<para>First, we need a copy of the <application>Kerberos</application>
+	  configuration file, <filename>/etc/krb5.conf</filename>.  To do
+	  so, simply copy it over to the client computer from the
+	  <acronym>KDC</acronym> in a secure fashion (using network utilities,
+	  such as &man.scp.1;, or physically via a
+	  floppy disk).</para>
+
+	<para>Next you need a <filename>/etc/krb5.keytab</filename> file.
+	  This is the major difference between a server providing
+	  <application>Kerberos</application> enabled daemons and a
+	  workstation &mdash; the server must have a
+	  <filename>keytab</filename> file.  This file
+	  contains the servers host key, which allows it and the
+	  <acronym>KDC</acronym> to verify each others identity.  It
+	  must be transmitted to the server in a secure fashion, as the
+	  security of the server can be broken if the key is made public.
+	  This explicitly means that transferring it via a clear text
+	  channel, such as <acronym>FTP</acronym>, is a very bad idea.</para>
+
+	<para>Typically, you transfer to the <filename>keytab</filename>
+	  to the server using the <command>kadmin</command> program.
+	  This is handy because you also need to create the host principal
+	  (the <acronym>KDC</acronym> end of the
+	  <filename>krb5.keytab</filename>) using
+	  <command>kadmin</command>.</para>
+
+	<para>Note that you must have already obtained a ticket and that this
+	  ticket must be allowed to use the <command>kadmin</command>
+	  interface in the <filename>kadmind.acl</filename>.  See the section
+	  titled <quote>Remote administration</quote> in the Heimdal info
+	  pages (<command>info heimdal</command>) for details on designing
+	  access control lists.  If you do not want to enable remote
+	  <command>kadmin</command> access, you can simply securely connect
+	  to the <acronym>KDC</acronym> (via local console,
+	  &man.ssh.1; or <application>Kerberos</application>
+	  &man.telnet.1;) and perform administration locally
+	  using <command>kadmin -l</command>.</para>
+
+	<para>After installing the <filename>/etc/krb5.conf</filename> file,
+	  you can use <command>kadmin</command> from the
+	  <application>Kerberos</application> server.  The
+	  <command>add --random-key</command> command will let you add the
+	  servers host principal, and the <command>ext</command> command
+	  will allow you to extract the servers host principal to its own
+	  keytab.  For example:</para>
+
+	<screen>&prompt.root; <userinput>kadmin</userinput>
+kadmin><userinput> add --random-key host/myserver.example.org</userinput>
+Max ticket life [unlimited]:
+Max renewable life [unlimited]:
+Attributes []:
+kadmin><userinput> ext host/myserver.example.org</userinput>
+kadmin><userinput> exit</userinput></screen>
+
+	<para>Note that the <command>ext</command> command (short for
+	  <quote>extract</quote>) stores the extracted key in
+	  <filename>/etc/krb5.keytab</filename> by default.</para>
+
+	<para>If you do not have <command>kadmind</command> running on the
+	  <acronym>KDC</acronym> (possibly for security reasons) and thus
+	  do not have access to <command>kadmin</command> remotely, you
+	  can add the host principal
+	  (<username>host/myserver.EXAMPLE.ORG</username>) directly on the
+	  <acronym>KDC</acronym> and then extract it to a temporary file
+	  (to avoid over-writing the <filename>/etc/krb5.keytab</filename>
+	  on the <acronym>KDC</acronym>) using something like this:</para>
+
+	<screen>&prompt.root; <userinput>kadmin</userinput>
+kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput>
+kadmin><userinput> exit</userinput></screen>
+
+	<para>You can then securely copy the keytab to the server
+	  computer (using <command>scp</command> or a floppy, for
+	  example).  Be sure to specify a non-default keytab name
+	  to avoid over-writing the keytab on the
+	  <acronym>KDC</acronym>.</para>
+
+	<para>At this point your server can communicate with the
+	  <acronym>KDC</acronym> (due to its <filename>krb5.conf</filename>
+	  file) and it can prove its own identity (due to the
+	  <filename>krb5.keytab</filename> file).  It is now ready for
+	  you to enable some <application>Kerberos</application> services.
+	  For this example we will enable the <command>telnet</command>
+	  service by putting a line like this into your
+	  <filename>/etc/inetd.conf</filename> and then restarting the
+	  &man.inetd.8; service with
+	  <command>/etc/rc.d/inetd restart</command>:</para>
+
+	<programlisting>telnet    stream  tcp     nowait  root    /usr/libexec/telnetd  telnetd -a user</programlisting>
+
+	<para>The critical bit is that the <command>-a</command>
+	  (for authentication) type is set to user.  Consult the
+	  &man.telnetd.8; manual page for more details.</para>
+
+      </sect2>
+
+      <sect2>
+	<title><application>Kerberos</application> enabling a client with Heimdal</title>
+
+	<indexterm>
+	  <primary>Kerberos5</primary>
+	  <secondary>configure clients</secondary>
+	</indexterm>
+
+	<para>Setting up a client computer is almost trivially easy.  As
+	  far as <application>Kerberos</application> configuration goes,
+	  you only need the <application>Kerberos</application>
+	  configuration file, located at <filename>/etc/krb5.conf</filename>.
+	  Simply securely copy it over to the client computer from the
+	  <acronym>KDC</acronym>.</para>
+
+	<para>Test your client computer by attempting to use
+	  <command>kinit</command>, <command>klist</command>, and
+	  <command>kdestroy</command> from the client to obtain, show, and
+	  then delete a ticket for the principal you created above.  You
+	  should also be able to use <application>Kerberos</application>
+	  applications to connect to <application>Kerberos</application>
+	  enabled servers, though if that does not work and obtaining a
+	  ticket does the problem is likely with the server and not with
+	  the client or the <acronym>KDC</acronym>.</para>
+
+	<para>When testing an application like <command>telnet</command>,
+	  try using a packet sniffer (such as &man.tcpdump.1;)
+	  to confirm that your password is not sent in the clear.  Try
+	  using <command>telnet</command> with the <literal>-x</literal>
+	  option, which encrypts the entire data stream (similar to
+	  <command>ssh</command>).</para>
+
+	<para>The core <application>Kerberos</application> client applications
+	  (traditionally named <command>kinit</command>,
+	  <command>klist</command>, <command>kdestroy</command>, and
+	  <command>kpasswd</command>) are installed in
+	  the base &os; install. Note that &os; versions prior to 5.0
+	  renamed them to <command>k5init</command>,
+	  <command>k5list</command>, <command>k5destroy</command>,
+	  <command>k5passwd</command>, and <command>k5stash</command>
+	  (though it is typically only used once).</para>
+
+	<para>Various non-core <application>Kerberos</application> client
+	  applications are also installed by default.  This is where the
+	  <quote>minimal</quote> nature of the base Heimdal installation is
+	  felt: <command>telnet</command> is the only
+	  <application>Kerberos</application> enabled service.</para>
+
+	<para>The Heimdal port adds some of the missing client applications:
+	  <application>Kerberos</application> enabled versions of
+	  <command>ftp</command>, <command>rsh</command>,
+	  <command>rcp</command>, <command>rlogin</command>, and a few
+	  other less common programs. The <acronym>MIT</acronym> port also
+	  contains a full suite of <application>Kerberos</application>
+	  client applications.</para>
+
+      </sect2>
+
+      <sect2>
+	<title>User configuration files: <filename>.k5login</filename> and <filename>.k5users</filename></title>
+
+	<indexterm>
+	  <primary><filename>.k5login</filename></primary>
+	</indexterm>
+
+	<indexterm>
+	  <primary><filename>.k5users</filename></primary>
+	</indexterm>
+
+	<para>Users within a realm typically have their
+	  <application>Kerberos</application> principal (such as
+	  <username>tillman@EXAMPLE.ORG</username>) mapped to a local
+	  user account (such as a local account named
+	  <username>tillman</username>).  Client applications such as
+	  <command>telnet</command> usually do not require a user name
+	  or a principal.</para>
+
+	<para>Occasionally, however, you want to grant access to a local
+	  user account to someone who does not have a matching
+	  <application>Kerberos</application> principal.  For example,
+	  <username>tillman@EXAMPLE.ORG</username> may need access to the
+	  local user account <username>webdevelopers</username>.  Other
+	  principals may also need access to that local account.</para>
+
+	<para>The <filename>.k5login</filename> and
+	  <filename>.k5users</filename> files, placed in a users home
+	  directory, can be used similar to a powerful combination of
+	  <filename>.hosts</filename> and <filename>.rhosts</filename>,
+	  solving this problem. For example, if a
+	  <filename>.k5login</filename> with the following
+	  contents:</para>
+
+	<screen>tillman@example.org
+jdoe@example.org</screen>
+
+	<para>Were to be placed into the home directory of the local user
+	  <username>webdevelopers</username> then both principals listed
+	  would have access to that account without requiring a shared
+	  password.</para>
+
+	<para>Reading the manual pages for these commands is recommended.
+	  Note that the <command>ksu</command> manual page covers
+	  <filename>.k5users</filename>.</para>
+
+      </sect2>
+
+      <sect2>
+	<title><application>Kerberos</application> Tips, Tricks, and Troubleshooting</title>
+
+	<indexterm>
+	  <primary>Kerberos5</primary>
+	  <secondary>troubleshooting</secondary>
+	</indexterm>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>When using either the Heimdal or <acronym>MIT</acronym>
+	      <application>Kerberos</application> ports ensure that your
+	      <envar>PATH</envar> environment variable lists the
+	      <application>Kerberos</application> versions of the client
+	      applications before the system versions.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Do all the computers in your realm have synchronized
+	      time settings?  If not, authentication may fail.
+	      <xref linkend="network-ntp"> describes how to synchronize
+	      clocks using <acronym>NTP</acronym>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para><acronym>MIT</acronym> and Heimdal inter-operate nicely.
+	      Except for <command>kadmin</command>, the protocol for
+	      which is not standardized.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>If you change your hostname, you also need to change your
+	      <username>host/</username> principal and update your keytab.
+	      This also applies to special keytab entries like the
+	      <username>www/</username> principal used for Apache's
+	      <filename role="package">www/mod_auth_kerb</filename>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>All hosts in your realm must be resolvable (both forwards
+	      and reverse) in <acronym>DNS</acronym> (or
+	      <filename>/etc/hosts</filename> as a minimum).  CNAMEs
+	      will work, but the A and PTR records must be correct and in
+	      place. The error message is not very intuitive:
+	      <errorname>Kerberos5 refuses authentication because Read req
+	      failed: Key table entry not found</errorname>.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Some operating systems that may being acting as clients
+	      to your <acronym>KDC</acronym> do not set the permissions
+	      for <command>ksu</command> to be setuid
+	      <username>root</username>.  This means that
+	      <command>ksu</command> does not work, which is a good
+	      security idea but annoying. This is not a
+	      <acronym>KDC</acronym> error.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>With <acronym>MIT</acronym>
+	      <application>Kerberos</application>, if you want to allow a
+	      principal to have a ticket life longer than the default ten
+	      hours, you must use <command>modify_principal</command> in
+	      <command>kadmin</command> to change the maxlife of both the
+	      principal in question and the <username>krbtgt</username>
+	      principal.  Then the principal can use the
+	      <literal>-l</literal> option with <command>kinit</command>
+	      to request a ticket with a longer lifetime.</para>
+	  </listitem>
+
+	  <listitem>
+	    <note><para>If you run a packet sniffer on your
+	      <acronym>KDC</acronym> to add in troubleshooting and then
+	      run <command>kinit</command> from a workstation, you will
+	      notice that your <acronym>TGT</acronym> is sent
+	      immediately upon running <command>kinit</command> &mdash;
+	      even before you type your password!  The explanation is
+	      that the <application>Kerberos</application> server freely
+	      transmits a <acronym>TGT</acronym> (Ticket Granting
+	      Ticket) to any unauthorized request;  however, every
+	      <acronym>TGT</acronym> is encrypted in a key derived from
+	      the user's password.  Therefore, when a user types their
+	      password it is not being sent to the <acronym>KDC</acronym>,
+	      it is being used to decrypt the <acronym>TGT</acronym> that
+	      <command>kinit</command> already obtained. If the decryption
+	      process results in a valid ticket with a valid time stamp,
+	      the user has valid <application>Kerberos</application>
+	      credentials.  These credentials include a session key for
+	      establishing secure communications with the
+	      <application>Kerberos</application> server in the future, as
+	      well as the actual ticket-granting ticket, which is actually
+	      encrypted with the <application>Kerberos</application>
+	      server's own key.  This second layer of encryption is
+	      unknown to the user, but it is what allows the
+	      <application>Kerberos</application> server to verify
+	      the authenticity of each <acronym>TGT</acronym>.</para></note>
+	  </listitem>
+
+	  <listitem>
+	    <para>If you want to use long ticket lifetimes (a week, for
+	      example) and you are using <application>OpenSSH</application>
+	      to connect to the machine where your ticket is stored, make
+	      sure that <application>Kerberos</application>
+	      <option>TicketCleanup</option> is set to <literal>no</literal>
+	      in your <filename>sshd_config</filename> or else your tickets
+	      will be deleted when you log out.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Remember that host principals can have a longer ticket
+	      lifetime as well.  If your user principal has a lifetime of a
+	      week but the host you are connecting to has a lifetime of nine
+	      hours, you will have an expired host principal in your cache
+	      and the ticket cache will not work as expected.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>When setting up a <filename>krb5.dict</filename> file to
+	    prevent specific bad passwords from being used (the manual page
+	    for <command>kadmind</command> covers this briefly), remember
+	    that it only applies to principals that have a password policy
+	    assigned to them.  The <filename>krb5.dict</filename> files
+	    format is simple: one string per line.  Creating a symbolic
+	    link to <filename>/usr/share/dict/words</filename> might be
+	    useful.</para>
+	  </listitem>
+        </itemizedlist>
+
+      </sect2>
+
+      <sect2>
+	<title>Differences with the <acronym>MIT</acronym> port</title>
+
+	<para>The major difference between the <acronym>MIT</acronym>
+	  and Heimdal installs relates to the <command>kadmin</command>
+	  program which has a different (but equivalent) set of commands
+	  and uses a different protocol.  This has a large implications
+	  if your <acronym>KDC</acronym> is <acronym>MIT</acronym> as you
+	  will not be able to use the Heimdal <command>kadmin</command>
+	  program to administer your <acronym>KDC</acronym> remotely
+	  (or vice versa, for that matter).</para>
+
+	<para>The client applications may also take slightly different
+	  command line options to accomplish the same tasks.  Following
+	  the instructions on the <acronym>MIT</acronym>
+	  <application>Kerberos</application> web site
+	  (<ulink url="http://web.mit.edu/Kerberos/www/"></ulink>)
+	  is recommended. Be careful of path issues: the
+	  <acronym>MIT</acronym> port installs into
+	  <filename>/usr/local/</filename> by default, and the
+	  <quote>normal</quote> system applications may be run instead
+	  of <acronym>MIT</acronym> if your <envar>PATH</envar>
+	  environment variable lists the system directories first.</para>
+
+	<note><para>With the <acronym>MIT</acronym>
+	  <filename role="package">security/krb5</filename> port
+	  that is provided by &os;, be sure to read the
+	  <filename>/usr/local/share/doc/krb5/README.FreeBSD</filename>
+	  file installed by the port if you want to understand why logins
+	  via <command>telnetd</command> and <command>klogind</command>
+	  behave somewhat oddly.  Most importantly, correcting the
+	  <quote>incorrect permissions on cache file</quote> behavior
+	  requires that the <command>login.krb5</command> binary be used
+	  for authentication so that it can properly change ownership for
+	  the forwarded credentials.</para></note>
+
+      </sect2>
+
+      <sect2>
+	<title>Mitigating limitations found in <application>Kerberos</application></title>
+
+	<indexterm>
+	  <primary>Kerberos5</primary>
+	  <secondary>limitations and shortcomings</secondary>
+	</indexterm>
+
+	<sect3>
+	 <title><application>Kerberos</application> is an all-or-nothing approach</title>
+
+	  <para>Every service enabled on the network must be modified to
+	    work with <application>Kerberos</application> (or be otherwise
+	    secured against network attacks) or else the users credentials
+	    could be stolen and re-used.  An example of this would be
+	    <application>Kerberos</application> enabling all remote shells
+	    (via <command>rsh</command> and <command>telnet</command>, for
+	    example) but not converting the <acronym>POP3</acronym> mail
+	    server which sends passwords in plain text.</para>
+
+	</sect3>
+
+	<sect3>
+	  <title><application>Kerberos</application> is intended for single-user workstations</title>
+
+	  <para>In a multi-user environment,
+	    <application>Kerberos</application> is less secure.
+	    This is because it stores the tickets in the
+	    <filename>/tmp</filename> directory, which is readable by all
+	    users.  If a user is sharing a computer with several other
+	    people simultaneously (i.e. multi-user), it is possible that
+	    the user's tickets can be stolen (copied) by another
+	    user.</para>
+
+	  <para>This can be overcome with the <literal>-c</literal>
+	    filename command-line option or (preferably) the
+	    <envar>KRB5CCNAME</envar> environment variable, but this
+	    is rarely done. In principal, storing the ticket in the users
+	    home directory and using simple file permissions can mitigate
+	    this problem.</para>
+
+	</sect3>
+
+	<sect3>
+	  <title>The KDC is a single point of failure</title>
+
+	  <para>By design, the <acronym>KDC</acronym> must be as secure as
+	    the master password database is contained on it.  The
+	    <acronym>KDC</acronym> should have absolutely no other
+	    services running on it and should be physically secured.  The
+	    danger is high because <application>Kerberos</application>
+	    stores all passwords encrypted with the same key (the
+	    <quote>master</quote> key), which in turn is stored as a file
+	    on the <acronym>KDC</acronym>.</para>
+
+	  <para>As a side note, a compromised master key is not quite as
+	    bad as one might normally fear.  The master key is only used
+	    to encrypt the <application>Kerberos</application> database
+	    and as a seed for the random number generator.  As long as
+	    access to your <acronym>KDC</acronym> is secure, an attacker
+	    cannot do much with the master key.</para>
+
+	  <para>Additionally, if the <acronym>KDC</acronym> is unavailable
+	    (perhaps due to a denial of service attack or network problems)
+	    the network services are unusable as authentication can not be
+	    performed, a recipe for a denial-of-service attack.  This can
+	    alleviated with multiple <acronym>KDC</acronym>s (a single
+	    master and one or more slaves) and with careful implementation
+	    of secondary or fall-back authentication
+	    (<acronym>PAM</acronym> is excellent for this).</para>
+
+	</sect3>
+
+	<sect3>
+	  <title><application>Kerberos</application> Shortcomings</title>
+
+	  <para><application>Kerberos</application> allows users, hosts
+	    and services to authenticate between themselves.  It does not
+	    have a mechanism to authenticate the <acronym>KDC</acronym>
+	    to the users, hosts or services.  This means that a trojanned
+	    <command>kinit</command> (for example) could record all user
+	    names and passwords.  Something like
+	    <filename role="package">security/tripwire</filename> or
+	    other file system integrity checking tools can alleviate
+	    this.</para>
+
+	</sect3>
+      </sect2>
+
+      <sect2>
+	<title>Resources and further information</title>
+
+	<indexterm>
+	  <primary>Kerberos5</primary>
+	  <secondary>external resources</secondary>
+	</indexterm>
+
+	<itemizedlist>
+	  <listitem>
+	  <para><ulink
+	    url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html">
+	    The <application>Kerberos</application> FAQ</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink url="http://web.mit.edu/Kerberos/www/dialogue.html">Designing
+	    an Authentication System: a Dialog in Four Scenes</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC 1510,
+	    The <application>Kerberos</application> Network Authentication Service
+	    (V5)</ulink></para>
+	</listitem>
+
+	<listitem>
+	  <para><ulink url="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym>
+	    <application>Kerberos</application> home page</ulink></para>
+	</listitem>
+
+	<listitem>
+	<para><ulink url="http://www.pdc.kth.se/heimdal/">Heimdal
+	  <application>Kerberos</application> home page</ulink></para>
+	</listitem>
+
+	</itemizedlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="openssl">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Written by: </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>OpenSSL</title>
+    <indexterm>
+      <primary>security</primary>
+      <secondary>OpenSSL</secondary>
+    </indexterm>
+
+    <para>One feature that many users overlook is the
+      <application>OpenSSL</application> toolkit included
+      in &os;.  <application>OpenSSL</application> provides an
+      encryption transport layer on top of the normal communications
+      layer; thus allowing it to be intertwined with many network
+      applications and services.</para>
+
+    <para>Some uses of <application>OpenSSL</application> may include
+      encrypted authentication of mail clients, web based transactions
+      such as credit card payments and more.  Many ports such as
+      <filename role="package">www/apache13-ssl</filename>, and
+      <filename role="package">mail/sylpheed-claws</filename>
+      will offer compilation support for building with
+      <application>OpenSSL</application>.</para>
+
+    <note>
+      <para>In most cases the Ports Collection will attempt to build
+	the <filename role="package">security/openssl</filename> port
+	unless the <makevar>WITH_OPENSSL_BASE</makevar> make variable
+	is explicitly set to <quote>yes</quote>.</para>
+    </note>
+
+    <para>The version of <application>OpenSSL</application> included
+      in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3),
+      Transport Layer Security v1 (TLSv1) network security protocols
+      and can be used as a general cryptographic library.</para>
+
+    <note>
+      <para>While <application>OpenSSL</application> supports the
+	<acronym>IDEA</acronym> algorithm, it is disabled by default
+	due to United States patents.  To use it, the license should
+	be reviewed and, if the restrictions are acceptable, the
+	<makevar>MAKE_IDEA</makevar> variable must be set in
+	<filename>make.conf</filename>.</para>
+    </note>
+
+    <para>One of the most common uses of
+      <application>OpenSSL</application> is to provide certificates for
+      use with software applications.  These certificates ensure
+      that the credentials of the company or individual are valid
+      and not fraudulent.  If the certificate in question has
+      not been verified by one of the several <quote>Certificate Authorities</quote>,
+      or <acronym>CA</acronym>s, a warning is usually produced.  A
+      Certificate Authority is a company, such as <ulink url="http://www.verisign.com">VeriSign</ulink>, which will
+      sign certificates in order to validate credentials of individuals
+      or companies.  This process has a cost associated with it and
+      is definitely not a requirement for using certificates; however,
+      it can put some of the more paranoid users at ease.</para>
+
+    <sect2>
+      <title>Generating Certificates</title>
+
+      <indexterm>
+	<primary>OpenSSL</primary>
+	<secondary>certificate generation</secondary>
+      </indexterm>
+
+      <para>To generate a certificate, the following command is
+	available:</para>
+
+      <screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput>
+Generating a 1024 bit RSA private key
+................++++++
+.......................................++++++
+writing new private key to 'cert.pem'
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput>
+State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput>
+Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput>
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput>
+Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput>
+Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput>
+Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput>
+
+Please enter the following 'extra' attributes
+to be sent with your certificate request
+A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput>
+An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen>
+
+      <para>Notice the response directly after the
+	<quote>Common Name</quote> prompt shows a domain name.
+	This prompt requires a server name to be entered for
+	verification purposes; placing anything	but a domain name
+	would yield a useless certificate.  Other options, for
+	instance expire time, alternate encryption algorithms, etc.
+	are available.  A complete list may be obtained by viewing
+	the &man.openssl.1; manual page.</para>
+
+      <para>Two files should now exist in
+	the directory in which the aforementioned command was issued.
+	The certificate request, <filename>req.pem</filename>, may be
+	sent to a certificate authority who will validate the credentials
+	that you entered, sign the request and return the certificate to
+	you.  The second file created will be named <filename>cert.pem</filename>
+	and is the private key for the certificate and should be
+	protected at all costs; if this falls in the hands of others it
+	can be used to impersonate you (or your server).</para>
+
+      <para>In cases where a signature from a <acronym>CA</acronym> is
+	not required, a self signed certificate can be created.  First,
+	generate the <acronym>RSA</acronym> key:</para>
+
+      <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out <filename>myRSA.key</filename> 1024</userinput></screen>
+	
+	<para>Next, generate the <acronym>CA</acronym> key:</para>
+
+      <screen>&prompt.root; <userinput>openssl gendsa -des3 -out <filename>myca.key</filename> <filename>myRSA.key</filename></userinput></screen>
+
+      <para>Use this key to create the certificate:</para>
+
+      <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key <filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen>
+
+      <para>Two new files should appear in the directory: a certificate
+	authority signature file, <filename>myca.key</filename> and the
+	certificate itself, <filename>new.crt</filename>.  These should
+	be placed in a directory, preferably under
+	<filename class="directory">/etc</filename>, which is readable
+	only by <username>root</username>.  Permissions of 0700 should be fine for this and
+	they can be set with the <command>chmod</command>
+	utility.</para>
+    </sect2>
+
+    <sect2>
+      <title>Using Certificates, an Example</title>
+
+      <para>So what can these files do?  A good use would be to
+	encrypt connections to the <application>Sendmail</application>
+	<acronym>MTA</acronym>.  This would dissolve the use of clear
+	text authentication for users who send mail via the local
+	<acronym>MTA</acronym>.</para>
+
+      <note>
+	<para>This is not the best use in the world as some
+	  <acronym>MUA</acronym>s will present the user with an
+	  error if they have not installed the certificate locally.
+	  Refer to the documentation included with the software for
+	  more information on certificate installation.</para>
+      </note>
+
+      <para>The following lines should be placed inside the
+	local <filename>.mc</filename> file:</para>
+
+      <programlisting>dnl SSL Options
+define(`confCACERT_PATH',`/etc/certs')dnl
+define(`confCACERT',`/etc/certs/new.crt')dnl
+define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
+define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
+define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>
+
+      <para>Where <filename class="directory">/etc/certs/</filename>
+	is the directory to be used for storing the certificate
+	and key files locally.  The last few requirements are a rebuild
+	of the local <filename>.cf</filename> file.  This is easily
+	achieved by typing <command>make</command>
+	<parameter>install</parameter> within the
+	<filename class="directory">/etc/mail</filename>
+	directory.  Follow that up with <command>make</command>
+	<parameter>restart</parameter> which should start the
+	<application>Sendmail</application> daemon.</para>
+
+      <para>If all went well there will be no error messages in the
+	<filename>/var/log/maillog</filename> file and
+	<application>Sendmail</application> will show up in the process
+	list.</para>
+
+      <para>For a simple test, simply connect to the mail server
+	using the &man.telnet.1; utility:</para>
+
+      <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput>
+Trying 192.0.34.166...
+Connected to <hostid role="fqdn">example.com</hostid>.
+Escape character is '^]'.
+220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
+<userinput>ehlo <replaceable>example.com</replaceable></userinput>
+250-example.com Hello example.com [192.0.34.166], pleased to meet you
+250-ENHANCEDSTATUSCODES
+250-PIPELINING
+250-8BITMIME
+250-SIZE
+250-DSN
+250-ETRN
+250-AUTH LOGIN PLAIN
+250-STARTTLS
+250-DELIVERBY
+250 HELP
+<userinput>quit</userinput>
+221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection
+Connection closed by foreign host.</screen>
+
+      <para>If the <quote>STARTTLS</quote> line appears in the output
+	then everything is working correctly.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="ipsec">
+    <sect1info>
+      <authorgroup>
+        <author>
+  	  <firstname>Nik</firstname>
+	  <surname>Clayton</surname>
+	  <affiliation>
+	    <address><email>nik@FreeBSD.org</email></address>
+          </affiliation>
+          <contrib>Written by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+
+    <indexterm>
+      <primary>IPsec</primary>
+    </indexterm>
+
+    <title>VPN over IPsec</title>
+    <para>Creating a VPN between two networks, separated by the
+      Internet, using FreeBSD gateways.</para>
+ 
+    <sect2>
+      <sect2info>
+        <authorgroup>
+          <author>
+            <firstname>Hiten M.</firstname>
+            <surname>Pandya</surname>
+	    <affiliation>
+	      <address><email>hmp@FreeBSD.org</email></address>
+	    </affiliation>
+	    <contrib>Written by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Understanding IPsec</title>
+
+      <para>This section will guide you through the process of setting
+	up IPsec, and to use it in an environment which consists of
+	FreeBSD and <application>&microsoft.windows; 2000/XP</application>
+	machines, to make them communicate securely.  In order to set up
+	IPsec, it is necessary that you are familiar with the concepts
+	of building a custom kernel (see
+	<xref linkend="kernelconfig">).</para>
+    
+      <para><emphasis>IPsec</emphasis> is a protocol which sits on top
+	of the Internet Protocol (IP) layer.  It allows two or more
+	hosts to communicate in a secure manner (hence the name).  The
+	FreeBSD IPsec <quote>network stack</quote> is based on the
+	<ulink url="http://www.kame.net/">KAME</ulink> implementation,
+	which has support for both protocol families, IPv4 and
+	IPv6.</para>
+
+      <note>
+        <para>FreeBSD contains a <quote>hardware
+        accelerated</quote> IPsec stack, known as <quote>Fast
+        IPsec</quote>, that was obtained from OpenBSD.  It employs
+        cryptographic hardware (whenever possible) via the
+        &man.crypto.4; subsystem to optimize the performance of IPsec.
+        This subsystem is new, and does not support all the features
+        that are available in the KAME version of IPsec.  However, in
+        order to enable hardware-accelerated IPsec, the following
+        kernel option has to be added to your kernel configuration
+        file:</para>
+
+	<indexterm>
+	  <primary>kernel options</primary>
+	  <secondary>FAST_IPSEC</secondary>
+	</indexterm>
+
+        <screen>
+options	  FAST_IPSEC  # new IPsec (cannot define w/ IPSEC)
+        </screen>
+
+        <para> Note, that it is not currently possible to use the
+	  <quote>Fast IPsec</quote> subsystem in lieu of the KAME
+	  implementation of IPsec.  Consult the &man.fast.ipsec.4;
+	  manual page for more information.</para>
+      </note>
+
+      <note>
+	<para>To let firewalls properly track state for &man.gif.4;
+	  tunnels too, you have to enable the
+	  <option>IPSEC_FILTERGIF</option> in your kernel
+	  configuration:</para>
+
+	<screen>
+options   IPSEC_FILTERGIF  #filter ipsec packets from a tunnel
+	</screen>
+      </note>
+  
+      <indexterm>
+	<primary>IPsec</primary>
+	<secondary>ESP</secondary>
+      </indexterm>
+  
+      <indexterm>
+	<primary>IPsec</primary>
+	<secondary>AH</secondary>
+      </indexterm>
+
+      <para>IPsec consists of two sub-protocols:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><emphasis>Encapsulated Security Payload
+	      (ESP)</emphasis>, protects the IP packet data from third
+	    party interference, by encrypting the contents using
+	    symmetric cryptography algorithms (like Blowfish,
+	    3DES).</para>
+        </listitem>
+        <listitem>
+          <para><emphasis>Authentication Header (AH)</emphasis>,
+	    protects the IP packet header from third party interference
+	    and spoofing, by computing a cryptographic checksum and
+	    hashing the IP packet header fields with a secure hashing
+	    function.  This is then followed by an additional header
+	    that contains the hash, to allow the information in the
+	    packet to be authenticated.</para>
+        </listitem>
+      </itemizedlist>
+      
+      <para><acronym>ESP</acronym> and <acronym>AH</acronym> can
+	either be used together or separately, depending on the
+	environment.</para>
+      
+      <indexterm>
+	<primary>VPN</primary>
+      </indexterm>
+
+      <indexterm>
+	<primary>virtual private network</primary>
+	<see>VPN</see>
+      </indexterm>
+
+      <para>IPsec can either be used to directly encrypt the traffic
+	between two hosts (known as <emphasis>Transport
+	  Mode</emphasis>); or to build <quote>virtual tunnels</quote>
+	between two subnets, which could be used for secure
+	communication between two corporate networks (known as
+	<emphasis>Tunnel Mode</emphasis>).  The latter is more commonly
+	known as a <emphasis>Virtual Private Network (VPN)</emphasis>.
+	The &man.ipsec.4; manual page should be consulted for detailed
+	information on the IPsec subsystem in FreeBSD.</para>
+      
+      <para>To add IPsec support to your kernel, add the following
+	options to your kernel configuration file:</para>
+
+      <indexterm>
+	<primary>kernel options</primary>
+	<secondary>IPSEC</secondary>
+      </indexterm>
+
+      <indexterm>
+	<primary>kernel options</primary>
+	<secondary>IPSEC_ESP</secondary>
+      </indexterm>
+
+      <screen>
+options   IPSEC        #IP security
+options   IPSEC_ESP    #IP security (crypto; define w/ IPSEC)
+      </screen>
+
+      <indexterm>
+	<primary>kernel options</primary>
+	<secondary>IPSEC_DEBUG</secondary>
+      </indexterm>
+
+      <para>If IPsec debugging support is desired, the following
+	kernel option should also be added:</para>
+
+      <screen>
+options   IPSEC_DEBUG  #debug for IP security
+      </screen>
+    </sect2>
+
+    <sect2>
+      <title>The Problem</title>
+ 
+      <para>There is no standard for what constitutes a VPN.  VPNs can
+	be implemented using a number of different technologies, each of
+	which have their own strengths and weaknesses.  This section
+	presents a scenario, and the strategies used for implementing a
+	VPN for this scenario.</para>
+    </sect2>
+    
+    <sect2> 
+      <title>The Scenario: Two networks, connected to the Internet, to
+        behave as one</title>
+      
+      <indexterm>
+	<primary>VPN</primary>
+	<secondary>creating</secondary>
+      </indexterm>
+
+      <para>The premise is as follows:</para>
+      
+      <itemizedlist>
+        <listitem>
+          <para>You have at least two sites</para>
+        </listitem>
+        <listitem>
+          <para>Both sites are using IP internally</para>
+        </listitem>
+        <listitem>
+          <para>Both sites are connected to the Internet, through a
+            gateway that is running FreeBSD.</para>
+        </listitem>
+        <listitem>
+          <para>The gateway on each network has at least one public IP
+            address.</para>
+        </listitem>
+        <listitem>
+          <para>The internal addresses of the two networks can be
+            public or private IP addresses, it does not matter.  You can
+            be running NAT on the gateway machine if necessary.</para>
+        </listitem>
+        <listitem>
+          <para>The internal IP addresses of the two networks
+            <emphasis>do not collide</emphasis>.  While I expect it is
+            theoretically possible to use a combination of VPN
+            technology and NAT to get this to work, I expect it to be a
+            configuration nightmare.</para>
+        </listitem>
+      </itemizedlist>
+      
+      <para>If you find that you are trying to connect two networks,
+        both of which, internally, use the same private IP address range
+        (e.g. both of them use <hostid
+        role="ipaddr">192.168.1.x</hostid>), then one of the networks will
+        have to be renumbered.</para>
+ 
+      <para>The network topology might look something like this:</para>
+ 
+      <mediaobject>
+	<imageobject>
+	  <imagedata fileref="security/ipsec-network" align="center">
+	</imageobject>
+
+	<textobject>
+<literallayout class="monospaced">Network #1            [ Internal Hosts ]    Private Net, 192.168.1.2-254
+                      [   Win9x/NT/2K  ]
+                      [      UNIX      ]
+                               |
+                               |
+                        .---[fxp1]---.      Private IP, 192.168.1.1
+                        |   FreeBSD  |
+                        `---[fxp0]---'      Public IP, A.B.C.D
+                               |
+                               |
+                      -=-=- Internet -=-=-
+                               |
+                               |
+                        .---[fxp0]---.      Public IP, W.X.Y.Z
+                        |   FreeBSD  |
+                        `---[fxp1]---'      Private IP, 192.168.2.1
+                               |
+                               |
+Network #2            [ Internal Hosts ]
+                      [   Win9x/NT/2K  ]    Private Net, 192.168.2.2-254
+                      [      UNIX      ]</literallayout>
+	</textobject>
+      </mediaobject>
+ 
+      <para>Notice the two public IP addresses.  I will use the letters to
+        refer to them in the rest of this article.  Anywhere you see those
+        letters in this article, replace them with your own public IP
+        addresses.  Note also that internally, the two gateway
+        machines have .1 IP addresses, and that the two networks have
+        different private IP addresses (<hostid
+        role="ipaddr">192.168.1.x</hostid> and <hostid
+        role="ipaddr">192.168.2.x</hostid> respectively).  All the
+        machines on the private networks have been configured to use the
+        <hostid role="ipaddr">.1</hostid> machine as their default
+        gateway.</para>
+ 
+      <para>The intention is that, from a network point of view, each
+        network should view the machines on the other network as though
+        they were directly attached the same router -- albeit a slightly
+        slow router with an occasional tendency to drop packets.</para>
+ 
+      <para>This means that (for example), machine <hostid
+        role="ipaddr">192.168.1.20</hostid> should be able to run</para>
+ 
+      <programlisting>ping 192.168.2.34</programlisting>
+ 
+      <para>and have it work, transparently.  &windows; machines should
+        be able to see the machines on the other network, browse file
+        shares, and so on, in exactly the same way that they can browse
+        machines on the local network.</para>
+ 
+      <para>And the whole thing has to be secure.  This means that
+        traffic between the two networks has to be encrypted.</para>
+ 
+      <para>Creating a VPN between these two networks is a multi-step
+        process.  The stages are as follows:</para>
+ 
+      <orderedlist>
+        <listitem>
+          <para>Create a <quote>virtual</quote> network link between the two
+            networks, across the Internet.  Test it, using tools like
+            &man.ping.8;, to make sure it works.</para>
+        </listitem>
+ 
+        <listitem>
+          <para>Apply security policies to ensure that traffic between
+            the two networks is transparently encrypted and decrypted as
+            necessary.  Test this, using tools like &man.tcpdump.1;, to
+            ensure that traffic is encrypted.</para>
+        </listitem>
+
+        <listitem>
+          <para>Configure additional software on the FreeBSD gateways,
+            to allow &windows; machines to see one another across the
+            VPN.</para>
+        </listitem>
+      </orderedlist>
+
+    <sect3>
+      <title>Step 1: Creating and testing a <quote>virtual</quote>
+        network link</title>
+ 
+      <para>Suppose that you were logged in to the gateway machine on
+        network #1 (with public IP address <hostid
+        role="ipaddr">A.B.C.D</hostid>, private IP address <hostid
+        role="ipaddr">192.168.1.1</hostid>), and you ran <command>ping
+        192.168.2.1</command>, which is the private address of the machine
+        with IP address <hostid role="ipaddr">W.X.Y.Z</hostid>.  What
+        needs to happen in order for this to work?</para>
+
+      <orderedlist>
+        <listitem>
+          <para>The gateway machine needs to know how to reach <hostid
+            role="ipaddr">192.168.2.1</hostid>.  In other words, it needs
+            to have a route to <hostid
+            role="ipaddr">192.168.2.1</hostid>.</para>
+        </listitem>
+        <listitem>
+          <para>Private IP addresses, such as those in the <hostid
+            role="ipaddr">192.168.x</hostid> range are not supposed to
+            appear on the Internet at large.  Instead, each packet you
+            send to <hostid role="ipaddr">192.168.2.1</hostid> will need
+            to be wrapped up inside another packet.  This packet will need
+            to appear to be from <hostid role="ipaddr">A.B.C.D</hostid>,
+            and it will have to be sent to <hostid
+            role="ipaddr">W.X.Y.Z</hostid>.  This process is called
+            <firstterm>encapsulation</firstterm>.</para>
+        </listitem>
+        <listitem>
+          <para>Once this packet arrives at <hostid
+            role="ipaddr">W.X.Y.Z</hostid> it will need to
+            <quote>unencapsulated</quote>, and delivered to <hostid
+            role="ipaddr">192.168.2.1</hostid>.</para>
+	</listitem>
+      </orderedlist>
+ 
+      <para>You can think of this as requiring a <quote>tunnel</quote>
+        between the two networks.  The two <quote>tunnel mouths</quote> are the IP
+        addresses <hostid role="ipaddr">A.B.C.D</hostid> and <hostid
+        role="ipaddr">W.X.Y.Z</hostid>, and the tunnel must be told the
+        addresses of the private IP addresses that will be allowed to pass
+        through it.  The tunnel is used to transfer traffic with private
+        IP addresses across the public Internet.</para>
+ 
+      <para>This tunnel is created by using the generic interface, or
+        <devicename>gif</devicename> devices on FreeBSD.  As you can
+        imagine, the <devicename>gif</devicename> interface on each
+        gateway host must be configured with four IP addresses; two for
+        the public IP addresses, and two for the private IP
+        addresses.</para>
+ 
+      <para>Support for the gif device must be compiled in to the
+        &os; kernel on both machines.  You can do this by adding the
+        line:</para>
+ 
+      <programlisting>device gif</programlisting>
+ 
+      <para>to the kernel configuration files on both machines, and
+        then compile, install, and reboot as normal.</para>
+ 
+      <para>Configuring the tunnel is a two step process.  First the
+        tunnel must be told what the outside (or public) IP addresses
+        are, using &man.ifconfig.8;.  Then the private IP addresses must be
+        configured using &man.ifconfig.8;.</para>
+ 
+      <para>On the gateway machine on network #1 you would run the
+        following two commands to configure the tunnel.</para>
+ 
+      <programlisting>ifconfig gif0 A.B.C.D W.X.Y.Z
+ifconfig gif0 inet 192.168.1.1 192.168.2.1 netmask 0xffffffff
+      </programlisting>
+ 
+      <para>On the other gateway machine you run the same commands,
+        but with the order of the IP addresses reversed.</para>
+ 
+      <programlisting>ifconfig gif0 W.X.Y.Z A.B.C.D
+ifconfig gif0 inet 192.168.2.1 192.168.1.1 netmask 0xffffffff
+      </programlisting>
+ 
+      <para>You can then run:</para>
+ 
+      <programlisting>ifconfig gif0</programlisting>
+ 
+      <para>to see the configuration.  For example, on the network #1
+        gateway, you would see this:</para>
+ 
+      <screen>&prompt.root; <userinput>ifconfig gif0</userinput>
+gif0: flags=8011&lt;UP,POINTTOPOINT,MULTICAST&gt; mtu 1280
+inet 192.168.1.1 --&gt; 192.168.2.1 netmask 0xffffffff
+physical address inet A.B.C.D --&gt; W.X.Y.Z
+      </screen>
+ 
+      <para>As you can see, a tunnel has been created between the
+        physical addresses <hostid role="ipaddr">A.B.C.D</hostid> and
+        <hostid role="ipaddr">W.X.Y.Z</hostid>, and the traffic allowed
+        through the tunnel is that between <hostid
+        role="ipaddr">192.168.1.1</hostid> and <hostid
+        role="ipaddr">192.168.2.1</hostid>.</para>
+ 
+      <para>This will also have added an entry to the routing table
+        on both machines, which you can examine with the command <command>netstat -rn</command>.
+        This output is from the gateway host on network #1.</para>
+ 
+      <screen>&prompt.root; <userinput>netstat -rn</userinput>
+Routing tables
+ 
+Internet:
+Destination      Gateway       Flags    Refs    Use    Netif  Expire
+...
+192.168.2.1      192.168.1.1   UH        0        0    gif0
+...
+      </screen>
+ 
+      <para>As the <quote>Flags</quote> value indicates, this is a
+        host route, which means that each gateway knows how to reach the
+        other gateway, but they do not know how to reach the rest of
+        their respective networks.  That problem will be fixed
+        shortly.</para>
+ 
+      <para>It is likely that you are running a firewall on both
+        machines.  This will need to be circumvented for your VPN
+        traffic.  You might want to allow all traffic between both
+        networks, or you might want to include firewall rules that
+        protect both ends of the VPN from one another.</para>
+ 
+      <para>It greatly simplifies testing if you configure the
+        firewall to allow all traffic through the VPN.  You can always
+        tighten things up later.  If you are using &man.ipfw.8; on the
+        gateway machines then a command like</para>
+
+      <programlisting>ipfw add 1 allow ip from any to any via gif0</programlisting>
+ 
+      <para>will allow all traffic between the two end points of the
+        VPN, without affecting your other firewall rules.  Obviously
+        you will need to run this command on both gateway hosts.</para>
+ 
+      <para>This is sufficient to allow each gateway machine to ping
+        the other.  On <hostid role="ipaddr">192.168.1.1</hostid>, you
+        should be able to run</para>
+ 
+      <programlisting>ping 192.168.2.1</programlisting>
+ 
+      <para>and get a response, and you should be able to do the same
+        thing on the other gateway machine.</para>
+ 
+      <para>However, you will not be able to reach internal machines
+        on either network yet.  This is because of the routing --
+        although the gateway machines know how to reach one another,
+        they do not know how to reach the network behind each one.</para>
+ 
+      <para>To solve this problem you must add a static route on each
+        gateway machine.  The command to do this on the first gateway
+        would be:</para>
+ 
+      <programlisting>route add 192.168.2.0 192.168.2.1 netmask 0xffffff00
+      </programlisting>
+ 
+      <para>This says <quote>In order to reach the hosts on the
+        network <hostid role="ipaddr">192.168.2.0</hostid>, send the
+        packets to the host <hostid
+        role="ipaddr">192.168.2.1</hostid></quote>.  You will need to
+        run a similar command on the other gateway, but with the
+        <hostid role="ipaddr">192.168.1.x</hostid> addresses
+        instead.</para>
+ 
+      <para>IP traffic from hosts on one network will now be able to
+        reach hosts on the other network.</para>
+ 
+      <para>That has now created two thirds of a VPN between the two
+        networks, in as much as it is <quote>virtual</quote> and it is a
+        <quote>network</quote>.  It is not private yet.  You can test
+        this using &man.ping.8; and &man.tcpdump.1;.  Log in to the
+        gateway host and run</para>
+ 
+      <programlisting>tcpdump dst host 192.168.2.1</programlisting>
+
+      <para>In another log in session on the same host run</para>
+
+      <programlisting>ping 192.168.2.1</programlisting>
+ 
+      <para>You will see output that looks something like this:</para>
+ 
+      <programlisting>
+16:10:24.018080 192.168.1.1 &gt; 192.168.2.1: icmp: echo request
+16:10:24.018109 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
+16:10:25.018814 192.168.1.1 &gt; 192.168.2.1: icmp: echo request
+16:10:25.018847 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
+16:10:26.028896 192.168.1.1 &gt; 192.168.2.1: icmp: echo request
+16:10:26.029112 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
+      </programlisting>
+ 
+      <para>As you can see, the ICMP messages are going back and forth
+        unencrypted.  If you had used the <option>-s</option> parameter to
+        &man.tcpdump.1; to grab more bytes of data from the packets you
+        would see more information.</para>
+ 
+      <para>Obviously this is unacceptable.  The next section will
+        discuss securing the link between the two networks so that it
+        all traffic is automatically encrypted.</para>
+ 
+      <itemizedlist>
+        <title>Summary:</title>
+        <listitem>
+          <para>Configure both kernels with <quote>device gif</quote>.</para>
+        </listitem>
+        <listitem>
+          <para>Edit <filename>/etc/rc.conf</filename> on gateway host
+            #1 and add the following lines (replacing IP addresses as
+            necessary).</para>
+          <programlisting>gifconfig_gif0="A.B.C.D W.X.Y.Z"
+ifconfig_gif0="inet 192.168.1.1 192.168.2.1 netmask 0xffffffff"
+static_routes="vpn"
+route_vpn="192.168.2.0 192.168.2.1 netmask 0xffffff00"
+          </programlisting>
+        </listitem>
+
+        <listitem>
+          <para>Edit your firewall script
+          (<filename>/etc/rc.firewall</filename>, or similar) on both
+          hosts, and add</para>
+
+          <programlisting>ipfw add 1 allow ip from any to any via gif0</programlisting>
+        </listitem>
+        <listitem>
+          <para>Make similar changes to
+            <filename>/etc/rc.conf</filename> on gateway host #2,
+            reversing the order of IP addresses.</para>
+        </listitem>
+      </itemizedlist>
+    </sect3>
+
+    <sect3>
+      <title>Step 2: Securing the link</title>
+ 
+      <para>To secure the link we will be using IPsec.  IPsec provides
+        a mechanism for two hosts to agree on an encryption key, and to
+        then use this key in order to encrypt data between the two
+        hosts.</para>
+ 
+      <para>The are two areas of configuration to be considered here.</para>
+ 
+      <orderedlist>
+        <listitem>
+          <para>There must be a mechanism for two hosts to agree on the
+            encryption mechanism to use.  Once two hosts have agreed on
+            this mechanism there is said to be a <quote>security association</quote>
+            between them.</para>
+        </listitem>
+        <listitem>
+          <para>There must be a mechanism for specifying which traffic
+            should be encrypted.  Obviously, you do not want to encrypt
+            all your outgoing traffic -- you only want to encrypt the
+            traffic that is part of the VPN.  The rules that you put in
+            place to determine what traffic will be encrypted are called
+            <quote>security policies</quote>.</para>
+         </listitem>
+       </orderedlist>
+ 
+       <para>Security associations and security policies are both
+         maintained by the kernel, and can be modified by userland
+         programs.  However, before you can do this you must configure the
+         kernel to support IPsec and the Encapsulated Security Payload
+         (ESP) protocol.  This is done by configuring a kernel with:</para>
+ 
+       <indexterm>
+	 <primary>kernel options</primary>
+	 <secondary>IPSEC</secondary>
+       </indexterm>
+
+       <programlisting>options IPSEC
+options IPSEC_ESP
+       </programlisting>
+ 
+       <para>and recompiling, reinstalling, and rebooting.  As before
+         you will need to do this to the kernels on both of the gateway
+         hosts.</para>
+ 
+       <indexterm>
+	 <primary>IKE</primary>
+       </indexterm>
+
+       <para>You have two choices when it comes to setting up security
+         associations.  You can configure them by hand between two hosts,
+         which entails choosing the encryption algorithm, encryption keys,
+         and so forth, or you can use daemons that implement the Internet
+         Key Exchange protocol (IKE) to do this for you.</para>
+ 
+       <para>I recommend the latter.  Apart from anything else, it is
+         easier to set up.</para>
+ 
+       <indexterm>
+	 <primary>IPsec</primary>
+	 <secondary>security policies</secondary>
+       </indexterm>
+
+       <indexterm>
+	 <primary><command>setkey</command></primary>
+       </indexterm>
+
+       <para>Editing and displaying security policies is carried out
+         using &man.setkey.8;.  By analogy, <command>setkey</command> is
+         to the kernel's security policy tables as &man.route.8; is to
+         the kernel's routing tables.  <command>setkey</command> can
+         also display the current security associations, and to continue
+         the analogy further, is akin to <command>netstat -r</command>
+         in that respect.</para>
+ 
+       <para>There are a number of choices for daemons to manage
+         security associations with FreeBSD.  This article will describe
+         how to use one of these, racoon&nbsp;&mdash; which is available from
+	 <filename role="package">security/ipsec-tools</filename> in the &os; Ports
+	 collection.</para>
+ 
+       <indexterm>
+	 <primary>racoon</primary>
+       </indexterm>
+
+       <para>The <application>racoon</application> software must be run on both gateway hosts.  On each host it
+         is configured with the IP address of the other end of the VPN,
+         and a secret key (which you choose, and must be the same on both
+         gateways).</para>
+ 
+       <para>The two daemons then contact one another, confirm that they
+         are who they say they are (by using the secret key that you
+         configured).  The daemons then generate a new secret key, and use
+         this to encrypt the traffic over the VPN.  They periodically
+         change this secret, so that even if an attacker were to crack one
+         of the keys (which is as theoretically close to unfeasible as it
+         gets) it will not do them much good -- by the time they have cracked
+         the key the two daemons have chosen another one.</para>
+ 
+       <para>The configuration file for racoon is stored in
+         <filename>${PREFIX}/etc/racoon</filename>.  You should find a
+         configuration file there, which should not need to be changed
+         too much.  The other component of racoon's configuration,
+         which you will need to change, is the <quote>pre-shared
+         key</quote>.</para>
+ 
+       <para>The default racoon configuration expects to find this in
+         the file <filename>${PREFIX}/etc/racoon/psk.txt</filename>.  It is important to note
+         that the pre-shared key is <emphasis>not</emphasis> the key that will be used to
+         encrypt your traffic across the VPN link, it is simply a token
+         that allows the key management daemons to trust one another.</para>
+
+       <para><filename>psk.txt</filename> contains a line for each
+         remote site you are dealing with.  In this example, where there
+         are two sites, each <filename>psk.txt</filename> file will contain one line (because
+         each end of the VPN is only dealing with one other end).</para>
+ 
+       <para>On gateway host #1 this line should look like this:</para>
+ 
+       <programlisting>W.X.Y.Z            secret</programlisting>
+ 
+       <para>That is, the <emphasis>public</emphasis> IP address of the remote end,
+         whitespace, and a text string that provides the secret.
+         Obviously, you should not use <quote>secret</quote> as your key -- the normal
+         rules for choosing a password apply.</para>
+ 
+       <para>On gateway host #2 the line would look like this</para>
+ 
+       <programlisting>A.B.C.D            secret</programlisting>
+ 
+       <para>That is, the public IP address of the remote end, and the
+         same secret key.  <filename>psk.txt</filename> must be mode
+         <literal>0600</literal> (i.e., only read/write to
+         <username>root</username>) before racoon will run.</para>
+ 
+       <para>You must run racoon on both gateway machines.  You will
+         also need to add some firewall rules to allow the IKE traffic,
+         which is carried over UDP to the ISAKMP (Internet Security Association
+         Key Management Protocol) port.  Again, this should be fairly early in
+         your firewall ruleset.</para>
+ 
+       <programlisting>ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
+ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
+       </programlisting>
+ 
+       <para>Once racoon is running you can try pinging one gateway host
+         from the other.  The connection is still not encrypted, but
+         racoon will then set up the security associations between the two
+         hosts -- this might take a moment, and you may see this as a
+         short delay before the ping commands start responding.</para>
+ 
+       <para>Once the security association has been set up you can
+         view it using &man.setkey.8;.  Run</para>
+ 
+       <programlisting>setkey -D</programlisting>
+ 
+       <para>on either host to view the security association information.</para>
+ 
+       <para>That's one half of the problem.  They other half is setting
+         your security policies.</para>
+ 
+       <para>To create a sensible security policy, let's review what's
+         been set up so far.  This discussions hold for both ends of the
+         link.</para>
+ 
+       <para>Each IP packet that you send out has a header that contains
+         data about the packet.  The header includes the IP addresses of
+         both the source and destination.  As we already know, private IP
+         addresses, such as the <hostid role="ipaddr">192.168.x.y</hostid>
+         range are not supposed to appear on the public Internet.
+         Instead, they must first be encapsulated inside another packet.
+         This packet must have the public source and destination IP
+         addresses substituted for the private addresses.</para>
+ 
+       <para>So if your outgoing packet started looking like this:</para>
+ 
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="security/ipsec-out-pkt" align="center">
+	  </imageobject>
+
+	  <textobject>
+	    <literallayout class="monospaced">
+  .----------------------.
+  | Src: 192.168.1.1     |
+  | Dst: 192.168.2.1     |
+  | &lt;other header info&gt;  |
+  +----------------------+
+  | &lt;packet data&gt;        |
+  `----------------------'</literallayout>
+	  </textobject>
+	</mediaobject>
+ 
+       <para>Then it will be encapsulated inside another packet, looking
+         something like this:</para>
+ 
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="security/ipsec-encap-pkt" align="center">
+	  </imageobject>
+
+	  <textobject>
+	    <literallayout class="monospaced">
+  .--------------------------.
+  | Src: A.B.C.D             |
+  | Dst: W.X.Y.Z             |
+  | &lt;other header info&gt;      |
+  +--------------------------+
+  | .----------------------. |
+  | | Src: 192.168.1.1     | |
+  | | Dst: 192.168.2.1     | |
+  | | &lt;other header info&gt;  | |
+  | +----------------------+ |
+  | | &lt;packet data&gt;        | |
+  | `----------------------' |
+  `--------------------------'</literallayout>
+	  </textobject>
+	</mediaobject>
+ 
+       <para>This encapsulation is carried out by the
+         <devicename>gif</devicename> device.  As
+         you can see, the packet now has real IP addresses on the outside,
+         and our original packet has been wrapped up as data inside the
+         packet that will be put out on the Internet.</para>
+ 
+       <para>Obviously, we want all traffic between the VPNs to be
+         encrypted.  You might try putting this in to words, as:</para>
+
+       <para><quote>If a packet leaves from <hostid
+         role="ipaddr">A.B.C.D</hostid>, and it is destined for <hostid
+         role="ipaddr">W.X.Y.Z</hostid>, then encrypt it, using the
+         necessary security associations.</quote></para>
+ 
+       <para><quote>If a packet arrives from <hostid
+         role="ipaddr">W.X.Y.Z</hostid>, and it is destined for <hostid
+         role="ipaddr">A.B.C.D</hostid>, then decrypt it, using the
+         necessary security associations.</quote></para>
+ 
+       <para>That's close, but not quite right.  If you did this, all
+         traffic to and from <hostid role="ipaddr">W.X.Y.Z</hostid>, even
+         traffic that was not part of the VPN, would be encrypted.  That's
+         not quite what you want.  The correct policy is as follows</para>
+ 
+       <para><quote>If a packet leaves from <hostid
+         role="ipaddr">A.B.C.D</hostid>, and that packet is encapsulating
+         another packet, and it is destined for <hostid
+         role="ipaddr">W.X.Y.Z</hostid>, then encrypt it, using the
+         necessary security associations.</quote></para>
+ 
+       <para><quote>If a packet arrives from <hostid
+         role="ipaddr">W.X.Y.Z</hostid>, and that packet is encapsulating
+         another packet, and it is destined for <hostid
+         role="ipaddr">A.B.C.D</hostid>, then decrypt it, using the
+         necessary security associations.</quote></para>
+ 
+       <para>A subtle change, but a necessary one.</para>
+ 
+       <para>Security policies are also set using &man.setkey.8;.
+         &man.setkey.8; features a configuration language for defining the
+         policy.  You can either enter configuration instructions via
+         stdin, or you can use the <option>-f</option> option to specify a
+         filename that contains configuration instructions.</para>
+ 
+       <para>The configuration on gateway host #1 (which has the public
+         IP address <hostid role="ipaddr">A.B.C.D</hostid>) to force all
+         outbound traffic to <hostid role="ipaddr">W.X.Y.Z</hostid> to be
+         encrypted is:</para>
+ 
+       <programlisting>
+spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;
+       </programlisting>
+ 
+       <para>Put these commands in a file (e.g.
+       <filename>/etc/ipsec.conf</filename>) and then run</para>
+
+       <screen>&prompt.root; <userinput>setkey -f /etc/ipsec.conf</userinput></screen>
+ 
+       <para><option>spdadd</option> tells &man.setkey.8; that we want
+         to add a rule to the secure policy database.  The rest of this
+         line specifies which packets will match this policy.  <hostid
+         role="ipaddr">A.B.C.D/32</hostid> and <hostid
+         role="ipaddr">W.X.Y.Z/32</hostid> are the IP addresses and
+         netmasks that identify the network or hosts that this policy will
+         apply to.  In this case, we want it to apply to traffic between
+         these two hosts.  <option>ipencap</option> tells the kernel that
+         this policy should only apply to packets that encapsulate other
+         packets.  <option>-P out</option> says that this policy applies
+         to outgoing packets, and <option>ipsec</option> says that the
+         packet will be secured.</para>
+ 
+       <para>The second line specifies how this packet will be
+         encrypted.  <option>esp</option> is the protocol that will be
+         used, while <option>tunnel</option> indicates that the packet
+         will be further encapsulated in an IPsec packet.  The repeated
+         use of <hostid role="ipaddr">A.B.C.D</hostid> and <hostid
+         role="ipaddr">W.X.Y.Z</hostid> is used to select the security
+         association to use, and the final <option>require</option>
+         mandates that packets must be encrypted if they match this
+         rule.</para>
+ 
+       <para>This rule only matches outgoing packets.  You will need a
+         similar rule to match incoming packets.</para>
+ 
+       <programlisting>spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;</programlisting>
+ 
+       <para>Note the <option>in</option> instead of
+         <option>out</option> in this case, and the necessary reversal of
+         the IP addresses.</para>
+ 
+       <para>The other gateway host (which has the public IP address
+         <hostid role="ipaddr">W.X.Y.Z</hostid>) will need similar rules.</para>
+ 
+       <programlisting>spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
+spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;</programlisting>
+ 
+       <para>Finally, you need to add firewall rules to allow ESP and
+        IPENCAP packets back and forth.  These rules will need to be
+        added to both hosts.</para>
+ 
+       <programlisting>ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
+ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
+ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
+ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
+       </programlisting>
+ 
+       <para>Because the rules are symmetric you can use the same rules
+         on each gateway host.</para>
+ 
+       <para>Outgoing packets will now look something like this:</para>
+ 
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="security/ipsec-crypt-pkt" align="center">
+	  </imageobject>
+
+	  <textobject>
+	    <literallayout class="monospaced">
+  .------------------------------.  --------------------------.
+  | Src: A.B.C.D                 |                            |
+  | Dst: W.X.Y.Z                 |                            |
+  | &lt;other header info&gt;          |                            |  Encrypted
+  +------------------------------+                            |  packet.
+  | .--------------------------. |  -------------.            |  contents
+  | | Src: A.B.C.D             | |               |            |  are
+  | | Dst: W.X.Y.Z             | |               |            |  completely
+  | | &lt;other header info&gt;      | |               |            |- secure
+  | +--------------------------+ |               |  Encap'd   |  from third
+  | | .----------------------. | |  -.           |  packet    |  party
+  | | | Src: 192.168.1.1     | | |   |  Original |- with real |  snooping
+  | | | Dst: 192.168.2.1     | | |   |  packet,  |  IP addr   |
+  | | | &lt;other header info&gt;  | | |   |- private  |            |
+  | | +----------------------+ | |   |  IP addr  |            |
+  | | | &lt;packet data&gt;        | | |   |           |            |
+  | | `----------------------' | |  -'           |            |
+  | `--------------------------' |  -------------'            |
+  `------------------------------'  --------------------------'
+	    </literallayout>
+	  </textobject>
+	</mediaobject>
+
+       <para>When they are received by the far end of the VPN they will
+         first be decrypted (using the security associations that have
+         been negotiated by racoon).  Then they will enter the
+         <devicename>gif</devicename> interface, which will unwrap
+         the second layer, until you are left with the innermost
+         packet, which can then travel in to the inner network.</para>
+ 
+       <para>You can check the security using the same &man.ping.8; test from
+         earlier.  First, log in to the
+         <hostid role="ipaddr">A.B.C.D</hostid> gateway machine, and
+         run:</para>
+ 
+       <programlisting>tcpdump dst host 192.168.2.1</programlisting>
+ 
+       <para>In another log in session on the same host run</para>
+ 
+       <programlisting>ping 192.168.2.1</programlisting>
+ 
+       <para>This time you should see output like the following:</para>
+ 
+       <programlisting>XXX tcpdump output</programlisting>
+ 
+       <para>Now, as you can see, &man.tcpdump.1; shows the ESP packets.  If
+         you try to examine them with the <option>-s</option> option you will see
+         (apparently) gibberish, because of the encryption.</para>
+ 
+      <para>Congratulations.  You have just set up a VPN between two
+        remote sites.</para>
+ 
+      <itemizedlist>
+        <title>Summary</title>
+        <listitem>
+          <para>Configure both kernels with:</para>
+ 
+          <programlisting>options IPSEC
+options IPSEC_ESP
+          </programlisting>
+        </listitem>
+        <listitem>
+          <para>Install <filename
+            role="package">security/ipsec-tools</filename>.  Edit
+            <filename>${PREFIX}/etc/racoon/psk.txt</filename> on both
+            gateway hosts, adding an entry for the remote host's IP
+            address and a secret key that they both know.  Make sure
+            this file is mode 0600.</para>
+        </listitem>
+        <listitem>
+          <para>Add the following lines to
+            <filename>/etc/rc.conf</filename> on each host:</para>
+ 
+          <programlisting>ipsec_enable="YES"
+ipsec_file="/etc/ipsec.conf"
+          </programlisting>
+        </listitem>
+        <listitem>
+          <para>Create an <filename>/etc/ipsec.conf</filename> on each
+            host that contains the necessary spdadd lines.  On gateway
+            host #1 this would be:</para>
+ 
+          <programlisting>
+spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec
+  esp/tunnel/A.B.C.D-W.X.Y.Z/require;
+spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P in ipsec
+  esp/tunnel/W.X.Y.Z-A.B.C.D/require;
+</programlisting>
+ 
+          <para>On gateway host #2 this would be:</para>
+ 
+<programlisting>
+spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec
+  esp/tunnel/W.X.Y.Z-A.B.C.D/require;
+spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec
+  esp/tunnel/A.B.C.D-W.X.Y.Z/require;
+</programlisting>
+        </listitem>
+        <listitem>
+          <para>Add firewall rules to allow IKE, ESP, and IPENCAP
+            traffic to both hosts:</para>
+ 
+          <programlisting>
+ipfw add 1 allow udp from A.B.C.D to W.X.Y.Z isakmp
+ipfw add 1 allow udp from W.X.Y.Z to A.B.C.D isakmp
+ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
+ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D
+ipfw add 1 allow ipencap from A.B.C.D to W.X.Y.Z
+ipfw add 1 allow ipencap from W.X.Y.Z to A.B.C.D
+          </programlisting>
+        </listitem>
+      </itemizedlist>
+
+      <para>The previous two steps should suffice to get the VPN up and
+        running.  Machines on each network will be able to refer to one
+        another using IP addresses, and all traffic across the link will
+        be automatically and securely encrypted.</para>
+    </sect3> 
+    </sect2> 
+  </sect1>
+
+  <sect1 id="openssh">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Chern</firstname>
+	  <surname>Lee</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+	<!-- 21 April 2001 -->
+      </authorgroup>
+    </sect1info>
+
+    <title>OpenSSH</title>
+    <indexterm><primary>OpenSSH</primary></indexterm>
+    <indexterm>
+      <primary>security</primary>
+      <secondary>OpenSSH</secondary>
+    </indexterm>
+
+    <para><application>OpenSSH</application> is a set of network connectivity tools used to
+      access remote machines securely.  It can be used as a direct
+      replacement for <command>rlogin</command>,
+      <command>rsh</command>, <command>rcp</command>, and
+      <command>telnet</command>.  Additionally, TCP/IP
+      connections can be tunneled/forwarded securely through SSH.
+      <application>OpenSSH</application> encrypts all traffic to effectively eliminate eavesdropping,
+      connection hijacking, and other network-level attacks.</para>
+
+    <para><application>OpenSSH</application> is maintained by the OpenBSD project, and is based
+      upon SSH v1.2.12 with all the recent bug fixes and updates.  It
+      is compatible with both SSH protocols 1 and 2.</para>
+
+    <sect2>
+      <title>Advantages of Using OpenSSH</title>
+  
+      <para>Normally, when using &man.telnet.1; or &man.rlogin.1;,
+        data is sent over the network in an clear, un-encrypted form.
+        Network sniffers anywhere in between the client and server can
+        steal your user/password information or data transferred in
+        your session.  <application>OpenSSH</application> offers a variety of authentication and
+        encryption methods to prevent this from happening.</para>
+    </sect2>
+
+    <sect2>
+      <title>Enabling sshd</title>
+      <indexterm>
+        <primary>OpenSSH</primary>
+        <secondary>enabling</secondary>
+      </indexterm>
+
+      <para>The 
+        <application>sshd</application> is an option presented during
+        a <literal>Standard</literal> install of &os;.  To see if
+        <application>sshd</application> is enabled, check the
+        <filename>rc.conf</filename> file for:</para>
+      <screen>sshd_enable="YES"</screen>
+      <para>This will load &man.sshd.8;, the daemon program for <application>OpenSSH</application>,
+	the next time your system initializes.  Alternatively, it is
+	possible to use <filename>/etc/rc.d/sshd</filename> &man.rc.8;
+	script to start <application>OpenSSH</application>:</para>
+
+      <programlisting>/etc/rc.d/sshd start</programlisting>
+    </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, recent versions of the
+        <application>OpenSSH</application> servers only accept SSH v2
+        connections.  The client will use version 2 if possible and
+        will fall back to version 1.  The client can also be forced to
+        use one or the other by passing it the <option>-1</option> or
+        <option>-2</option> for version 1 or version 2, respectively.
+        The version 1 compatibility is maintained in the client for
+        backwards compatibility with older versions.</para>
+    </sect2>
+    
+    <sect2>
+      <title>Secure Copy</title>
+      <indexterm>
+        <primary>OpenSSH</primary>
+        <secondary>secure copy</secondary>
+      </indexterm>
+      <indexterm><primary><command>scp</command></primary></indexterm>
+
+      <para>The &man.scp.1; command works similarly to
+	&man.rcp.1;; it copies a file to or from a remote machine,
+	except in a secure fashion.</para>
+
+      <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
+user@example.com's password: <userinput>*******</userinput>
+COPYRIGHT            100% |*****************************|  4735       
+00:00    
+&prompt.root;</screen>
+      <para>Since the fingerprint was already saved for this host in the
+        previous example, it is verified when using &man.scp.1;
+        here.</para>
+
+      <para>The arguments passed to &man.scp.1; are similar
+	to &man.cp.1;, with the file or files in the first
+	argument, and the destination in the second.  Since the file is
+	fetched over the network, through SSH, one or more of the file
+	arguments takes on the form
+	<option>user@host:&lt;path_to_remote_file&gt;</option>.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Configuration</title>
+      <indexterm>
+        <primary>OpenSSH</primary>
+        <secondary>configuration</secondary>
+      </indexterm>
+
+      <para>The system-wide configuration files for both the
+        <application>OpenSSH</application> daemon and client reside
+        within the <filename>/etc/ssh</filename> directory.</para>
+
+      <para><filename>ssh_config</filename> configures the client 
+        settings, while <filename>sshd_config</filename> configures the 
+        daemon.</para>
+
+      <para>Additionally, the <option>sshd_program</option>
+	(<filename>/usr/sbin/sshd</filename> by default), and
+	<option>sshd_flags</option> <filename>rc.conf</filename>
+	options can provide more levels of configuration.</para>
+    </sect2>
+
+    <sect2 id="security-ssh-keygen">
+      <title>ssh-keygen</title>
+
+      <para>Instead of using passwords, &man.ssh-keygen.1; can
+        be used to generate DSA or RSA keys to authenticate a user:</para>
+
+      <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput>
+Generating public/private dsa key pair.
+Enter file in which to save the key (/home/user/.ssh/id_dsa):
+Created directory '/home/user/.ssh'.
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+Your identification has been saved in /home/user/.ssh/id_dsa.
+Your public key has been saved in /home/user/.ssh/id_dsa.pub.
+The key fingerprint is:
+bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com
+</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/id_dsa</filename> or
+        <filename>~/.ssh/id_rsa</filename>, whereas the public key is
+        stored in <filename>~/.ssh/id_dsa.pub</filename> or
+        <filename>~/.ssh/id_rsa.pub</filename>, respectively for DSA and
+        RSA key types.  The public key must be placed in
+        <filename>~/.ssh/authorized_keys</filename> of the remote
+        machine in order for the setup to work.  Similarly, RSA version
+        1 public keys should be placed in
+        <filename>~/.ssh/authorized_keys</filename>.</para>
+
+      <para>This will allow connection to the remote machine based upon
+        SSH keys 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.  &man.ssh-agent.1; can alleviate the strain of
+        repeatedly entering long passphrases, and is explored in the
+        <xref linkend="security-ssh-agent"> section below.</para>
+
+      <warning><para>The various options and files can be different
+        according to the <application>OpenSSH</application> version
+        you have on your system; to avoid problems you should consult
+        the &man.ssh-keygen.1; manual page.</para></warning>
+    </sect2>
+
+    <sect2 id="security-ssh-agent">
+      <title>ssh-agent and ssh-add</title>
+
+      <para>The &man.ssh-agent.1; and &man.ssh-add.1; utilities provide
+        methods for <application>SSH</application> keys to be loaded
+        into memory for use, without needing to type the passphrase
+        each time.</para>
+
+      <para>The &man.ssh-agent.1; utility will handle the authentication
+        using the private key(s) that are loaded into it.
+        &man.ssh-agent.1; should be used to launch another application.
+        At the most basic level, it could spawn a shell or at a more
+        advanced level, a window manager.</para>
+
+      <para>To use &man.ssh-agent.1; in a shell, first it will need to
+        be spawned with a shell as an argument.  Secondly, the
+        identity needs to be added by running &man.ssh-add.1; and
+        providing it the passphrase for the private key.  Once these
+        steps have been completed the user will be able to &man.ssh.1;
+        to any host that has the corresponding public key installed.
+        For example:</para>
+
+      <screen>&prompt.user; ssh-agent <replaceable>csh</replaceable>
+&prompt.user; ssh-add
+Enter passphrase for /home/user/.ssh/id_dsa:
+Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa)
+&prompt.user;</screen>
+
+      <para>To use &man.ssh-agent.1; in X11, a call to
+        &man.ssh-agent.1; will need to be placed in
+        <filename>~/.xinitrc</filename>.  This will provide the
+        &man.ssh-agent.1; services to all programs launched in X11.
+        An example <filename>~/.xinitrc</filename> file might look
+        like this:</para>
+
+      <programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting>
+
+      <para>This would launch &man.ssh-agent.1;, which would in turn
+        launch <application>XFCE</application>, every time X11 starts.
+        Then once that is done and X11 has been restarted so that the
+        changes can take effect, simply run &man.ssh-add.1; to load
+        all of your SSH keys.</para>
+    </sect2>
+
+    <sect2 id="security-ssh-tunneling">
+      <title>SSH Tunneling</title>
+      <indexterm>
+        <primary>OpenSSH</primary>
+        <secondary>tunneling</secondary>
+      </indexterm>
+
+      <para><application>OpenSSH</application> has the ability to create a tunnel to encapsulate
+        another protocol in an encrypted session.</para>
+
+      <para>The following command tells &man.ssh.1; to create a tunnel 
+         for <application>telnet</application>:</para>
+
+       <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput>
+&prompt.user;</screen>
+
+      <para>The <command>ssh</command> command is used with the
+	following options:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><option>-2</option></term>
+	  
+	  <listitem>
+	    <para>Forces <command>ssh</command> to use version 2 of
+	      the protocol. (Do not use if you are working with older
+	      SSH servers)</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-N</option></term>
+
+	  <listitem>
+	    <para>Indicates no command, or tunnel only.  If omitted,
+	      <command>ssh</command> would initiate a normal
+	      session.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-f</option></term>
+
+	  <listitem>
+	    <para>Forces <command>ssh</command> to run in the
+	      background.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-L</option></term>
+
+	  <listitem>
+	    <para>Indicates a local tunnel in
+	      <replaceable>localport:remotehost:remoteport</replaceable>
+	      fashion.</para>
+	  </listitem>
+	  </varlistentry>
+
+	<varlistentry>
+	  <term><option>user@foo.example.com</option></term>
+
+	  <listitem>
+	    <para>The remote SSH server.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+
+      <para>An SSH tunnel works by creating a listen socket on
+	<hostid>localhost</hostid> on the specified port.
+	It then forwards any connection received
+	on the local host/port via the SSH connection to the specified
+	remote host and port.</para>
+
+      <para>In the example, port <replaceable>5023</replaceable> on
+	<hostid>localhost</hostid> is being forwarded to port
+	<replaceable>23</replaceable> on <hostid>localhost</hostid>
+	of the remote machine.  Since <replaceable>23</replaceable> is <application>telnet</application>,
+	this would create a secure <application>telnet</application> session through an SSH tunnel.</para>
+
+      <para>This can be used to wrap any number of insecure TCP
+        protocols such as SMTP, POP3, FTP, etc.</para>
+
+      <example>
+	<title>Using SSH to Create a Secure Tunnel for SMTP</title>
+
+        <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
+user@mailserver.example.com's password: <userinput>*****</userinput>
+&prompt.user; <userinput>telnet localhost 5025</userinput>
+Trying 127.0.0.1...
+Connected to localhost.
+Escape character is '^]'.
+220 mailserver.example.com ESMTP</screen>     
+
+        <para>This can be used in conjunction with an
+          &man.ssh-keygen.1; and additional user accounts to create a
+          more seamless/hassle-free SSH tunneling environment.  Keys
+          can be used in place of typing a password, and the tunnels
+          can be run as a separate user.</para>
+      </example>
+
+      <sect3>
+	<title>Practical SSH Tunneling Examples</title>
+
+	<sect4>
+	  <title>Secure Access of a POP3 Server</title>
+
+	  <para>At work, there is an SSH server that accepts
+	    connections from the outside.  On the same office network
+	    resides a mail server running a POP3 server.  The network,
+	    or network path between your home and office may or may not
+	    be completely trustable.  Because of this, you need to check
+	    your e-mail in a secure manner.  The solution is to create
+	    an SSH connection to your office's SSH server, and tunnel
+	    through to the mail server.</para>
+
+	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
+user@ssh-server.example.com's password: <userinput>******</userinput></screen>
+
+	  <para>When the tunnel is up and running, you can point your
+	    mail client to send POP3 requests to <hostid>localhost</hostid>
+	    port 2110.  A connection here will be forwarded securely across
+	    the tunnel to <hostid>mail.example.com</hostid>.</para>
+	</sect4>
+
+	<sect4>
+	  <title>Bypassing a Draconian Firewall</title>
+
+	  <para>Some network administrators impose extremely draconian
+	    firewall rules, filtering not only incoming connections,
+	    but outgoing connections.  You may be only given access
+	    to contact remote machines on ports 22 and 80 for SSH
+	    and web surfing.</para>
+
+	  <para>You may wish to access another (perhaps non-work
+	    related) service, such as an Ogg Vorbis server to stream
+	    music.  If this Ogg Vorbis server is streaming on some other
+	    port than 22 or 80, you will not be able to access it.</para>
+
+	  <para>The solution is to create an SSH connection to a machine
+	    outside of your network's firewall, and use it to tunnel to
+	    the Ogg Vorbis server.</para>
+
+	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput>
+user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen>
+
+	  <para>Your streaming client can now be pointed to
+	    <hostid>localhost</hostid> port 8888, which will be
+	    forwarded over to <hostid>music.example.com</hostid> port
+	    8000, successfully evading the firewall.</para>
+        </sect4>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>The <varname>AllowUsers</varname> Users Option</title>
+
+      <para>It is often a good idea to limit which users can log in and
+        from where.  The <literal>AllowUsers</literal> option is a good
+        way to accomplish this.  For example, to only allow the
+        <username>root</username> user to log in from
+        <hostid role="ipaddr">192.168.1.32</hostid>, something like this
+        would be appropriate in the
+        <filename>/etc/ssh/sshd_config</filename> file:</para>
+
+      <programlisting>AllowUsers root@192.168.1.32</programlisting>
+
+      <para>To allow the user <username>admin</username> to log in from
+        anywhere, just list the username by itself:</para>
+
+      <programlisting>AllowUsers admin</programlisting>
+
+      <para>Multiple users should be listed on the same line, like so:</para>
+
+      <programlisting>AllowUsers root@192.168.1.32 admin</programlisting>
+
+      <note>
+        <para>It is important that you list each user that needs to
+          log in to this machine; otherwise they will be locked out.</para>
+      </note>
+
+      <para>After making changes to
+         <filename>/etc/ssh/sshd_config</filename> you must tell
+         &man.sshd.8; to reload its config files, by running:</para>
+
+      <screen>&prompt.root; <userinput>/etc/rc.d/sshd reload</userinput></screen>
+    </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; &man.ssh.config.5;</para>
+      <para>&man.sshd.8; &man.sftp-server.8; &man.sshd.config.5;</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="fs-acl">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <indexterm>
+      <primary>ACL</primary>
+    </indexterm>
+    <title>File System Access Control Lists</title>
+
+    <para>In conjunction with file system enhancements like snapshots, FreeBSD 5.0
+      and later offers the security of File System Access Control Lists
+      (<acronym>ACLs</acronym>).</para>
+
+    <para>Access Control Lists extend the standard &unix;
+      permission model in a highly compatible (&posix;.1e) way.  This feature
+      permits an administrator to make use of and take advantage of a
+      more sophisticated security model.</para>
+
+    <para>To enable <acronym>ACL</acronym> support for <acronym>UFS</acronym>
+      file systems, the following:</para>
+
+    <programlisting>options UFS_ACL</programlisting>
+
+    <para>must be compiled into the kernel.  If this option has
+      not been compiled in, a warning message will be displayed
+      when attempting to mount a file system supporting <acronym>ACLs</acronym>.
+      This option is included in the <filename>GENERIC</filename> kernel.
+      <acronym>ACLs</acronym> rely on extended attributes being enabled on
+      the file system.  Extended attributes are natively supported in the next generation
+      &unix; file system, <acronym>UFS2</acronym>.</para>
+
+    <note><para>A higher level of administrative overhead is required to
+      configure extended attributes on <acronym>UFS1</acronym> than on
+      <acronym>UFS2</acronym>.  The performance of extended attributes
+      on <acronym>UFS2</acronym> is also substantially higher.  As a
+      result, <acronym>UFS2</acronym> is generally recommended in preference
+      to <acronym>UFS1</acronym> for use with access control lists.</para></note>
+
+    <para><acronym>ACLs</acronym> are enabled by the mount-time administrative
+      flag, <option>acls</option>, which may be added to <filename>/etc/fstab</filename>.
+      The mount-time flag can also be automatically set in a persistent manner using
+      &man.tunefs.8; to modify a superblock <acronym>ACLs</acronym> flag in the
+      file system header.  In general, it is preferred to use the superblock flag
+      for several reasons:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The mount-time <acronym>ACLs</acronym> flag cannot be changed by a
+	remount (&man.mount.8; <option>-u</option>), only by means of a complete
+	&man.umount.8; and fresh &man.mount.8;.  This means that
+	<acronym>ACLs</acronym> cannot be enabled on the root file system after boot.
+	It also means that you cannot change the disposition of a file system once
+	it is in use.</para>
+      </listitem>
+
+      <listitem>
+	<para>Setting the superblock flag will cause the file system to always be
+	mounted with <acronym>ACLs</acronym> enabled even if there is not an
+	<filename>fstab</filename> entry or if the devices re-order.  This prevents
+	accidental mounting of the file system without <acronym>ACLs</acronym>
+	enabled, which can result in <acronym>ACLs</acronym> being improperly enforced,
+	and hence security problems.</para>
+      </listitem>
+    </itemizedlist>
+
+    <note><para>We may change the <acronym>ACLs</acronym> behavior to allow the flag to
+      be enabled without a complete fresh &man.mount.8;, but we consider it desirable to
+      discourage accidental mounting without <acronym>ACLs</acronym> enabled, because you
+      can shoot your feet quite nastily if you enable <acronym>ACLs</acronym>, then disable
+      them, then re-enable them without flushing the extended attributes.  In general, once
+      you have enabled <acronym>ACLs</acronym> on a file system, they should not be disabled,
+      as the resulting file protections may not be compatible with those intended by the
+      users of the system, and re-enabling <acronym>ACLs</acronym> may re-attach the previous
+      <acronym>ACLs</acronym> to files that have since had their permissions changed,
+      resulting in other unpredictable behavior.</para></note>
+      
+    <para>File systems with <acronym>ACLs</acronym> enabled will show a <literal>+</literal>
+      (plus) sign in their permission settings when viewed.  For example:</para>
+
+    <programlisting>drwx------  2 robert  robert  512 Dec 27 11:54 private
+drwxrwx---+ 2 robert  robert  512 Dec 23 10:57 directory1
+drwxrwx---+ 2 robert  robert  512 Dec 22 10:20 directory2
+drwxrwx---+ 2 robert  robert  512 Dec 27 11:57 directory3
+drwxr-xr-x  2 robert  robert  512 Nov 10 11:54 public_html</programlisting>
+
+    <para>Here we see that the <filename>directory1</filename>,
+      <filename>directory2</filename>, and <filename>directory3</filename>
+      directories are all taking advantage of <acronym>ACLs</acronym>.  The
+      <filename>public_html</filename> directory is not.</para>
+
+    <sect2>
+      <title>Making Use of <acronym>ACL</acronym>s</title>
+
+      <para>The file system <acronym>ACL</acronym>s can be viewed by the
+	&man.getfacl.1; utility.  For instance, to view the
+	<acronym>ACL</acronym> settings on the <filename>test</filename>
+	file, one would use the command:</para>
+
+      <screen>&prompt.user; <userinput>getfacl <filename>test</filename></userinput>
+	#file:test
+	#owner:1001
+	#group:1001
+	user::rw-
+	group::r--
+	other::r--</screen>
+
+      <para>To change the <acronym>ACL</acronym> settings on this file,
+	invoke the &man.setfacl.1; utility.  Observe:</para>
+
+      <screen>&prompt.user; <userinput>setfacl -k <filename>test</filename></userinput></screen>
+
+      <para>The <option>-k</option> flag will remove all of the
+	currently defined <acronym>ACL</acronym>s from a file or file
+	system.  The more preferable method would be to use
+	<option>-b</option> as it leaves the basic fields required for
+	<acronym>ACL</acronym>s to work.</para>
+
+      <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- <filename>test</filename></userinput></screen>
+
+      <para>In the aforementioned command, the <option>-m</option>
+	option was used to modify the default <acronym>ACL</acronym>
+	entries.  Since there were no pre-defined entries, as they were
+	removed by the previous command, this will restore the default
+	options and assign the options listed.  Take care to notice that
+	if you add a user or group which does not exist on the system,
+	an <errorname>Invalid argument</errorname> error will be printed
+	to <devicename>stdout</devicename>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="security-portaudit">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+
+    <indexterm>
+      <primary>Portaudit</primary>
+    </indexterm>
+    <title>Monitoring Third Party Security Issues</title>
+
+    <para>In recent years, the security world has made many improvements
+      to how vulnerability assessment is handled.  The threat of system
+      intrusion increases as third party utilities are installed and
+      configured for virtually any operating system available
+      today.</para>
+
+    <para>Vulnerability assessment is a key factor in security, and
+      while &os; releases advisories for the base system, doing so
+      for every third party utility is beyond the &os; Project's
+      capability.  There is a way to mitigate third party
+      vulnerabilities and warn administrators of known security
+      issues.  A &os; add on utility known as
+      <application>Portaudit</application> exists solely for this
+      purpose.</para>
+
+    <para>The <filename role="port">security/portaudit</filename> port
+      polls a database, updated and maintained by the &os; Security
+      Team and ports developers, for known security issues.</para>
+
+    <para>To begin using <application>Portaudit</application>, one
+      must install it from the Ports Collection:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/ports/security/portaudit &amp;&amp; make install clean</userinput></screen>
+
+    <para>During the install process, the configuration files for
+      &man.periodic.8; will be updated, permitting
+      <application>Portaudit</application> output in the daily security
+      runs.  Ensure the daily security run emails, which are sent to
+      <username>root</username>'s email account, are being read.  No
+      more configuration will be required here.</para>
+
+    <para>After installation, an administrator can update the database
+      and view known vulnerabilities in installed packages by invoking
+      the following command:</para>
+
+    <screen>&prompt.root; <userinput>portaudit -Fda</userinput></screen>
+
+    <note>
+      <para>The database will automatically be updated during the
+	&man.periodic.8; run; thus, the previous command is completely
+	optional.  It is only required for the following
+	examples.</para>
+    </note>
+
+    <para>To audit the third party utilities installed as part of
+      the Ports Collection at anytime, an administrator need only run
+      the following command:</para>
+
+    <screen>&prompt.root; <userinput>portaudit -a</userinput></screen>
+
+    <para><application>Portaudit</application> will produce something
+      like this for vulnerable packages:</para>
+
+    <programlisting>Affected package: cups-base-1.1.22.0_1
+Type of problem: cups-base -- HPGL buffer overflow vulnerability.
+Reference: &lt;http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html&gt;
+
+1 problem(s) in your installed packages found.
+
+You are advised to update or deinstall the affected package(s) immediately.</programlisting>
+
+    <para>By pointing a web browser to the <acronym>URL</acronym> shown,
+      an administrator may obtain more information about the
+      vulnerability in question.  This will include versions affected,
+      by &os; Port version, along with other web sites which may contain
+      security advisories.</para>
+
+    <para>In short, <application>Portaudit</application> is a powerful
+      utility and extremely useful when coupled with the
+      <application>Portupgrade</application> port.</para>
+  </sect1>
+
+  <sect1 id="security-advisories">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <indexterm>
+      <primary>FreeBSD Security Advisories</primary>
+    </indexterm>
+    <title>&os; Security Advisories</title>
+
+    <para>Like many production quality operating systems, &os; publishes
+      <quote>Security Advisories</quote>.  These advisories are usually
+      mailed to the security lists and noted in the Errata only
+      after the appropriate releases have been patched.  This section
+      will work to explain what an advisory is, how to understand it,
+      and what measures to take in order to patch a system.</para>
+
+    <sect2>
+      <title>What does an advisory look like?</title>
+
+      <para>The &os; security advisories look similar to the one below,
+	taken from the &a.security-notifications.name; mailing list.</para>
+
+      <programlisting>=============================================================================
+&os;-SA-XX:XX.UTIL                                     Security Advisory
+                                                          The &os; Project
+
+Topic:          denial of service due to some problem<co id="co-topic">
+
+Category:       core<co id="co-category">
+Module:         sys<co id="co-module">
+Announced:      2003-09-23<co id="co-announce">
+Credits:        Person@EMAIL-ADDRESS<co id="co-credit">
+Affects:        All releases of &os;<co id="co-affects">
+                &os; 4-STABLE prior to the correction date
+Corrected:      2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE)
+                2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6)
+                2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15)
+                2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8)
+                2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18)
+                2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21)
+                2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33)
+                2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43)
+                2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39)<co id="co-corrected">
+<acronym>CVE</acronym> Name:	CVE-XXXX-XXXX<co id="co-cve">
+
+For general information regarding FreeBSD Security Advisories,
+including descriptions of the fields above, security branches, and the
+following sections, please visit
+http://www.FreeBSD.org/security/.
+
+I.   Background<co id="co-backround">
+
+
+II.  Problem Description<co id="co-descript">
+
+
+III. Impact<co id="co-impact">
+
+
+IV.  Workaround<co id="co-workaround">
+
+
+V.   Solution<co id="co-solution">
+
+
+VI.  Correction details<co id="co-details">
+
+
+VII. References<co id="co-ref"></programlisting>
+
+
+      <calloutlist>
+	<callout arearefs="co-topic">
+	  <para>The <literal>Topic</literal> field indicates exactly what the problem is.
+	    It is basically an introduction to the current security
+	    advisory and notes the utility with the
+	    vulnerability.</para>
+	</callout>
+
+	<callout arearefs="co-category">
+	  <para>The <literal>Category</literal> refers to the affected part of the system
+	    which may be one of <literal>core</literal>, <literal>contrib</literal>, or <literal>ports</literal>.  The <literal>core</literal>
+	    category means that the vulnerability affects a core
+	    component of the &os; operating system.  The <literal>contrib</literal>
+	    category means that the vulnerability affects software
+	    contributed to the &os; Project, such as
+	    <application>sendmail</application>.  Finally the <literal>ports</literal>
+	    category indicates that the vulnerability affects add on
+	    software available as part of the Ports Collection.</para>
+	</callout>
+
+	<callout arearefs="co-module">
+	  <para>The <literal>Module</literal> field refers to the component location, for
+	    instance <literal>sys</literal>.  In this example, we see that the module,
+	    <literal>sys</literal>, is affected; therefore, this vulnerability
+	    affects a component used within the kernel.</para>
+	</callout>
+
+	<callout arearefs="co-announce">
+	  <para>The <literal>Announced</literal> field reflects the date said security
+	    advisory was published, or announced to the world.  This
+	    means that the security team has verified that the problem
+	    does exist and that a patch has been committed to the &os;
+	    source code repository.</para>
+	</callout>
+
+	<callout arearefs="co-credit">
+	  <para>The <literal>Credits</literal> field gives credit to the individual or
+	    organization who noticed the vulnerability and reported
+	    it.</para>
+	</callout>
+
+	<callout arearefs="co-affects">
+	  <para>The <literal>Affects</literal> field explains which releases of &os; are
+	    affected by this vulnerability.  For the kernel, a quick
+	    look over the output from <command>ident</command> on the
+	    affected files will help in determining the revision.
+	    For ports, the version number is listed after the port name
+	    in <filename>/var/db/pkg</filename>.  If the system does not
+	    sync with the &os; <acronym>CVS</acronym> repository and rebuild
+	    daily, chances are that it is affected.</para>
+	</callout>
+
+	<callout arearefs="co-corrected">
+	  <para>The <literal>Corrected</literal> field indicates the date, time, time
+	    offset, and release that was corrected.</para>
+	</callout>
+
+	<callout arearefs="co-cve">
+	  <para>Reserved for the identification information used to look up
+	    vulnerabilities in the Common Vulnerabilities Database system.</para>
+	</callout>
+
+	<callout arearefs="co-backround">
+	  <para>The <literal>Background</literal> field gives information on exactly what
+	    the affected utility is.  Most of the time this is why
+	    the utility exists in &os;, what it is used for, and a bit
+	    of information on how the utility came to be.</para>
+	</callout>
+
+	<callout arearefs="co-descript">
+	  <para>The <literal>Problem Description</literal> field explains the security hole
+	    in depth.  This can include information on flawed code, or
+	    even how the utility could be maliciously used to open
+	    a security hole.</para>
+	</callout>
+
+	<callout arearefs="co-impact">
+	  <para>The <literal>Impact</literal> field describes what type of impact the
+	    problem could have on a system.  For example, this could
+	    be anything from a denial of service attack, to extra
+	    privileges available to users, or even giving the attacker
+	    superuser access.</para>
+	</callout>
+
+	<callout arearefs="co-workaround">
+	  <para>The <literal>Workaround</literal> field offers a feasible workaround to
+	    system administrators who may be incapable of upgrading
+	    the system.  This may be due to time constraints, network
+	    availability, or a slew of other reasons.  Regardless,
+	    security should not be taken lightly, and an affected system
+	    should either be patched or the security hole workaround
+	    should be implemented.</para>
+	</callout>
+
+	<callout arearefs="co-solution">
+	  <para>The <literal>Solution</literal> field offers instructions on patching the
+	    affected system.  This is a step by step tested and verified
+	    method for getting a system patched and working
+	    securely.</para>
+	</callout>
+
+	<callout arearefs="co-details">
+	  <para>The <literal>Correction Details</literal> field displays the
+	    <acronym>CVS</acronym> branch or release name with the
+	    periods changed to underscore characters.  It also shows
+	    the revision number of the affected files within each
+	    branch.</para>
+	</callout>
+
+	<callout arearefs="co-ref">
+	  <para>The <literal>References</literal> field usually offers sources of other
+	    information.  This can included web <acronym>URL</acronym>s,
+	    books, mailing lists, and newsgroups.</para>
+	</callout>
+      </calloutlist>
+    </sect2>
+  </sect1>
+
+  <sect1 id="security-accounting">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Tom</firstname>
+	  <surname>Rhodes</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <indexterm>
+      <primary>Process Accounting</primary>
+    </indexterm>
+    <title>Process Accounting</title>
+
+    <para>Process accounting is a security method in which an
+      administrator may keep track of system resources used,
+      their allocation among users, provide for system monitoring,
+      and minimally track a user's commands.</para>
+
+    <para>This indeed has its own positive and negative points.  One of
+      the positives is that an intrusion may be narrowed down
+      to the point of entry.  A negative is the amount of logs
+      generated by process accounting, and the disk space they may
+      require.  This section will walk an administrator through
+      the basics of process accounting.</para>
+
+    <sect2>
+      <title>Enable and Utilizing Process Accounting</title>
+      <para>Before making use of process accounting, it
+	must be enabled.  To do this, execute the following
+	commands:</para>
+
+      <screen>&prompt.root; <userinput>touch <filename>/var/account/acct</filename></userinput>
+
+&prompt.root; <userinput>accton <filename>/var/account/acct</filename></userinput>
+
+&prompt.root; <userinput>echo 'accounting_enable="YES"' &gt;&gt; <filename>/etc/rc.conf</filename></userinput></screen>
+
+      <para>Once enabled, accounting will begin to track
+	<acronym>CPU</acronym> stats, commands, etc.  All accounting
+	logs are in a non-human readable format and may be viewed
+	using the &man.sa.8; utility.  If issued without any options,
+	<command>sa</command> will print information relating to the
+	number of per user calls, the total elapsed time in minutes,
+	total <acronym>CPU</acronym> and user time in minutes, average
+	number of I/O operations, etc.</para>
+
+      <para>To view information about commands being issued, one
+	would use the &man.lastcomm.1; utility.  The
+	<command>lastcomm</command> may be used to print out commands
+	issued by users on specific &man.ttys.5;, for example:</para>
+
+      <screen>&prompt.root; <userinput>lastcomm ls
+	<username>trhodes</username> ttyp1</userinput></screen>
+
+      <para>Would print out all known usage of the <command>ls</command>
+        by <username>trhodes</username> on the ttyp1 terminal.</para>
+
+      <para>Many other useful options exist and are explained in the
+	&man.lastcomm.1;, &man.acct.5; and &man.sa.8; manual
+	pages.</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/pl_PL.ISO8859-2/books/handbook/serialcomms/Makefile b/pl_PL.ISO8859-2/books/handbook/serialcomms/Makefile
new file mode 100644
index 0000000000..b83d9a27bb
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/serialcomms/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	serialcomms/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/serialcomms/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/serialcomms/chapter.sgml
new file mode 100644
index 0000000000..8f1821c7cd
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/serialcomms/chapter.sgml
@@ -0,0 +1,2857 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="serialcomms">
+  <title>Serial Communications</title>
+
+  <sect1 id="serial-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm><primary>serial communications</primary></indexterm>
+    <para>&unix; has always had support for serial communications.  In fact,
+      the very first &unix; machines relied on serial lines for user input
+      and output.  Things have changed a lot from the days when the average
+      <quote>terminal</quote> consisted of a 10-character-per-second serial
+      printer and a keyboard.  This chapter will cover some of the ways in
+      which FreeBSD uses serial communications.</para>
+
+    <para>After reading this chapter, you will know:</para>
+    <itemizedlist>
+      <listitem><para>How to connect terminals to your FreeBSD
+	  system.</para></listitem>
+      <listitem><para>How to use a modem to dial out to remote
+	  hosts.</para></listitem>
+      <listitem><para>How to allow remote users to login to your
+	  system with a modem.</para></listitem>
+      <listitem><para>How to boot your system from a serial
+	  console.</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>
+      <listitem><para>Understand &unix; permissions and processes (<xref linkend="basics">).</para></listitem>
+      <listitem><para>Have access to the technical manual for the
+	serial hardware (modem or multi-port card) that you would like
+	to use with FreeBSD.</para></listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="serial">
+    <title>Introduction</title>
+
+    <!-- XXX Write me! -->
+
+    <sect2 id="serial-terminology">
+      <title>Terminology</title>
+
+      <variablelist>
+	<indexterm><primary>bits-per-second</primary></indexterm>
+	<varlistentry>
+	  <term>bps</term>
+	  <listitem>
+	    <para>Bits per Second &mdash; the rate at which data is
+	      transmitted</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>DTE</term>
+	  <indexterm><primary>DTE</primary></indexterm>
+	  <listitem>
+	    <para>Data Terminal Equipment &mdash; for example, your
+	      computer</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>DCE</term>
+	  <indexterm><primary>DCE</primary></indexterm>
+	  <listitem>
+	    <para>Data Communications Equipment &mdash;  your modem</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>RS-232</term>
+	  <indexterm><primary>RS-232C cables</primary></indexterm>
+	  <listitem>
+	    <para>EIA standard for hardware serial communications</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>When talking about communications data rates, this section
+	does not use the term <quote>baud</quote>.  Baud refers to the
+	number of electrical state transitions that may be made in a
+	period of time, while <quote>bps</quote> (bits per second) is
+	the <emphasis>correct</emphasis> term to use (at least it does not
+	seem to bother the curmudgeons quite as much).</para>
+    </sect2>
+
+    <sect2 id="serial-cables-ports">
+      <title>Cables and Ports</title>
+
+      <para>To connect a modem or terminal to your FreeBSD system, you
+	will need a serial port on your computer and the proper cable to connect
+	to your serial device.  If you are already familiar with your
+	hardware and the cable it requires, you can safely skip this
+	section.</para>
+
+      <sect3 id="term-cables">
+	<title>Cables</title>
+
+	<para>There are several different kinds of serial cables.  The
+	  two most common types for our purposes are null-modem cables
+	  and standard (<quote>straight</quote>) RS-232 cables.  The documentation
+	  for your hardware should describe the type of cable
+	  required.</para>
+
+	<sect4 id="term-cables-null">
+	  <title>Null-modem Cables</title>
+
+	  <indexterm>
+	    <primary>null-modem cable</primary>
+	  </indexterm>
+	  <para>A null-modem cable passes some signals, such as <quote>Signal
+	    Ground</quote>, straight through, but switches other signals.  For
+	    example, the <quote>Transmitted Data</quote> pin on one end goes to the
+	    <quote>Received Data</quote> pin on the other end.</para>
+
+	  <para>You can also construct your own null-modem cable for use with
+	    terminals (e.g., for quality purposes).  This table shows the RS-232C
+	    <link linkend="serialcomms-signal-names">signals</link> and the pin
+	    numbers on a DB-25 connector.  Note that the standard also calls for a
+	    straight-through pin 1 to pin 1 <emphasis>Protective Ground</emphasis>
+	    line, but it is often omitted.  Some terminals work OK using only
+	    pins 2, 3 and 7, while others require different configurations than
+	    the examples shown below.</para>
+
+	  <table frame="none" pgwide="1">
+	    <title>DB-25 to DB-25 Null-Modem Cable</title>
+
+	    <tgroup cols="5">
+	      <thead>
+		<row>
+		  <entry align="left">Signal</entry>
+		  <entry align="left">Pin #</entry>
+		  <entry></entry>
+		  <entry align="left">Pin #</entry>
+		  <entry align="left">Signal</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>SG</entry>
+		  <entry>7</entry>
+		  <entry>connects to</entry>
+		  <entry>7</entry>
+		  <entry>SG</entry>
+		</row>
+
+		<row>
+		  <entry>TD</entry>
+		  <entry>2</entry>
+		  <entry>connects to</entry>
+		  <entry>3</entry>
+		  <entry>RD</entry>
+		</row>
+
+		<row>
+		  <entry>RD</entry>
+		  <entry>3</entry>
+		  <entry>connects to</entry>
+		  <entry>2</entry>
+		  <entry>TD</entry>
+		</row>
+
+		<row>
+		  <entry>RTS</entry>
+		  <entry>4</entry>
+		  <entry>connects to</entry>
+		  <entry>5</entry>
+		  <entry>CTS</entry>
+		</row>
+
+		<row>
+		  <entry>CTS</entry>
+		  <entry>5</entry>
+		  <entry>connects to</entry>
+		  <entry>4</entry>
+		  <entry>RTS</entry>
+		</row>
+
+		<row>
+		  <entry>DTR</entry>
+		  <entry>20</entry>
+		  <entry>connects to</entry>
+		  <entry>6</entry>
+		  <entry>DSR</entry>
+		</row>
+
+		<row>
+		  <entry>DTR</entry>
+		  <entry>20</entry>
+		  <entry>connects to</entry>
+		  <entry>8</entry>
+		  <entry>DCD</entry>
+		</row>
+
+		<row>
+		  <entry>DSR</entry>
+		  <entry>6</entry>
+		  <entry>connects to</entry>
+		  <entry>20</entry>
+		  <entry>DTR</entry>
+		</row>
+
+		<row>
+		  <entry>DCD</entry>
+		  <entry>8</entry>
+		  <entry>connects to</entry>
+		  <entry>20</entry>
+		  <entry>DTR</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </table>
+
+	  <para>Here are two other schemes more common nowadays.</para>
+
+	  <table frame="none" pgwide="1">
+	    <title>DB-9 to DB-9 Null-Modem Cable</title>
+
+	    <tgroup cols="5">
+	      <thead>
+		<row>
+		  <entry align="left">Signal</entry>
+		  <entry align="left">Pin #</entry>
+		  <entry></entry>
+		  <entry align="left">Pin #</entry>
+		  <entry align="left">Signal</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>RD</entry>
+		  <entry>2</entry>
+		  <entry>connects to</entry>
+		  <entry>3</entry>
+		  <entry>TD</entry>
+		</row>
+
+		<row>
+		  <entry>TD</entry>
+		  <entry>3</entry>
+		  <entry>connects to</entry>
+		  <entry>2</entry>
+		  <entry>RD</entry>
+		</row>
+
+		<row>
+		  <entry>DTR</entry>
+		  <entry>4</entry>
+		  <entry>connects to</entry>
+		  <entry>6</entry>
+		  <entry>DSR</entry>
+		</row>
+
+		<row>
+		  <entry>DTR</entry>
+		  <entry>4</entry>
+		  <entry>connects to</entry>
+		  <entry>1</entry>
+		  <entry>DCD</entry>
+		</row>
+
+		<row>
+		  <entry>SG</entry>
+		  <entry>5</entry>
+		  <entry>connects to</entry>
+		  <entry>5</entry>
+		  <entry>SG</entry>
+		</row>
+
+		<row>
+		  <entry>DSR</entry>
+		  <entry>6</entry>
+		  <entry>connects to</entry>
+		  <entry>4</entry>
+		  <entry>DTR</entry>
+		</row>
+
+		<row>
+		  <entry>DCD</entry>
+		  <entry>1</entry>
+		  <entry>connects to</entry>
+		  <entry>4</entry>
+		  <entry>DTR</entry>
+		</row>
+
+		<row>
+		  <entry>RTS</entry>
+		  <entry>7</entry>
+		  <entry>connects to</entry>
+		  <entry>8</entry>
+		  <entry>CTS</entry>
+		</row>
+
+		<row>
+		  <entry>CTS</entry>
+		  <entry>8</entry>
+		  <entry>connects to</entry>
+		  <entry>7</entry>
+		  <entry>RTS</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </table>
+
+	  <table frame="none" pgwide="1">
+	    <title>DB-9 to DB-25 Null-Modem Cable</title>
+
+	    <tgroup cols="5">
+	      <thead>
+		<row>
+		  <entry align="left">Signal</entry>
+		  <entry align="left">Pin #</entry>
+		  <entry></entry>
+		  <entry align="left">Pin #</entry>
+		  <entry align="left">Signal</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>RD</entry>
+		  <entry>2</entry>
+		  <entry>connects to</entry>
+		  <entry>2</entry>
+		  <entry>TD</entry>
+		</row>
+
+		<row>
+		  <entry>TD</entry>
+		  <entry>3</entry>
+		  <entry>connects to</entry>
+		  <entry>3</entry>
+		  <entry>RD</entry>
+		</row>
+
+		<row>
+		  <entry>DTR</entry>
+		  <entry>4</entry>
+		  <entry>connects to</entry>
+		  <entry>6</entry>
+		  <entry>DSR</entry>
+		</row>
+
+		<row>
+		  <entry>DTR</entry>
+		  <entry>4</entry>
+		  <entry>connects to</entry>
+		  <entry>8</entry>
+		  <entry>DCD</entry>
+		</row>
+
+		<row>
+		  <entry>SG</entry>
+		  <entry>5</entry>
+		  <entry>connects to</entry>
+		  <entry>7</entry>
+		  <entry>SG</entry>
+		</row>
+
+		<row>
+		  <entry>DSR</entry>
+		  <entry>6</entry>
+		  <entry>connects to</entry>
+		  <entry>20</entry>
+		  <entry>DTR</entry>
+		</row>
+
+		<row>
+		  <entry>DCD</entry>
+		  <entry>1</entry>
+		  <entry>connects to</entry>
+		  <entry>20</entry>
+		  <entry>DTR</entry>
+		</row>
+
+		<row>
+		  <entry>RTS</entry>
+		  <entry>7</entry>
+		  <entry>connects to</entry>
+		  <entry>5</entry>
+		  <entry>CTS</entry>
+		</row>
+
+		<row>
+		  <entry>CTS</entry>
+		  <entry>8</entry>
+		  <entry>connects to</entry>
+		  <entry>4</entry>
+		  <entry>RTS</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </table>
+
+	  <note>
+	    <para>When one pin at one end connects to a pair of pins
+	      at the other end, it is usually implemented with one short
+	      wire between the pair of pins in their connector and a
+	      long wire to the other single pin.</para>
+	  </note>
+
+	  <para>The above designs seems to be the most popular.  In another
+	    variation (explained in the book <emphasis>RS-232 Made
+	      Easy</emphasis>) SG connects to SG, TD connects to RD, RTS and
+	    CTS connect to DCD, DTR connects to DSR, and vice-versa.</para>
+	</sect4>
+
+	<sect4 id="term-cables-std">
+	  <title>Standard RS-232C Cables</title>
+	  <indexterm><primary>RS-232C cables</primary></indexterm>
+
+	  <para>A standard serial cable passes all of the RS-232C signals
+	    straight through.  That is, the <quote>Transmitted Data</quote> pin on one
+	    end of the cable goes to the <quote>Transmitted Data</quote> pin on the
+	    other end. This is the type of cable to use to connect a modem to your
+	    FreeBSD system, and is also appropriate for some
+	    terminals.</para>
+	</sect4>
+      </sect3>
+
+      <sect3 id="term-ports">
+	<title>Ports</title>
+
+	<para>Serial ports are the devices through which data is transferred
+	  between the FreeBSD host computer and the terminal. This section
+	  describes the kinds of ports that exist and how they are addressed
+	  in FreeBSD.</para>
+
+	<sect4 id="term-portkinds">
+	  <title>Kinds of Ports</title>
+
+	  <para>Several kinds of serial ports exist.  Before you purchase or
+	    construct a cable, you need to make sure it will fit the ports on
+	    your terminal and on the FreeBSD system.</para>
+
+	  <para>Most terminals will have DB-25 ports.  Personal computers,
+	    including PCs running FreeBSD, will have DB-25 or DB-9 ports. If you
+	    have a multiport serial card for your PC, you may have RJ-12 or
+	    RJ-45 ports.</para>
+
+	  <para>See the documentation that accompanied the hardware for
+	    specifications on the kind of port in use.  A visual inspection of
+	    the port often works too.</para>
+	</sect4>
+
+	<sect4 id="term-portnames">
+	  <title>Port Names</title>
+
+	  <para>In FreeBSD, you access each serial port through an entry in
+	    the <filename>/dev</filename> directory.  There are two different
+	    kinds of entries:</para>
+
+	  <itemizedlist>
+	    <listitem>
+	      <para>Call-in ports are named
+		<filename>/dev/ttyd<replaceable>N</replaceable></filename>
+		where <replaceable>N</replaceable> is the port number,
+		starting from zero.  Generally, you use the call-in port for
+		terminals.  Call-in ports require that the serial line assert
+		the data carrier detect (DCD) signal to work correctly.</para>
+	    </listitem>
+
+	    <listitem>
+	      <para>Call-out ports are named
+		<filename>/dev/cuad<replaceable>N</replaceable></filename>.
+		You usually do not use the call-out port for terminals, just
+		for modems.  You may use the call-out port if the serial cable
+		or the terminal does not support the carrier detect
+		signal.</para>
+
+	      <note><para>Call-out ports are named
+		<filename>/dev/cuaa<replaceable>N</replaceable></filename> in
+		&os;&nbsp;5.X and older.</para></note>
+	    </listitem>
+	  </itemizedlist>
+
+	  <para>If you have connected a terminal to the first serial port
+	    (<devicename>COM1</devicename> in &ms-dos;), then you will
+	    use <filename>/dev/ttyd0</filename> to refer to the terminal.  If
+	    the terminal is on the second serial port (also known as
+	    <devicename>COM2</devicename>), use
+	    <filename>/dev/ttyd1</filename>, and so forth.</para>
+
+	</sect4>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Kernel Configuration</title>
+
+      <para>FreeBSD supports four serial ports by default.  In the
+	&ms-dos; world, these are known as
+	<devicename>COM1</devicename>,
+	<devicename>COM2</devicename>,
+	<devicename>COM3</devicename>, and
+	<devicename>COM4</devicename>.  FreeBSD currently supports
+	<quote>dumb</quote> multiport serial interface cards, such as
+	the BocaBoard 1008 and 2016, as well as more
+	intelligent multi-port cards such as those made by Digiboard
+	and Stallion Technologies.  However, the default kernel only looks
+	for the standard COM ports.</para>
+
+      <para>To see if your kernel recognizes any of your serial ports, watch
+	for messages while the kernel is booting, or use the
+	<command>/sbin/dmesg</command> command to replay the kernel's boot
+	messages.  In particular, look for messages that start with the
+	characters <literal>sio</literal>.</para>
+
+      <tip><para>To view just the messages that have the word
+	<literal>sio</literal>, use the command:</para>
+
+      <screen>&prompt.root; <userinput>/sbin/dmesg | grep 'sio'</userinput></screen>
+      </tip>
+
+      <para>For example, on a system with four serial ports, these are the
+	serial-port specific kernel boot messages:</para>
+
+      <screen>sio0 at 0x3f8-0x3ff irq 4 on isa
+sio0: type 16550A
+sio1 at 0x2f8-0x2ff irq 3 on isa
+sio1: type 16550A
+sio2 at 0x3e8-0x3ef irq 5 on isa
+sio2: type 16550A
+sio3 at 0x2e8-0x2ef irq 9 on isa
+sio3: type 16550A</screen>
+
+      <para>If your kernel does not recognize all of your serial
+	ports, you will probably need to configure your kernel
+	in the <filename>/boot/device.hints</filename> file.  You can
+	also comment-out or completely remove lines for devices you do not
+	have.</para>
+
+      <para>Please refer to the &man.sio.4; manual page for
+	more information on serial ports and multiport boards configuration.
+	Be careful if you are using a configuration
+	file that was previously used for a different version of
+	FreeBSD because the device flags and the syntax have changed between
+	versions.</para>
+
+      <note>
+	<para><literal>port IO_COM1</literal> is a substitution for
+	  <literal>port 0x3f8</literal>, <literal>IO_COM2</literal> is
+	  <literal>0x2f8</literal>, <literal>IO_COM3</literal> is
+	  <literal>0x3e8</literal>, and <literal>IO_COM4</literal> is
+	  <literal>0x2e8</literal>, which are fairly common port addresses for
+	  their respective serial ports; interrupts 4, 3, 5, and 9 are fairly
+	  common interrupt request lines.  Also note that regular serial ports
+	  <emphasis>cannot</emphasis> share interrupts on ISA-bus PCs
+	  (multiport boards have on-board electronics that allow all the
+	  16550A's on the board to share one or two interrupt request
+	  lines).</para>
+      </note>
+
+    </sect2>
+
+    <sect2>
+      <title>Device Special Files</title>
+
+      <para>Most devices in the kernel are accessed through <quote>device
+	special files</quote>, which are located in the
+	<filename>/dev</filename> directory.  The <devicename>sio</devicename>
+	devices are accessed through the
+	<filename>/dev/ttyd<replaceable>N</replaceable></filename> (dial-in)
+	and <filename>/dev/cuad<replaceable>N</replaceable></filename>
+	(call-out) devices.  FreeBSD also provides initialization devices
+	(<filename>/dev/ttyd<replaceable>N</replaceable>.init</filename> and
+	<filename>/dev/cuad<replaceable>N</replaceable>.init</filename> on
+	&os;&nbsp;6.X,
+	<filename>/dev/ttyid<replaceable>N</replaceable></filename> and
+	<filename>/dev/cuaia<replaceable>N</replaceable></filename> on
+	&os;&nbsp;5.X) and
+	locking devices
+	(<filename>/dev/ttyd<replaceable>N</replaceable>.lock</filename> and
+	<filename>/dev/cuad<replaceable>N</replaceable>.lock</filename> on
+	&os;&nbsp;6.X,
+	<filename>/dev/ttyld<replaceable>N</replaceable></filename> and
+	<filename>/dev/cuala<replaceable>N</replaceable></filename> on
+	&os;&nbsp;5.X).  The
+	initialization devices are used to initialize communications port
+	parameters each time a port is opened, such as
+	<literal>crtscts</literal> for modems which use
+	<literal>RTS/CTS</literal> signaling for flow control.  The locking
+	devices are used to lock flags on ports to prevent users or programs
+	changing certain parameters; see the manual pages &man.termios.4;,
+	  &man.sio.4;, and &man.stty.1; for
+	information on the terminal settings, locking and initializing
+	devices, and setting terminal options, respectively.</para>
+    </sect2>
+
+
+    <sect2 id="serial-hw-config">
+      <title>Serial Port Configuration</title>
+
+    <indexterm><primary><devicename>ttyd</devicename></primary></indexterm>
+    <indexterm><primary><devicename>cuad</devicename></primary></indexterm>
+
+    <para>The <devicename>ttyd<replaceable>N</replaceable></devicename> (or
+      <devicename>cuad<replaceable>N</replaceable></devicename>) device is the
+      regular device you will want to open for your applications.  When a
+      process opens the device, it will have a default set of terminal I/O
+      settings.  You can see these settings with the command</para>
+
+    <screen>&prompt.root; <userinput>stty -a -f /dev/ttyd1</userinput></screen>
+
+    <para>When you change the settings to this device, the settings are in
+      effect until the device is closed.  When it is reopened, it goes back to
+      the default set.  To make changes to the default set, you can open and
+      adjust the settings of the <quote>initial state</quote> device. For
+      example, to turn on <option>CLOCAL</option> mode, 8 bit communication,
+      and <option>XON/XOFF</option> flow control by default for
+      <devicename>ttyd5</devicename>, type:</para>
+
+    <screen>&prompt.root; <userinput>stty -f /dev/ttyd5.init clocal cs8 ixon ixoff</userinput></screen>
+
+    <indexterm>
+      <primary>rc files</primary>
+      <secondary><filename>rc.serial</filename></secondary>
+    </indexterm>
+
+    <para>System-wide initialization of the serial devices is
+      controlled in <filename>/etc/rc.d/serial</filename>.  This file
+      affects the default settings of serial devices.</para>
+
+    <para>To prevent certain settings from being changed by an
+      application, make adjustments to the <quote>lock state</quote>
+      device.  For example, to lock the speed of
+      <devicename>ttyd5</devicename> to 57600&nbsp;bps, type:</para>
+
+    <screen>&prompt.root; <userinput>stty -f /dev/ttyd5.lock 57600</userinput></screen>
+
+    <para>Now, an application that opens
+      <devicename>ttyd5</devicename> and tries to change the speed of
+      the port will be stuck with 57600&nbsp;bps.</para>
+
+    <para>Naturally, you should make the initial state and lock state devices
+      writable only by the <username>root</username> account.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="term">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Sean</firstname>
+	  <surname>Kelly</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+	<!-- 28 July 1996 -->
+      </authorgroup>
+    </sect1info>
+    <title>Terminals</title>
+
+    <indexterm><primary>terminals</primary></indexterm>
+
+    <para>Terminals provide a convenient and low-cost way to access
+      your FreeBSD system when you are not at the computer's console or on
+      a connected network.  This section describes how to use terminals with
+      FreeBSD.</para>
+
+    <sect2 id="term-uses">
+      <title>Uses and Types of Terminals</title>
+
+      <para>The original &unix; systems did not have consoles.  Instead, people
+	logged in and ran programs through terminals that were connected to
+	the computer's serial ports.  It is quite similar to using a modem and
+	terminal software to dial into a remote system to do text-only
+	work.</para>
+
+      <para>Today's PCs have consoles capable of high quality graphics, but
+	the ability to establish a login session on a serial port still exists
+	in nearly every &unix; style operating system today; FreeBSD is no
+	exception.  By using a terminal attached to an unused serial port, you
+	can log in and run any text program that you would normally run on the
+	console or in an <command>xterm</command> window in the X Window
+	System.</para>
+
+      <para>For the business user, you can attach many terminals to a FreeBSD
+	system and place them on your employees' desktops.  For a home user, a
+	spare computer such as an older IBM PC or a &macintosh; can be a
+	terminal wired into a more powerful computer running FreeBSD.  You can
+	turn what might otherwise be a single-user computer into a powerful
+	multiple user system.</para>
+
+      <para>For FreeBSD, there are three kinds of terminals:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><link linkend="term-dumb">Dumb terminals</link></para>
+	</listitem>
+
+	<listitem>
+	  <para><link linkend="term-pcs">PCs acting as terminals</link></para>
+	</listitem>
+
+	<listitem>
+	  <para><link linkend="term-x">X terminals</link></para>
+	</listitem>
+      </itemizedlist>
+
+      <para>The remaining subsections describe each kind.</para>
+
+      <sect3 id="term-dumb">
+	<title>Dumb Terminals</title>
+
+	<para>Dumb terminals are specialized pieces of hardware that let you
+	  connect to computers over serial lines.  They are called
+	  <quote>dumb</quote> because they have only enough computational power
+	  to display, send, and receive text.  You cannot run any programs on
+	  them.  It is the computer to which you connect them that has all the
+	  power to run text editors, compilers, email, games, and so
+	  forth.</para>
+
+	<para>There are hundreds of kinds of dumb terminals made by many
+	  manufacturers, including Digital Equipment Corporation's VT-100 and
+	  Wyse's WY-75.  Just about any kind will work with FreeBSD. Some
+	  high-end terminals can even display graphics, but only certain
+	  software packages can take advantage of these advanced
+	  features.</para>
+
+	<para>Dumb terminals are popular in work environments where workers do
+	  not need access to graphical applications such as those provided by
+	  the X Window System.</para>
+      </sect3>
+
+      <sect3 id="term-pcs">
+	<title>PCs Acting as Terminals</title>
+
+	<para>If a <link linkend="term-dumb">dumb terminal</link> has just
+	  enough ability to display, send, and receive text, then certainly
+	  any spare personal computer can be a dumb terminal. All you need is
+	  the proper cable and some <emphasis>terminal emulation</emphasis>
+	  software to run on the computer.</para>
+
+	<para>Such a configuration is popular in homes.  For example, if your
+	  spouse is busy working on your FreeBSD system's console, you can do
+	  some text-only work at the same time from a less powerful personal
+	  computer hooked up as a terminal to the FreeBSD system.</para>
+
+	<para>There are at least two utilities in the base-system of
+	  &os; that can be used to work through a serial connection:
+	  &man.cu.1; and &man.tip.1;.</para>
+
+	<para>To connect from a client system that runs &os; to the
+	  serial connection of another system, you can use:</para>
+
+	<screen>&prompt.root; <userinput>cu -l <replaceable>serial-port-device</replaceable></userinput></screen>
+
+	<para>Where <quote>serial-port-device</quote> is the name of a
+	  special device file denoting a serial port of your system.
+	  These device files are called
+	  <devicename>/dev/cuaa<replaceable>N</replaceable></devicename>
+	  for &os; versions older than 6.0, and
+	  <devicename>/dev/cuad<replaceable>N</replaceable></devicename>
+	  for 6.0 and later versions.</para>
+
+	<para>The <quote>N</quote>-part of a device name is the serial
+	  port number.</para>
+
+	<note>
+	  <para>Note that device numbers in &os; start from zero and not
+	    one (like they do, for instance in &ms-dos;-derived systems).
+	    This means that what &ms-dos;-based systems
+	    call <quote>COM1</quote> is
+	    usually <filename>/dev/cuad0</filename> in &os;.</para>
+	</note>
+
+	<note>
+	  <para>Some people prefer to use other programs, available
+	    through the Ports Collection.  The Ports include quite a few
+	    utilities which can work in ways similar to &man.cu.1; and
+	    &man.tip.1;,
+	    i.e. <filename role="package">comms/minicom</filename>.</para>
+	</note>
+      </sect3>
+
+      <sect3 id="term-x">
+	<title>X Terminals</title>
+
+	<para>X terminals are the most sophisticated kind of terminal
+	  available.  Instead of connecting to a serial port, they usually
+	  connect to a network like Ethernet.  Instead of being relegated to
+	  text-only applications, they can display any X application.</para>
+
+	<para>We introduce X terminals just for the sake of completeness.
+	  However, this chapter does <emphasis>not</emphasis> cover setup,
+	  configuration, or use of X terminals.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="term-config">
+      <title>Configuration</title>
+
+      <para>This section describes what you need to configure on your FreeBSD
+	system to enable a login session on a terminal.  It assumes you have
+	already configured your kernel to support the serial port to which the
+	terminal is connected&mdash;and that you have connected it.</para>
+
+      <para>Recall from <xref linkend="boot"> that the
+	<command>init</command> process is responsible for all process
+	control and initialization at system startup.  One of the
+	tasks performed by <command>init</command> is to read the
+	<filename>/etc/ttys</filename> file and start a
+	<command>getty</command> process on the available terminals.
+	The <command>getty</command> process is responsible for
+	reading a login name and starting the <command>login</command>
+	program.</para>
+
+      <para>Thus, to configure terminals for your FreeBSD system the
+	following steps should be taken as <username>root</username>:</para>
+
+      <procedure>
+	<step>
+	  <para>Add a line to <filename>/etc/ttys</filename> for the entry in
+	    the <filename>/dev</filename> directory for the serial port if it
+	    is not already there.</para>
+	</step>
+
+	<step>
+	  <para>Specify that <command>/usr/libexec/getty</command> be run on
+	    the port, and specify the appropriate
+	    <replaceable>getty</replaceable> type from the
+	    <filename>/etc/gettytab</filename> file.</para>
+	</step>
+
+	<step>
+	  <para>Specify the default terminal type.</para>
+	</step>
+
+	<step>
+	  <para>Set the port to <quote>on.</quote></para>
+	</step>
+
+	<step>
+	  <para>Specify whether the port should be
+	    <quote>secure.</quote></para>
+	</step>
+
+	<step>
+	  <para>Force <command>init</command> to reread the
+	    <filename>/etc/ttys</filename> file.</para>
+	</step>
+      </procedure>
+
+      <para>As an optional step, you may wish to create a custom
+	<replaceable>getty</replaceable> type for use in step 2 by making an
+	entry in <filename>/etc/gettytab</filename>.  This chapter does
+	not explain how to do so; you are encouraged to see the
+	  &man.gettytab.5; and the &man.getty.8; manual pages for more
+	information.</para>
+
+      <sect3 id="term-etcttys">
+	<title>Adding an Entry to <filename>/etc/ttys</filename></title>
+
+	<para>The <filename>/etc/ttys</filename> file lists all of the ports
+	  on your FreeBSD system where you want to allow logins.  For example,
+	  the first virtual console <filename>ttyv0</filename> has an entry in
+	  this file.  You can log in on the console using this entry.  This
+	  file also contains entries for the other virtual consoles, serial ports,
+	  and pseudo-ttys.  For a hardwired terminal, just list the serial
+	  port's <filename>/dev</filename> entry without the
+	  <filename>/dev</filename> part (for example,
+	  <filename>/dev/ttyv0</filename> would be listed as
+	  <devicename>ttyv0</devicename>).</para>
+
+	<para>A default FreeBSD install includes an
+	  <filename>/etc/ttys</filename> file with support for the first
+	  four serial ports: <filename>ttyd0</filename> through
+	  <filename>ttyd3</filename>.  If you are attaching a terminal
+	  to one of those ports, you do not need to add another entry.</para>
+
+	<example id="ex-etc-ttys">
+	  <title>Adding Terminal Entries to
+	    <filename>/etc/ttys</filename></title>
+
+	  <para>Suppose we would like to connect two terminals to the
+	    system: a Wyse-50 and an old 286 IBM PC running
+	    <application>Procomm</application> terminal software
+	    emulating a VT-100 terminal.  We connect the Wyse to the
+	    second serial port and the 286 to the sixth serial port (a
+	    port on a multiport serial card).  The corresponding
+	    entries in the <filename>/etc/ttys</filename> file would
+	    look like this:</para>
+
+	  <programlisting>ttyd1<co
+	      id="co-ttys-line1col1">  "/usr/libexec/getty std.38400"<co
+	      id="co-ttys-line1col2">  wy50<co
+	      id="co-ttys-line1col3">  on<co
+	      id="co-ttys-line1col4">  insecure<co
+	      id="co-ttys-line1col5">
+ttyd5   "/usr/libexec/getty std.19200"  vt100  on  insecure
+	  </programlisting>
+
+	  <calloutlist>
+	    <callout arearefs="co-ttys-line1col1">
+	      <para>The first field normally specifies the name of
+	      the terminal special file as it is found in
+	      <filename>/dev</filename>.</para>
+	    </callout>
+	    <callout arearefs="co-ttys-line1col2">
+
+	      <para>The second field is the command to execute for
+		this line, which is usually &man.getty.8;.
+		<command>getty</command> initializes and opens the
+		line, sets the speed, prompts for a user name and then
+		executes the &man.login.1; program.</para>
+
+	      <para>The <command>getty</command> program accepts one
+		(optional) parameter on its command line, the
+		<replaceable>getty</replaceable> type.  A
+		<replaceable>getty</replaceable> type configures
+		characteristics on the terminal line, like bps rate
+		and parity. The <command>getty</command> program reads
+		these characteristics from the file
+		<filename>/etc/gettytab</filename>.</para>
+
+	      <para>The file <filename>/etc/gettytab</filename>
+		contains lots of entries for terminal lines both old
+		and new.  In almost all cases, the entries that start
+		with the text <literal>std</literal> will work for
+		hardwired terminals. These entries ignore parity.
+		There is a <literal>std</literal> entry for each bps
+		rate from 110 to 115200.  Of course, you can add your
+		own entries to this file. The &man.gettytab.5; manual
+		page provides more information.</para>
+
+	      <para>When setting the <replaceable>getty</replaceable>
+		type in the <filename>/etc/ttys</filename> file, make
+		sure that the communications settings on the terminal
+		match.</para>
+
+	      <para>For our example, the Wyse-50 uses no parity and
+		connects at 38400&nbsp;bps.  The 286&nbsp;PC uses no parity and
+		connects at 19200&nbsp;bps.</para>
+
+	    </callout>
+
+	    <callout arearefs="co-ttys-line1col3">
+
+	      <para>The third field is the type of terminal usually
+		connected to that tty line.  For dial-up ports,
+		<literal>unknown</literal> or
+		<literal>dialup</literal> is typically used in this
+		field since users may dial up with practically any
+		type of terminal or software.  For hardwired
+		terminals, the terminal type does not change, so you
+		can put a real terminal type from the &man.termcap.5;
+		database file in this field.</para>
+
+	      <para>For our example, the Wyse-50 uses the real
+		terminal type while the 286 PC running
+		<application>Procomm</application> will be set to
+		emulate at VT-100. </para>
+
+	    </callout>
+
+	    <callout arearefs="co-ttys-line1col4">
+	      <para>The fourth field specifies if the port should be
+		enabled.  Putting <literal>on</literal> here will have
+		the <command>init</command> process start the program
+		in the second field, <command>getty</command>.  If you
+		put <literal>off</literal> in this field, there will
+		be no <command>getty</command>, and hence no logins on
+		the port.</para>
+	    </callout>
+
+	    <callout arearefs="co-ttys-line1col5">
+	      <para>The final field is used to specify whether the
+		port is secure.  Marking a port as secure means that
+		you trust it enough to allow the
+		<username>root</username> account (or any account with
+		a user ID of 0) to login from that port.  Insecure
+		ports do not allow <username>root</username> logins.
+		On an insecure port, users must login from
+		unprivileged accounts and then use &man.su.1; or a
+		similar mechanism to gain superuser privileges.</para>
+
+	      <para>It is highly recommended that you use
+		<quote>insecure</quote>
+		even for terminals that are behind locked doors.  It
+		is quite easy to login and use <command>su</command>
+		if you need superuser privileges.</para>
+	    </callout>
+	  </calloutlist>
+	</example>
+      </sect3>
+
+      <sect3 id="term-hup">
+	<title>Force <command>init</command> to Reread
+	  <filename>/etc/ttys</filename></title>
+
+	<para>After making the necessary changes to the
+	  <filename>/etc/ttys</filename> file you should send a SIGHUP
+	  (hangup) signal to the <command>init</command> process to
+	  force it to re-read its configuration file.  For example:</para>
+
+	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
+
+	<note>
+	  <para><command>init</command> is always the first process run
+	    on a system, therefore it will always have PID 1.</para>
+	</note>
+
+	<para>If everything is set up correctly, all cables are in
+	  place, and the terminals are powered up, then a
+	  <command>getty</command> process should be running on each
+	  terminal and you should see login prompts on your terminals
+	  at this point.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="term-debug">
+      <title>Troubleshooting Your Connection</title>
+
+      <para>Even with the most meticulous attention to detail, something could
+	still go wrong while setting up a terminal.  Here is a list of
+	symptoms and some suggested fixes.</para>
+
+      <sect3>
+	<title>No Login Prompt Appears</title>
+
+	<para>Make sure the terminal is plugged in and powered up. If it
+	  is a personal computer acting as a terminal, make sure it is
+	  running terminal emulation software on the correct serial
+	  port.</para>
+
+	<para>Make sure the cable is connected firmly to both the terminal
+	  and the FreeBSD computer.  Make sure it is the right kind of
+	  cable.</para>
+
+	<para>Make sure the terminal and FreeBSD agree on the bps rate and
+	  parity settings.  If you have a video display terminal, make
+	  sure the contrast and brightness controls are turned up.  If it
+	  is a printing terminal, make sure paper and ink are in good
+	  supply.</para>
+
+	<para>Make sure that a <command>getty</command> process is running
+	  and serving the terminal.  For example, to get a list of
+	  running <command>getty</command> processes with
+	  <command>ps</command>, type:</para>
+
+	<screen>&prompt.root; <userinput>ps -axww|grep getty</userinput></screen>
+
+	<para>You should see an entry for the terminal.  For
+	  example, the following display shows that a
+	  <command>getty</command> is running on the second serial
+	  port <literal>ttyd1</literal> and is using the
+	  <literal>std.38400</literal> entry in
+	  <filename>/etc/gettytab</filename>:</para>
+
+	<screen>22189  d1  Is+    0:00.03 /usr/libexec/getty std.38400 ttyd1</screen>
+
+	<para>If no <command>getty</command> process is running, make sure
+	  you have enabled the port in <filename>/etc/ttys</filename>.
+	  Also remember to run <command>kill -HUP 1</command>
+	  after modifying the <filename>ttys</filename> file.</para>
+
+	<para>If the <command>getty</command> process is running
+	  but the terminal still does not display a login prompt,
+	  or if it displays a prompt but will not allow you to
+	  type, your terminal or cable may not support hardware
+	  handshaking. Try changing the entry in
+	  <filename>/etc/ttys</filename> from
+	  <literal>std.38400</literal> to
+	  <literal>3wire.38400</literal> remember to run
+	  <command>kill -HUP 1</command> after modifying
+	  <filename>/etc/ttys</filename>). The
+	  <literal>3wire</literal> entry is similar to
+	  <literal>std</literal>, but ignores hardware
+	  handshaking. You may need to reduce the baud rate or
+	  enable software flow control when using
+	  <literal>3wire</literal> to prevent buffer
+	  overflows.</para>
+
+      </sect3>
+
+      <sect3>
+	<title>If Garbage Appears Instead of a Login Prompt</title>
+
+	<para>Make sure the terminal and FreeBSD agree on the bps rate and
+	  parity settings.  Check the <command>getty</command> processes
+	  to make sure the
+	  correct <replaceable>getty</replaceable> type is in use.  If
+	  not, edit <filename>/etc/ttys</filename> and run <command>kill
+	  -HUP 1</command>.</para>
+
+      </sect3>
+
+      <sect3>
+	<title>Characters Appear Doubled; the Password Appears When Typed</title>
+
+	<para>Switch the terminal (or the terminal emulation software)
+	  from <quote>half duplex</quote> or <quote>local echo</quote> to
+	  <quote>full duplex.</quote></para>
+
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="dialup">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Guy</firstname>
+	  <surname>Helmer</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Sean</firstname>
+	  <surname>Kelly</surname>
+	  <contrib>Additions by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Dial-in Service</title>
+    <indexterm><primary>dial-in service</primary></indexterm>
+
+    <para>Configuring your FreeBSD system for dial-in service is very
+      similar to connecting terminals except that you are dealing with
+      modems instead of terminals.</para>
+
+      <sect2>
+	<title>External vs. Internal Modems</title>
+
+	<para>External modems seem to be more convenient for dial-up, because
+	  external modems often can be semi-permanently configured via
+	  parameters stored in non-volatile RAM and they usually provide
+	  lighted indicators that display the state of important RS-232
+	  signals.  Blinking lights impress visitors, but lights are also very
+	  useful to see whether a modem is operating properly.</para>
+
+	<para>Internal modems usually lack non-volatile RAM, so their
+	  configuration may be limited only to setting DIP switches.  If your
+	  internal modem has any signal indicator lights, it is probably
+	  difficult to view the lights when the system's cover is in
+	  place.</para>
+
+      <sect3>
+	<title>Modems and Cables</title>
+	<indexterm><primary>modem</primary></indexterm>
+
+	<para>If you are using an external modem, then you will of
+	  course need the proper cable.  A standard RS-232C serial
+	  cable should suffice as long as all of the normal signals
+	  are wired:</para>
+
+	  <table frame="none" pgwide="1" id="serialcomms-signal-names">
+	    <title>Signal Names</title>
+
+	    <tgroup cols="2">
+	      <thead>
+		<row>
+		  <entry align="left">Acronyms</entry>
+		  <entry align="left">Names</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry><acronym>RD</acronym></entry>
+		  <entry>Received Data</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>TD</acronym></entry>
+		  <entry>Transmitted Data</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>DTR</acronym></entry>
+		  <entry>Data Terminal Ready</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>DSR</acronym></entry>
+		  <entry>Data Set Ready</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>DCD</acronym></entry>
+		  <entry>Data Carrier Detect (RS-232's Received Line
+		    Signal Detector)</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>SG</acronym></entry>
+		  <entry>Signal Ground</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>RTS</acronym></entry>
+		  <entry>Request to Send</entry>
+		</row>
+
+		<row>
+		  <entry><acronym>CTS</acronym></entry>
+		  <entry>Clear to Send</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </table>
+
+	<para>FreeBSD needs the <acronym>RTS</acronym> and
+	  <acronym>CTS</acronym> signals for flow control at speeds above
+	  2400&nbsp;bps, the <acronym>CD</acronym> signal to detect when a call has
+	  been answered or the line has been hung up, and the
+	  <acronym>DTR</acronym> signal to reset the modem after a session is
+	  complete.  Some cables are wired without all of the needed signals,
+	  so if you have problems, such as a login session not going away when
+	  the line hangs up, you may have a problem with your cable.</para>
+
+	<para>Like other &unix; like operating systems, FreeBSD uses the
+	  hardware signals to find out when a call has been answered
+	  or a line has been hung up and to hangup and reset the modem
+	  after a call.  FreeBSD avoids sending commands to the modem
+	  or watching for status reports from the modem.  If you are
+	  familiar with connecting modems to PC-based bulletin board
+	  systems, this may seem awkward.</para>
+      </sect3>
+      </sect2>
+
+      <sect2>
+	<title>Serial Interface Considerations</title>
+
+	<para>FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based
+	  EIA RS-232C (CCITT V.24) communications interfaces.  The 8250 and
+	  16450 devices have single-character buffers.  The 16550 device
+	  provides a 16-character buffer, which allows for better system
+	  performance.  (Bugs in plain 16550's prevent the use of the
+	  16-character buffer, so use 16550A's if possible).  Because
+	  single-character-buffer devices require more work by the operating
+	  system than the 16-character-buffer devices, 16550A-based serial
+	  interface cards are much preferred. If the system has many active
+	  serial ports or will have a heavy load, 16550A-based cards are
+	  better for low-error-rate communications.</para>
+      </sect2>
+
+    <sect2>
+      <title>Quick Overview</title>
+
+      <indexterm><primary>getty</primary></indexterm>
+      <para>As with terminals, <command>init</command> spawns a
+	<command>getty</command> process for each configured serial
+	port for dial-in connections.  For example, if a modem is
+	attached to <filename>/dev/ttyd0</filename>, the command
+	<command>ps ax</command> might show this:</para>
+
+      <screen> 4850 ??  I      0:00.09 /usr/libexec/getty V19200 ttyd0</screen>
+
+      <para>When a user dials the modem's line and the modems connect, the
+	<acronym>CD</acronym> (Carrier Detect) line is reported by the modem.
+	The kernel
+	notices that carrier has been detected and completes
+	<command>getty</command>'s open of the port.  <command>getty</command>
+	sends a <prompt>login:</prompt> prompt at the specified initial line
+	speed.  <command>getty</command> watches to see if legitimate
+	characters are received, and, in a typical configuration, if it finds
+	junk (probably due to the modem's connection speed being different
+	than <command>getty</command>'s speed), <command>getty</command> tries
+	adjusting the line speeds until it receives reasonable
+	characters.</para>
+
+      <indexterm>
+	<primary><command>/usr/bin/login</command></primary>
+      </indexterm>
+      <para>After the user enters his/her login name,
+	<command>getty</command> executes
+	<filename>/usr/bin/login</filename>, which completes the login
+	by asking for the user's password and then starting the user's
+	shell.</para>
+    </sect2>
+
+
+    <sect2>
+      <title>Configuration Files</title>
+
+      <para>There are three system configuration files in the
+	<filename>/etc</filename> directory that you will probably need to
+	edit to allow dial-up access to your FreeBSD system.  The first,
+	<filename>/etc/gettytab</filename>, contains configuration information
+	for the <filename>/usr/libexec/getty</filename> daemon.  Second,
+	<filename>/etc/ttys</filename> holds information that tells
+	<filename>/sbin/init</filename> what <filename>tty</filename> devices
+	should have <command>getty</command> processes running on them.
+	Lastly, you can place port initialization commands in the
+	<filename>/etc/rc.d/serial</filename> script.</para>
+
+      <para>There are two schools of thought regarding dial-up modems on &unix;.
+	One group likes to configure their modems and systems so that no matter
+	at what speed a remote user dials in, the local computer-to-modem
+	RS-232 interface runs at a locked speed.  The benefit of this
+	configuration is that the remote user always sees a system login
+	prompt immediately.  The downside is that the system does not know
+	what a user's true data rate is, so full-screen programs like Emacs
+	will not adjust their screen-painting methods to make their response
+	better for slower connections.</para>
+
+      <para>The other school configures their modems' RS-232 interface to vary
+	its speed based on the remote user's connection speed.  For example,
+	V.32bis (14.4&nbsp;Kbps) connections to the modem might make the modem run
+	its RS-232 interface at 19.2&nbsp;Kbps, while 2400&nbsp;bps connections make the
+	modem's RS-232 interface run at 2400&nbsp;bps. Because
+	<command>getty</command> does not understand any particular modem's
+	connection speed reporting, <command>getty</command> gives a
+	<prompt>login:</prompt> message at an initial speed and watches the
+	characters that come back in response.  If the user sees junk, it is
+	assumed that they know they should press the
+	<keycode>Enter</keycode> key until they see a recognizable
+	prompt.  If the data rates do not match, <command>getty</command> sees
+	anything the user types as <quote>junk</quote>, tries going to the next
+	speed and gives the <prompt>login:</prompt> prompt again.  This
+	procedure can continue ad nauseam, but normally only takes a keystroke
+	or two before the user sees a good prompt.  Obviously, this login
+	sequence does not look as clean as the former
+	<quote>locked-speed</quote> method, but a user on a low-speed
+	connection should receive better interactive response from full-screen
+	programs.</para>
+
+      <para>This section will try to give balanced configuration information,
+	but is biased towards having the modem's data rate follow the
+	connection rate.</para>
+
+      <sect3>
+	<title><filename>/etc/gettytab</filename></title>
+
+  <indexterm>
+    <primary><filename>/etc/gettytab</filename></primary>
+  </indexterm>
+	<para><filename>/etc/gettytab</filename> is a &man.termcap.5;-style
+	  file of configuration information for &man.getty.8;.  Please see the
+	    &man.gettytab.5; manual page for complete information on the
+	  format of the file and the list of capabilities.</para>
+
+	<sect4>
+	  <title>Locked-speed Config</title>
+
+	  <para>If you are locking your modem's data communications rate at a
+	    particular speed, you probably will not need to make any changes
+	    to <filename>/etc/gettytab</filename>.</para>
+	</sect4>
+
+	<sect4>
+	  <title>Matching-speed Config</title>
+
+	  <para>You will need to set up an entry in
+	    <filename>/etc/gettytab</filename> to give
+	    <command>getty</command> information about the speeds you wish to
+	    use for your modem.  If you have a 2400&nbsp;bps modem, you can
+	    probably use the existing <literal>D2400</literal> entry.</para>
+
+	  <programlisting>#
+# Fast dialup terminals, 2400/1200/300 rotary (can start either way)
+#
+D2400|d2400|Fast-Dial-2400:\
+        :nx=D1200:tc=2400-baud:
+3|D1200|Fast-Dial-1200:\
+        :nx=D300:tc=1200-baud:
+5|D300|Fast-Dial-300:\
+        :nx=D2400:tc=300-baud:</programlisting>
+
+	  <para>If you have a higher speed modem, you will probably need to
+	    add an entry in <filename>/etc/gettytab</filename>; here is an
+	    entry you could use for a 14.4&nbsp;Kbps modem with a top interface
+	    speed of 19.2&nbsp;Kbps:</para>
+
+	  <programlisting>#
+# Additions for a V.32bis Modem
+#
+um|V300|High Speed Modem at 300,8-bit:\
+        :nx=V19200:tc=std.300:
+un|V1200|High Speed Modem at 1200,8-bit:\
+        :nx=V300:tc=std.1200:
+uo|V2400|High Speed Modem at 2400,8-bit:\
+        :nx=V1200:tc=std.2400:
+up|V9600|High Speed Modem at 9600,8-bit:\
+        :nx=V2400:tc=std.9600:
+uq|V19200|High Speed Modem at 19200,8-bit:\
+        :nx=V9600:tc=std.19200:</programlisting>
+
+	  <para>This will result in 8-bit, no parity connections.</para>
+
+	  <para>The example above starts the communications rate at 19.2&nbsp;Kbps
+	    (for a V.32bis connection), then cycles through 9600&nbsp;bps (for
+	    V.32), 2400&nbsp;bps, 1200&nbsp;bps, 300&nbsp;bps, and back to 19.2&nbsp;Kbps.
+	    Communications rate cycling is implemented with the
+	    <literal>nx=</literal> (<quote>next table</quote>) capability.
+	    Each of the lines uses a <literal>tc=</literal> (<quote>table
+	    continuation</quote>) entry to pick up the rest of the
+	    <quote>standard</quote> settings for a particular data rate.</para>
+
+	  <para>If you have a 28.8&nbsp;Kbps modem and/or you want to take
+	    advantage of compression on a 14.4&nbsp;Kbps modem, you need to use a
+	    higher communications rate than 19.2&nbsp;Kbps.  Here is an example of
+	    a <filename>gettytab</filename> entry starting a 57.6&nbsp;Kbps:</para>
+
+	  <programlisting>#
+# Additions for a V.32bis or V.34 Modem
+# Starting at 57.6 Kbps
+#
+vm|VH300|Very High Speed Modem at 300,8-bit:\
+        :nx=VH57600:tc=std.300:
+vn|VH1200|Very High Speed Modem at 1200,8-bit:\
+        :nx=VH300:tc=std.1200:
+vo|VH2400|Very High Speed Modem at 2400,8-bit:\
+        :nx=VH1200:tc=std.2400:
+vp|VH9600|Very High Speed Modem at 9600,8-bit:\
+        :nx=VH2400:tc=std.9600:
+vq|VH57600|Very High Speed Modem at 57600,8-bit:\
+        :nx=VH9600:tc=std.57600:</programlisting>
+
+	  <para>If you have a slow CPU or a heavily loaded system and do
+	    not have 16550A-based serial ports, you may receive
+	    <errorname>sio</errorname>
+	    <quote>silo</quote> errors at 57.6&nbsp;Kbps.</para>
+	</sect4>
+      </sect3>
+
+      <sect3 id="dialup-ttys">
+	<title><filename>/etc/ttys</filename></title>
+	<indexterm>
+	  <primary><filename>/etc/ttys</filename></primary>
+	</indexterm>
+
+	<para>Configuration of the <filename>/etc/ttys</filename> file
+	  was covered in <xref linkend="ex-etc-ttys">.
+	  Configuration for modems is similar but we must pass a
+	  different argument to <command>getty</command> and specify a
+	  different terminal type.  The general format for both
+	  locked-speed and matching-speed configurations is:</para>
+
+	<programlisting>ttyd0   "/usr/libexec/getty <replaceable>xxx</replaceable>"   dialup on</programlisting>
+
+	<para>The first item in the above line is the device special file for
+	  this entry &mdash; <literal>ttyd0</literal> means
+	  <filename>/dev/ttyd0</filename> is the file that this
+	  <command>getty</command> will be watching.  The second item,
+	  <literal>"/usr/libexec/getty
+	    <replaceable>xxx</replaceable>"</literal>
+	  (<replaceable>xxx</replaceable> will be replaced by the initial
+	  <filename>gettytab</filename> capability) is the process
+	  <command>init</command> will run on the device.  The third item,
+	  <literal>dialup</literal>, is the default terminal type.  The fourth
+	  parameter, <literal>on</literal>, indicates to
+	  <command>init</command> that the line is operational.  There can be
+	  a fifth parameter, <literal>secure</literal>, but it should only be
+	  used for terminals which are physically secure (such as the system
+	  console).</para>
+
+	<para>The default terminal type (<literal>dialup</literal> in the
+	  example above) may depend on local preferences.
+	  <literal>dialup</literal> is the traditional default terminal type
+	  on dial-up lines so that users may customize their login scripts to
+	  notice when the terminal is <literal>dialup</literal> and
+	  automatically adjust their terminal type.  However, the author finds
+	  it easier at his site to specify <literal>vt102</literal> as the
+	  default terminal type, since the users just use VT102 emulation on
+	  their remote systems.</para>
+
+	<para>After you have made changes to <filename>/etc/ttys</filename>,
+	  you may send the <command>init</command> process a
+	  <acronym>HUP</acronym> signal to re-read the file.  You can use the
+	  command
+
+	<screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen>
+
+	  to send the signal.  If this is your first time setting up the
+	  system, you may want to wait until your modem(s) are properly
+	  configured and connected before signaling <command>init</command>.
+	  </para>
+
+	<sect4>
+	  <title>Locked-speed Config</title>
+
+	  <para>For a locked-speed configuration, your
+	    <filename>ttys</filename> entry needs to have a fixed-speed entry
+	    provided to <command>getty</command>.  For a modem whose port
+	    speed is locked at 19.2&nbsp;Kbps, the <filename>ttys</filename> entry
+	    might look like this:</para>
+
+	  <programlisting>ttyd0   "/usr/libexec/getty std.19200"   dialup on</programlisting>
+
+	  <para>If your modem is locked at a different data rate,
+	    substitute the appropriate value for
+	    <literal>std.<replaceable>speed</replaceable></literal>
+	    instead of <literal>std.19200</literal>.  Make sure that
+	    you use a valid type listed in
+	    <filename>/etc/gettytab</filename>.</para>
+	</sect4>
+
+	<sect4>
+	  <title>Matching-speed Config</title>
+
+	  <para>In a matching-speed configuration, your
+	    <filename>ttys</filename> entry needs to reference the appropriate
+	    beginning <quote>auto-baud</quote> (sic) entry in
+	    <filename>/etc/gettytab</filename>.  For example, if you added the
+	    above suggested entry for a matching-speed modem that starts at
+	    19.2&nbsp;Kbps (the <filename>gettytab</filename> entry containing the
+	    <literal>V19200</literal> starting point), your
+	    <filename>ttys</filename> entry might look like this:</para>
+
+	  <programlisting>ttyd0   "/usr/libexec/getty V19200"   dialup on</programlisting>
+	</sect4>
+      </sect3>
+
+      <sect3>
+	<title><filename>/etc/rc.d/serial</filename></title>
+	<indexterm>
+	  <primary>rc files</primary>
+	  <secondary><filename>rc.serial</filename></secondary>
+	</indexterm>
+
+	<para>High-speed modems, like V.32, V.32bis, and V.34 modems,
+	  need to use hardware (<literal>RTS/CTS</literal>) flow
+	  control. You can add <command>stty</command> commands to
+	  <filename>/etc/rc.d/serial</filename> to set the hardware flow
+	  control flag in the FreeBSD kernel for the modem
+	  ports.</para>
+
+	<para>For example to set the <literal>termios</literal> flag
+	  <varname>crtscts</varname> on serial port #1's
+	  (<devicename>COM2</devicename>) dial-in and dial-out initialization
+	  devices, the following lines could be added to
+	  <filename>/etc/rc.d/serial</filename>:</para>
+	<programlisting># Serial port initial configuration
+stty -f /dev/ttyd1.init crtscts
+stty -f /dev/cuad1.init crtscts</programlisting>
+
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Modem Settings</title>
+
+      <para>If you have a modem whose parameters may be permanently set in
+	non-volatile RAM, you will need to use a terminal program (such as
+	Telix under &ms-dos; or <command>tip</command> under FreeBSD) to set the
+	parameters.  Connect to the modem using the same communications speed
+	as the initial speed <command>getty</command> will use and configure
+	the modem's non-volatile RAM to match these requirements:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><acronym>CD</acronym> asserted when connected</para>
+	</listitem>
+
+	<listitem>
+	  <para><acronym>DTR</acronym> asserted for operation; dropping DTR
+	    hangs up line and resets modem</para>
+	</listitem>
+
+	<listitem>
+	  <para><acronym>CTS</acronym> transmitted data flow control</para>
+	</listitem>
+
+	<listitem>
+	  <para>Disable <acronym>XON/XOFF</acronym> flow control</para>
+	</listitem>
+
+	<listitem>
+	  <para><acronym>RTS</acronym> received data flow control</para>
+	</listitem>
+
+	<listitem>
+	  <para>Quiet mode (no result codes)</para>
+	</listitem>
+
+	<listitem>
+	  <para>No command echo</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Please read the documentation for your modem to find out what
+	commands and/or DIP switch settings you need to give it.</para>
+
+      <para>For example, to set the above parameters on a &usrobotics;
+	&sportster; 14,400 external modem, one could give these commands to
+	the modem:</para>
+
+      <programlisting>ATZ
+AT&amp;C1&amp;D2&amp;H1&amp;I0&amp;R2&amp;W</programlisting>
+
+      <para>You might also want to take this opportunity to adjust other
+	settings in the modem, such as whether it will use V.42bis and/or MNP5
+	compression.</para>
+
+      <para>The &usrobotics; &sportster; 14,400 external modem also has some DIP switches
+	that need to be set; for other modems, perhaps you can use these
+	settings as an example:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Switch 1: UP &mdash; DTR Normal</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 2: N/A (Verbal Result Codes/Numeric Result
+	    Codes)</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 3: UP &mdash; Suppress Result Codes</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 4: DOWN &mdash; No echo, offline commands</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 5: UP &mdash; Auto Answer</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 6: UP &mdash; Carrier Detect Normal</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 7: UP &mdash; Load NVRAM Defaults</para>
+	</listitem>
+
+	<listitem>
+	  <para>Switch 8: N/A (Smart Mode/Dumb Mode)</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Result codes should be disabled/suppressed for dial-up modems to
+	avoid problems that can occur if <command>getty</command> mistakenly
+	gives a <prompt>login:</prompt> prompt to a modem that is in command
+	mode and the modem echoes the command or returns a result
+	code.  This sequence can result in a extended, silly conversation
+ 	between <command>getty</command> and the modem.</para>
+
+      <sect3>
+	<title>Locked-speed Config</title>
+
+	<para>For a locked-speed configuration, you will need to configure the
+	  modem to maintain a constant modem-to-computer data rate independent
+	  of the communications rate.  On a &usrobotics; &sportster; 14,400 external
+	  modem, these commands will lock the modem-to-computer data rate at
+	  the speed used to issue the commands:</para>
+
+	<programlisting>ATZ
+AT&amp;B1&amp;W</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>Matching-speed Config</title>
+
+	<para>For a variable-speed configuration, you will need to configure
+	  your modem to adjust its serial port data rate to match the incoming
+	  call rate.  On a &usrobotics; &sportster; 14,400 external modem, these commands
+	  will lock the modem's error-corrected data rate to the speed used to
+	  issue the commands, but allow the serial port rate to vary for
+	  non-error-corrected connections:</para>
+
+	<programlisting>ATZ
+AT&amp;B2&amp;W</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>Checking the Modem's Configuration</title>
+
+	<para>Most high-speed modems provide commands to view the modem's
+	  current operating parameters in a somewhat human-readable fashion.
+	  On the &usrobotics; &sportster; 14,400 external modems, the command
+	  <command>ATI5</command> displays the settings that are stored in the
+	  non-volatile RAM.  To see the true operating parameters of the modem
+	  (as influenced by the modem's DIP switch settings), use the commands
+	  <command>ATZ</command> and then <command>ATI4</command>.</para>
+
+	<para>If you have a different brand of modem, check your modem's
+	  manual to see how to double-check your modem's configuration
+	  parameters.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <para>Here are a few steps you can follow to check out the dial-up modem
+	on your system.</para>
+
+      <sect3>
+	<title>Checking Out the FreeBSD System</title>
+
+	<para>Hook up your modem to your FreeBSD system, boot the system, and,
+	  if your modem has status indication lights, watch to see whether the
+	  modem's <acronym>DTR</acronym> indicator lights when the
+	  <prompt>login:</prompt> prompt appears on the system's console
+	  &mdash; if it lights up, that should mean that FreeBSD has started a
+	  <command>getty</command> process on the appropriate communications
+	  port and is waiting for the modem to accept a call.</para>
+
+	<para>If the <acronym>DTR</acronym> indicator does not light, login to
+	  the FreeBSD system through the console and issue a <command>ps
+	    ax</command> to see if FreeBSD is trying to run a
+	  <command>getty</command> process on the correct port. You should see
+	  lines like these among the processes displayed:</para>
+
+	<screen>  114 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd0
+  115 ??  I      0:00.10 /usr/libexec/getty V19200 ttyd1</screen>
+
+	<para>If you see something different, like this:</para>
+
+	  <screen>  114 d0  I      0:00.10 /usr/libexec/getty V19200 ttyd0</screen>
+
+	<para>and the modem has not accepted a call yet, this means that
+	  <command>getty</command> has completed its open on the
+	  communications port.  This could indicate a problem with the cabling
+	  or a mis-configured modem, because <command>getty</command> should
+	  not be able to open the communications port until
+	  <acronym>CD</acronym> (carrier detect) has been asserted by the
+	  modem.</para>
+
+	<para>If you do not see any <command>getty</command> processes waiting
+	  to open the desired
+	  <filename>ttyd<replaceable>N</replaceable></filename> port,
+	  double-check your entries in <filename>/etc/ttys</filename> to see
+	  if there are any mistakes there.  Also, check the log file
+	  <filename>/var/log/messages</filename> to see if there are any log
+	  messages from <command>init</command> or <command>getty</command>
+	  regarding any problems.  If there are any messages, triple-check the
+	  configuration files <filename>/etc/ttys</filename> and
+	  <filename>/etc/gettytab</filename>, as well as the appropriate
+	  device special files <filename>/dev/ttydN</filename>, for any
+	  mistakes, missing entries, or missing device special files.</para>
+      </sect3>
+
+      <sect3>
+	<title>Try Dialing In</title>
+
+	<para>Try dialing into the system; be sure to use 8 bits, no parity,
+	  and 1
+	  stop bit on the remote system.  If you do not get a prompt right
+	  away, or get garbage, try pressing <keycode>Enter</keycode>
+	  about once per second.  If you still do not see a
+	  <prompt>login:</prompt> prompt after a while, try sending a
+	  <command>BREAK</command>. If you are using a high-speed modem to do
+	  the dialing, try dialing again after locking the dialing modem's
+	  interface speed (via <command>AT&amp;B1</command> on a &usrobotics;
+	  &sportster; modem, for example).</para>
+
+	<para>If you still cannot get a <prompt>login:</prompt> prompt, check
+	  <filename>/etc/gettytab</filename> again and double-check
+	  that</para>
+
+	<itemizedlist>
+	  <listitem>
+	    <para>The initial capability name specified in
+	      <filename>/etc/ttys</filename> for the line matches a name of a
+	      capability in <filename>/etc/gettytab</filename></para>
+		</listitem>
+
+	  <listitem>
+	    <para>Each <literal>nx=</literal> entry matches another
+	      <filename>gettytab</filename> capability name</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>Each <literal>tc=</literal> entry matches another
+	      <filename>gettytab</filename> capability name</para>
+	  </listitem>
+	</itemizedlist>
+
+	<para>If you dial but the modem on the FreeBSD system will not answer,
+	  make sure that the modem is configured to answer the phone when
+	  <acronym>DTR</acronym> is asserted.  If the modem seems to be
+	  configured correctly, verify that the <acronym>DTR</acronym> line is
+	  asserted by checking the modem's indicator lights (if it has
+	  any).</para>
+
+	<para>If you have gone over everything several times and it still does
+	  not work, take a break and come back to it later.  If it still does
+	  not work, perhaps you can send an electronic mail message to the
+	  &a.questions; describing your modem and your problem, and the good
+	  folks on the list will try to help.</para>
+      </sect3>
+    </sect2>
+
+  </sect1>
+
+  <sect1 id="dialout">
+    <title>Dial-out Service</title>
+    <indexterm><primary>dial-out service</primary></indexterm>
+
+    <para>The following are tips for getting your host to be able to connect
+      over the modem to another computer.  This is appropriate for
+      establishing a terminal session with a remote host.</para>
+
+    <para>This is useful to log onto a BBS.</para>
+
+    <para>This kind of connection can be extremely helpful to get a file on
+      the Internet if you have problems with PPP.  If you need to FTP
+      something and PPP is broken, use the terminal session to FTP it. Then
+      use zmodem to transfer it to your machine.</para>
+
+    <sect2>
+      <title>My Stock Hayes Modem Is Not Supported, What Can I Do?</title>
+
+      <para>Actually, the manual page for <command>tip</command> is out of date.
+	There is a generic Hayes dialer already built in. Just use
+	<literal>at=hayes</literal> in your <filename>/etc/remote</filename>
+	file.</para>
+
+      <para>The Hayes driver is not smart enough to recognize some of the
+	advanced features of newer modems&mdash;messages like
+	<literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or
+	<literal>CONNECT 115200</literal> will just confuse it.  You should
+	turn those messages off when you use <command>tip</command> (using
+	<command>ATX0&amp;W</command>).</para>
+
+      <para>Also, the dial timeout for <command>tip</command> is 60 seconds.
+	Your modem should use something less, or else tip will think there is
+	a communication problem.  Try <command>ATS7=45&amp;W</command>.</para>
+
+      <note>
+	<para>As shipped, <command>tip</command> does not yet support
+	  Hayes modems fully.  The solution is to edit the file
+	  <filename>tipconf.h</filename> in the directory
+	  <filename>/usr/src/usr.bin/tip/tip</filename>. Obviously you need the
+	  source distribution to do this.</para>
+
+	<para>Edit the line <literal>#define HAYES 0</literal> to
+	  <literal>#define HAYES 1</literal>.  Then <command>make</command> and
+	  <command>make install</command>.  Everything works nicely after
+	  that.</para>
+      </note>
+    </sect2>
+
+    <sect2 id="direct-at">
+      <title>How Am I Expected to Enter These AT Commands?</title>
+
+      <indexterm>
+	<primary><filename>/etc/remote</filename></primary>
+      </indexterm>
+      <para>Make what is called a <quote>direct</quote> entry in your
+	<filename>/etc/remote</filename> file.  For example, if your modem is
+	hooked up to the first serial port, <filename>/dev/cuad0</filename>,
+	then put in the following line:</para>
+
+      <programlisting>cuad0:dv=/dev/cuad0:br#19200:pa=none</programlisting>
+
+      <para>Use the highest bps rate your modem supports in the br capability.
+	Then, type <command>tip cuad0</command> and you will be connected to
+	your modem.</para>
+
+      <para>Or use <command>cu</command> as <username>root</username> with the
+	following command:</para>
+
+      <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen>
+
+      <para><replaceable>line</replaceable> is the serial port
+	(e.g.<filename>/dev/cuad0</filename>) and
+	<replaceable>speed</replaceable> is the speed
+	(e.g.<literal>57600</literal>).  When you are done entering the AT
+	commands hit <keycap>~.</keycap> to exit.</para>
+    </sect2>
+
+    <sect2>
+      <title>The <literal>@</literal> Sign for the pn Capability Does Not
+	Work!</title>
+
+      <para>The <literal>@</literal> sign in the phone number capability tells
+	tip to look in <filename>/etc/phones</filename> for a phone number.
+	But the <literal>@</literal> sign is also a special character in
+	capability files like <filename>/etc/remote</filename>.  Escape it
+	with a backslash:</para>
+
+      <programlisting>pn=\@</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>How Can I Dial a Phone Number on the Command Line?</title>
+
+      <para>Put what is called a <quote>generic</quote> entry in your
+	<filename>/etc/remote</filename> file.  For example:</para>
+
+      <programlisting>tip115200|Dial any phone number at 115200 bps:\
+        :dv=/dev/cuad0:br#115200:at=hayes:pa=none:du:
+tip57600|Dial any phone number at 57600 bps:\
+        :dv=/dev/cuad0:br#57600:at=hayes:pa=none:du:</programlisting>
+
+      <para>Then you can do things like:</para>
+
+      <screen>&prompt.root; <userinput>tip -115200 5551234</userinput></screen>
+
+      <para>If you prefer <command>cu</command> over <command>tip</command>,
+	use a generic <literal>cu</literal> entry:</para>
+
+      <programlisting>cu115200|Use cu to dial any number at 115200bps:\
+        :dv=/dev/cuad1:br#57600:at=hayes:pa=none:du:</programlisting>
+
+      <para>and type:</para>
+
+      <screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen>
+    </sect2>
+
+    <sect2>
+      <title>Do I Have to Type in the bps Rate Every Time I Do That?</title>
+
+      <para>Put in an entry for <literal>tip1200</literal> or
+	<literal>cu1200</literal>, but go ahead and use whatever bps rate is
+	appropriate with the br capability.  <command>tip</command> thinks a
+	good default is 1200&nbsp;bps which is why it looks for a
+	<literal>tip1200</literal> entry.  You do not have to use 1200&nbsp;bps,
+	though.</para>
+    </sect2>
+
+    <sect2>
+      <title>I Access a Number of Hosts Through a Terminal Server</title>
+
+      <para>Rather than waiting until you are connected and typing
+	<command>CONNECT &lt;host&gt;</command> each time, use tip's
+	<literal>cm</literal> capability.  For example, these entries in
+	<filename>/etc/remote</filename>:</para>
+
+      <programlisting>pain|pain.deep13.com|Forrester's machine:\
+        :cm=CONNECT pain\n:tc=deep13:
+muffin|muffin.deep13.com|Frank's machine:\
+        :cm=CONNECT muffin\n:tc=deep13:
+deep13:Gizmonics Institute terminal server:\
+        :dv=/dev/cuad2:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting>
+
+      <para>will let you type <command>tip pain</command> or <command>tip
+	  muffin</command> to connect to the hosts pain or muffin, and
+	<command>tip deep13</command> to get to the terminal server.</para>
+    </sect2>
+
+    <sect2>
+      <title>Can Tip Try More Than One Line for Each Site?</title>
+
+      <para>This is often a problem where a university has several modem lines
+	and several thousand students trying to use them.</para>
+
+      <para>Make an entry for your university in
+	<filename>/etc/remote</filename> and use <literal>@</literal> for the
+	<literal>pn</literal> capability:</para>
+
+      <programlisting>big-university:\
+        :pn=\@:tc=dialout
+dialout:\
+        :dv=/dev/cuad3:br#9600:at=courier:du:pa=none:</programlisting>
+
+      <para>Then, list the phone numbers for the university in
+	<filename>/etc/phones</filename>:</para>
+
+      <programlisting>big-university 5551111
+big-university 5551112
+big-university 5551113
+big-university 5551114</programlisting>
+
+      <para><command>tip</command> will try each one in the listed order, then
+	give up.  If you want to keep retrying, run <command>tip</command> in
+	a while loop.</para>
+    </sect2>
+
+    <sect2>
+      <title>Why Do I Have to Hit
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap>
+	  <keycap>P</keycap>
+	</keycombo>
+	Twice to Send
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap>
+	  <keycap>P</keycap>
+	</keycombo>
+	Once?</title>
+
+      <para><keycombo action="simul"><keycap>Ctrl</keycap><keycap>P</keycap></keycombo> is the default <quote>force</quote> character, used to tell
+	<command>tip</command> that the next character is literal data.  You
+	can set the force character to any other character with the
+	<command>~s</command> escape, which means <quote>set a
+	variable.</quote></para>
+
+      <para>Type
+	<command>~sforce=<replaceable>single-char</replaceable></command>
+	followed by a newline.  <replaceable>single-char</replaceable> is any
+	single character. If you leave out
+	<replaceable>single-char</replaceable>, then the force character is
+	the nul character, which you can get by typing
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap><keycap>2</keycap>
+	</keycombo>
+	or
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap><keycap>Space</keycap>
+	</keycombo>.
+	A pretty good value for <replaceable>single-char</replaceable> is
+	<keycombo action="simul">
+	  <keycap>Shift</keycap>
+	  <keycap>Ctrl</keycap>
+	  <keycap>6</keycap>
+	</keycombo>, which is only used on some terminal
+	servers.</para>
+
+      <para>You can have the force character be whatever you want by
+	specifying the following in your <filename>&#36;HOME/.tiprc</filename>
+	file:</para>
+
+      <programlisting>force=&lt;single-char&gt;</programlisting>
+    </sect2>
+
+    <sect2>
+      <title>Suddenly Everything I Type Is in Upper Case??</title>
+
+      <para>You must have pressed
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap>
+	  <keycap>A</keycap>
+	</keycombo>, <command>tip</command>'s
+	<quote>raise character,</quote> specially designed for people with
+	broken caps-lock keys.  Use <command>~s</command> as above and set the
+	variable <literal>raisechar</literal> to something reasonable.  In
+	fact, you can set it to the same as the force character, if you never
+	expect to use either of these features.</para>
+
+      <para>Here is a sample .tiprc file perfect for
+	<application>Emacs</application> users who need to type
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap><keycap>2</keycap>
+	</keycombo>
+	and
+	<keycombo action="simul">
+	  <keycap>Ctrl</keycap><keycap>A</keycap>
+	</keycombo>
+	a lot:</para>
+
+      <programlisting>force=^^
+raisechar=^^</programlisting>
+
+      <para>The ^^ is
+	<keycombo action="simul">
+	  <keycap>Shift</keycap><keycap>Ctrl</keycap><keycap>6</keycap>
+	</keycombo>.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>How Can I Do File Transfers with <command>tip</command>?</title>
+
+      <para>If you are talking to another &unix; system, you can send and
+	receive files with <command>~p</command> (put) and
+	<command>~t</command> (take).  These commands run
+	<command>cat</command> and <command>echo</command> on the remote
+	system to accept and send files.  The syntax is:</para>
+
+      <cmdsynopsis>
+	<command>~p</command>
+	<arg choice="plain">local-file</arg>
+	<arg choice="opt">remote-file</arg>
+      </cmdsynopsis>
+
+      <cmdsynopsis>
+	<command>~t</command>
+	<arg choice="plain">remote-file</arg>
+	<arg choice="opt">local-file</arg>
+      </cmdsynopsis>
+
+      <para>There is no error checking, so you probably should use another
+	protocol, like zmodem.</para>
+    </sect2>
+
+    <sect2>
+      <title>How Can I Run zmodem with <command>tip</command>?</title>
+
+      <para>To receive files, start the sending program on the remote end.
+	Then, type <command>~C rz</command> to begin receiving them
+	locally.</para>
+
+      <para>To send files, start the receiving program on the remote end.
+	Then, type <command>~C sz <replaceable>files</replaceable></command>
+	to send them to the remote system.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="serialconsole-setup">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Kazutaka</firstname>
+	  <surname>YOKOTA</surname>
+	  <contrib>Contributed by </contrib>
+	</author>
+      </authorgroup>
+      <authorgroup>
+	<author>
+	  <firstname>Bill</firstname>
+	  <surname>Paul</surname>
+	  <contrib>Based on a document by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Setting Up the Serial Console</title>
+    <indexterm><primary>serial console</primary></indexterm>
+
+    <sect2 id="serialconsole-intro">
+      <title>Introduction</title>
+
+      <para>FreeBSD has the ability to boot on a system with only
+	a dumb terminal on a serial port as a console.  Such a configuration
+	should be useful for two classes of people:  system administrators who
+	wish to install FreeBSD on machines that have no keyboard or monitor
+	attached, and developers who want to debug the kernel or device
+	drivers.</para>
+
+      <para>As described in <xref linkend="boot">, FreeBSD employs a three stage
+	bootstrap.  The first two stages are in the boot block code which is
+	stored at the beginning of the FreeBSD slice on the boot disk.  The
+	boot block will then load and run the boot loader
+	(<filename>/boot/loader</filename>) as the third stage code.</para>
+
+      <para>In order to set up the serial console you must configure the boot
+	block code, the boot loader code and the kernel.</para>
+
+    </sect2>
+
+    <sect2 id="serialconsole-howto-fast">
+      <title>Serial Console Configuration, Terse Version</title>
+
+      <para>This section assumes that you are using the default setup
+	and just want a fast overview of setting up the serial
+	console.</para>
+
+      <procedure>
+
+	<step>
+	  <para>Connect the serial cable to COM1 and the controlling
+	    terminal.</para>
+	</step>
+
+	<step>
+	  <para>To see all boot messages on the serial console, issue
+	    the following command while logged in as the superuser:</para>
+	  <screen>&prompt.root; echo 'console="comconsole"' &gt;&gt; /boot/loader.conf</screen>
+	</step>
+
+	<step>
+	  <para>Edit <filename>/etc/ttys</filename> and change
+	    <literal>off</literal> to <literal>on</literal> and
+	    <literal>dialup</literal> to <literal>vt100</literal> for the
+	    <literal>ttyd0</literal> entry.  Otherwise a password will not be
+	    required to connect via the serial console, resulting in a
+	    potential security hole.</para>
+	</step>
+
+	<step>
+	  <para><para>Reboot the system to see if the changes took effect.</para>
+	</step>
+
+      </procedure>
+
+      <para>If a different configuration is required, a more in depth
+	configuration explanation exists in
+	<xref linkend="serialconsole-howto">.</para>
+    </sect2>
+
+    <sect2 id="serialconsole-howto">
+      <title>Serial Console Configuration</title>
+
+      <procedure>
+	<step>
+	  <para>Prepare a serial cable.</para>
+
+	  <indexterm><primary>null-modem cable</primary></indexterm>
+	  <para>You will need either a null-modem cable or a standard serial
+	    cable and a null-modem adapter.  See <xref linkend="serial-cables-ports"> for
+	    a discussion on serial cables.</para>
+	</step>
+
+	<step>
+	  <para>Unplug your keyboard.</para>
+
+	  <para>Most PC systems probe for the keyboard during the Power-On
+	    Self-Test (POST) and will generate an error if the keyboard is not
+	    detected.  Some machines complain loudly about the lack of a
+	    keyboard and will not continue to boot until it is plugged
+	    in.</para>
+
+	  <para>If your computer complains about the error, but boots anyway,
+	    then you do not have to do anything special.  (Some machines with
+	    Phoenix BIOS installed merely say <errorname>Keyboard
+	      failed</errorname> and continue to boot normally.)</para>
+
+	  <para>If your computer refuses to boot without a keyboard attached
+	    then you will have to configure the BIOS so that it ignores this
+	    error (if it can).  Consult your motherboard's manual for details
+	    on how to do this.</para>
+
+	  <tip>
+	    <para>Set the keyboard to <quote>Not installed</quote> in the
+	      BIOS setup.  You will still
+	      be able to use your keyboard.  All this does is tell the BIOS
+	      not to probe for a keyboard at power-on.  Your BIOS should not
+	      complain if the keyboard is absent.  You can leave the
+	      keyboard plugged in even with this flag set to <quote>Not
+	      installed</quote> and the keyboard will still work.</para>
+	  </tip>
+
+	  <note>
+	    <para>If your system has a &ps2; mouse, chances are very good  that
+	      you may have to unplug your mouse as well as your keyboard.
+	      This is because &ps2; mice share some hardware with the keyboard
+	      and leaving the mouse plugged in can fool the keyboard probe
+	      into thinking the keyboard is still there.  It is said that a
+	      Gateway 2000 Pentium 90&nbsp;MHz system with an AMI BIOS that behaves
+	      this way.  In general, this is not a problem since the mouse is
+	      not much good without the keyboard anyway.</para>
+	  </note>
+	</step>
+
+	<step>
+	  <para>Plug a dumb terminal into <devicename>COM1</devicename>
+	    (<devicename>sio0</devicename>).</para>
+
+	  <para>If you do not have a dumb terminal, you can use an old PC/XT
+	    with a modem program, or the serial port on another &unix; box.  If
+	    you do not have a <devicename>COM1</devicename>
+	    (<devicename>sio0</devicename>), get one.  At this time, there is
+	    no way to select a port other than <devicename>COM1</devicename>
+	    for the boot blocks without recompiling the boot blocks.  If you
+	    are already using <devicename>COM1</devicename> for another
+	    device, you will have to temporarily remove that device and
+	    install a new boot block and kernel once you get FreeBSD up and
+	    running. (It is assumed that <devicename>COM1</devicename> will
+	    be available on a file/compute/terminal server anyway; if you
+	    really need <devicename>COM1</devicename> for something else
+	    (and you cannot switch that something else to
+	    <devicename>COM2</devicename> (<devicename>sio1</devicename>)),
+	    then you probably should not even be bothering with all this in
+	    the first place.)</para>
+	</step>
+
+	<step>
+	  <para>Make sure the configuration file of your kernel has
+	    appropriate flags set for <devicename>COM1</devicename>
+	    (<devicename>sio0</devicename>).</para>
+
+	  <para>Relevant flags are:</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><literal>0x10</literal></term>
+
+	      <listitem>
+		<para>Enables console support for this unit.  The other
+		  console flags are ignored unless this is set. Currently, at
+		  most one unit can have console support;  the first one (in
+		  config file order) with this flag set is preferred.  This
+		  option alone will not make the serial port the console.  Set
+		  the following flag or use the <option>-h</option> option
+		  described below, together with this flag.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>0x20</literal></term>
+
+	      <listitem>
+		<para>Forces this unit to be the console (unless there is
+		  another higher priority console), regardless of the
+		  <option>-h</option> option discussed below.
+		  The flag <literal>0x20</literal> must be used
+		  together with the <option>0x10</option> flag.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><literal>0x40</literal></term>
+
+	      <listitem>
+		<para>Reserves this unit (in conjunction with
+		  <literal>0x10</literal>) and makes the unit
+		  unavailable for normal access.  You should not set
+		  this flag to the serial port unit which you want to
+		  use as the serial console.  The only use of this
+		  flag is to designate the unit for kernel remote
+		  debugging.  See <ulink
+		  url="&url.books.developers-handbook;/index.html">The
+		  Developer's Handbook</ulink> for more information on
+		  remote debugging.</para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+
+	  <para>Example:</para>
+
+	  <programlisting>device sio0 at isa? port IO_COM1 flags 0x10 irq 4</programlisting>
+
+	  <para>See the &man.sio.4; manual page for more details.</para>
+
+	  <para>If the flags were not set, you need to run UserConfig (on a
+	    different console) or recompile the kernel.</para>
+	</step>
+
+	<step>
+	  <para>Create <filename>boot.config</filename> in the root directory
+	    of the <literal>a</literal> partition on the boot drive.</para>
+
+	  <para>This file will instruct the boot block code how you would like
+	    to boot the system.  In order to activate the serial console, you
+	    need one or more of the following options&mdash;if you want
+	    multiple options, include them all on the same line:</para>
+
+	  <variablelist>
+	    <varlistentry>
+	      <term><option>-h</option></term>
+
+	      <listitem>
+		<para>Toggles internal and serial consoles.  You can use this
+		  to switch console devices.  For instance, if you boot from
+		  the internal (video) console, you can use
+		  <option>-h</option> to direct the boot loader and the kernel
+		  to use the serial port as its console device. Alternatively,
+		  if you boot from the serial port, you can use the
+		  <option>-h</option> to tell the boot loader and the kernel
+		  to use the video display as the console instead.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-D</option></term>
+
+	      <listitem>
+		<para>Toggles single and dual console configurations.  In the
+		  single configuration the console will be either the internal
+		  console (video display) or the serial port, depending on the
+		  state of the <option>-h</option> option above.  In the dual
+		  console configuration, both the video display  and the
+		  serial port will become the console at the same time,
+		  regardless of the state of the <option>-h</option> option.
+		  However, note that the dual console configuration takes  effect
+		  only during the boot block is running.  Once the boot loader
+		  gets control, the console specified by the
+		  <option>-h</option> option becomes the only console.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term><option>-P</option></term>
+
+	      <listitem>
+		<para>Makes the boot block probe the keyboard.  If no keyboard
+		  is found, the <option>-D</option> and <option>-h</option>
+		  options are automatically set.</para>
+
+		<note>
+		  <para>Due to space constraints in the current version of the
+		    boot blocks, the <option>-P</option> option is capable of
+		    detecting extended keyboards only.  Keyboards with less
+		    than 101 keys (and without F11 and F12  keys) may not be
+		    detected.  Keyboards on some laptop computers may not be
+		    properly found because of this limitation.  If this is
+		    the case with your system, you have to abandon using
+		    the <option>-P</option> option.  Unfortunately there is no
+		    workaround for this problem.</para>
+		</note>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+
+	  <para>Use either the <option>-P</option> option to select the
+	    console automatically, or the <option>-h</option> option to
+	    activate the serial console.</para>
+
+	  <para>You may include other options described in &man.boot.8; as
+	    well.</para>
+
+	  <para>The options, except for <option>-P</option>, will be passed to
+	    the boot loader (<filename>/boot/loader</filename>).  The boot
+	    loader will determine which of the internal video or the serial
+	    port should become the console by examining the state of the
+	    <option>-h</option> option alone.  This means that if you specify
+	    the <option>-D</option> option but not the <option>-h</option>
+	    option in <filename>/boot.config</filename>, you can use the
+	    serial port as the console only during the boot block;  the boot
+	    loader will use the internal video display as the console.</para>
+	</step>
+
+	<step>
+	  <para>Boot the machine.</para>
+
+	  <para>When you start your FreeBSD box, the boot blocks will echo the
+	    contents of <filename>/boot.config</filename> to the console.  For
+	    example:</para>
+
+	  <screen>/boot.config: -P
+Keyboard: no</screen>
+
+	  <para>The second line appears only if you put <option>-P</option> in
+	    <filename>/boot.config</filename> and indicates presence/absence
+	    of the keyboard.  These messages go to either serial or internal
+	    console, or both, depending on the option in
+	    <filename>/boot.config</filename>.</para>
+
+	  <informaltable frame="none" pgwide="1">
+	    <tgroup cols="2">
+	      <thead>
+		<row>
+		  <entry align="left">Options</entry>
+		  <entry align="left">Message goes to</entry>
+		</row>
+	      </thead>
+
+	      <tbody>
+		<row>
+		  <entry>none</entry>
+		  <entry>internal console</entry>
+		</row>
+
+		<row>
+		  <entry><option>-h</option></entry>
+		  <entry>serial console</entry>
+		</row>
+
+		<row>
+		  <entry><option>-D</option></entry>
+		  <entry>serial and internal consoles</entry>
+		</row>
+
+		<row>
+		  <entry><option>-Dh</option></entry>
+		  <entry>serial and internal consoles</entry>
+		</row>
+
+		<row>
+		  <entry><option>-P</option>, keyboard present</entry>
+		  <entry>internal console</entry>
+		</row>
+
+		<row>
+		  <entry><option>-P</option>, keyboard absent</entry>
+		  <entry>serial console</entry>
+		</row>
+	      </tbody>
+	    </tgroup>
+	  </informaltable>
+
+	  <para>After the above messages, there will be a small pause before
+	    the boot blocks continue loading the boot loader and before any
+	    further messages printed to the console.  Under normal
+	    circumstances, you do not need to interrupt the boot blocks, but
+	    you may want to do so in order to make sure things are set up
+	    correctly.</para>
+
+	  <para>Hit any key, other than <keycode>Enter</keycode>, at the console to
+	    interrupt the boot process.  The boot blocks will then prompt you
+	    for further action.  You should now see something like:</para>
+
+	  <screen>&gt;&gt; FreeBSD/i386 BOOT
+Default: 0:ad(0,a)/boot/loader
+boot:</screen>
+
+	  <para>Verify the above message appears on either the serial or
+	    internal console or both, according to the options you put in
+	    <filename>/boot.config</filename>.  If the message appears in the
+	    correct console, hit <keycode>Enter</keycode> to continue the boot
+	    process.</para>
+
+	  <para>If you want the serial console but you do not see the prompt
+	    on the serial terminal, something is wrong with your settings.  In
+	    the meantime, you enter <option>-h</option> and hit Enter/Return
+	    (if possible) to tell the boot block (and then the boot loader and
+	    the kernel) to choose the serial port for the console. Once the
+	    system is up, go back and check what went wrong.</para>
+	</step>
+      </procedure>
+
+      <para>After the boot loader is loaded and you are in the third stage of
+	the boot process you can still switch between the internal console and
+	the serial console by setting appropriate environment variables in the
+	boot loader.  See <xref linkend="serialconsole-loader">.</para>
+    </sect2>
+
+  <sect2 id="serialconsole-summary">
+    <title>Summary</title>
+
+      <para>Here is the summary of various settings discussed in this section
+	and the console eventually selected.</para>
+
+      <sect3>
+	<title>Case 1: You Set the Flags to 0x10 for
+	  <devicename>sio0</devicename></title>
+
+	<programlisting>device sio0 at isa? port IO_COM1 flags 0x10 irq 4</programlisting>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="4">
+	    <thead>
+	      <row>
+		<entry align="left">Options in /boot.config</entry>
+		<entry align="left">Console during boot blocks</entry>
+		<entry align="left">Console during boot loader</entry>
+		<entry align="left">Console in kernel</entry>
+	      </row>
+	    </thead>
+
+	    <tbody>
+	      <row>
+		<entry>nothing</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-h</option></entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-D</option></entry>
+		<entry>serial and internal</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-Dh</option></entry>
+		<entry>serial and internal</entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-P</option>, keyboard present</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-P</option>, keyboard absent</entry>
+		<entry>serial and internal</entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+      </sect3>
+
+      <sect3>
+	<title>Case 2: You Set the Flags to 0x30 for sio0</title>
+
+	<programlisting>device sio0 at isa? port IO_COM1 flags 0x30 irq 4</programlisting>
+
+	<informaltable frame="none" pgwide="1">
+	  <tgroup cols="4">
+	    <thead>
+	      <row>
+		<entry align="left">Options in /boot.config</entry>
+		<entry align="left">Console during boot blocks</entry>
+		<entry align="left">Console during boot loader</entry>
+		<entry align="left">Console in kernel</entry>
+	      </row>
+	    </thead>
+
+	    <tbody>
+	      <row>
+		<entry>nothing</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-h</option></entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-D</option></entry>
+		<entry>serial and internal</entry>
+		<entry>internal</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-Dh</option></entry>
+		<entry>serial and internal</entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-P</option>, keyboard present</entry>
+		<entry>internal</entry>
+		<entry>internal</entry>
+		<entry>serial</entry>
+	      </row>
+
+	      <row>
+		<entry><option>-P</option>, keyboard absent</entry>
+		<entry>serial and internal</entry>
+		<entry>serial</entry>
+		<entry>serial</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</informaltable>
+      </sect3>
+    </sect2>
+
+    <sect2 id="serialconsole-tips">
+      <title>Tips for the Serial Console</title>
+
+      <sect3>
+	<title>Setting a Faster Serial Port Speed</title>
+
+	<para>By default, the serial port settings are: 9600 baud, 8
+	  bits, no parity, and 1 stop bit.  If you wish to change the speed, you
+	  need to recompile at least the boot blocks.  Add the following line
+	  to <filename>/etc/make.conf</filename> and compile new boot
+	  blocks:</para>
+
+	<programlisting>BOOT_COMCONSOLE_SPEED=19200</programlisting>
+
+	<para>See <xref linkend="serialconsole-com2"> for detailed
+	  instructions about building and installing new boot blocks.</para>
+
+	<para>If the serial console is configured in some other way than by
+	  booting with <option>-h</option>, or if the serial console used by
+	  the kernel is different from the one used by the boot blocks, then
+	  you must also add the following option to the kernel configuration
+	  file and compile a new kernel:</para>
+
+	<programlisting>options CONSPEED=19200</programlisting>
+      </sect3>
+
+      <sect3 id="serialconsole-com2">
+	<title>Using Serial Port Other Than <devicename>sio0</devicename> for
+	  the Console</title>
+
+	<para>Using a port other than <devicename>sio0</devicename> as the
+	  console requires some recompiling.  If you want to use another
+	  serial port for whatever reasons, recompile the boot blocks, the
+	  boot loader and the kernel as follows.</para>
+
+	<procedure>
+	  <step>
+	    <para>Get the kernel source. (See <xref linkend="cutting-edge">)</para>
+	  </step>
+
+	  <step>
+	    <para>Edit <filename>/etc/make.conf</filename> and set
+	      <literal>BOOT_COMCONSOLE_PORT</literal> to the address of the
+	      port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8).  Only
+	      <devicename>sio0</devicename> through
+	      <devicename>sio3</devicename> (<devicename>COM1</devicename>
+	      through <devicename>COM4</devicename>) can be used;  multiport
+	      serial cards will not work.  No interrupt setting is
+	      needed.</para>
+	  </step>
+
+	  <step>
+	    <para>Create a custom kernel configuration file and add
+	      appropriate flags for the serial port you want to use. For
+	      example, if you want to make <devicename>sio1</devicename>
+	      (<devicename>COM2</devicename>) the console:</para>
+
+	    <programlisting>device sio1 at isa? port IO_COM2 flags 0x10 irq 3</programlisting>
+
+	    <para>or</para>
+
+	    <programlisting>device sio1 at isa? port IO_COM2 flags 0x30 irq 3</programlisting>
+
+	    <para>The console flags for the other serial ports should not be
+	      set.</para>
+	  </step>
+
+	  <step>
+	    <para>Recompile and install the boot blocks and the boot loader:</para>
+
+	    <screen>&prompt.root; <userinput>cd /sys/boot</userinput>
+&prompt.root; <userinput>make clean</userinput>
+&prompt.root; <userinput>make</userinput>
+&prompt.root; <userinput>make install</userinput></screen>
+	  </step>
+
+	  <step>
+	    <para>Rebuild and install the kernel.</para>
+	  </step>
+
+	  <step>
+	    <para>Write the boot blocks to the boot disk with
+		&man.bsdlabel.8; and boot from the new kernel.</para>
+	  </step>
+	</procedure>
+      </sect3>
+
+      <sect3 id="serialconsole-ddb">
+	<title>Entering the DDB Debugger from the Serial Line</title>
+
+	<para>If you wish to drop into the kernel debugger from the serial
+	  console (useful for remote diagnostics, but also dangerous if you
+	  generate a spurious BREAK on the serial port!) then you should
+	  compile your kernel with the following options:</para>
+
+	<programlisting>options BREAK_TO_DEBUGGER
+options DDB</programlisting>
+      </sect3>
+
+      <sect3>
+	<title>Getting a Login Prompt on the Serial Console</title>
+
+	<para>While this is not required, you may wish to get a
+	  <emphasis>login</emphasis> prompt over the serial line, now that you
+	  can see boot messages and can enter the kernel debugging session
+	  through the serial console.  Here is how to do it.</para>
+
+	<para>Open the file <filename>/etc/ttys</filename> with an editor
+	  and locate the lines:</para>
+
+      <programlisting>ttyd0 "/usr/libexec/getty std.9600" unknown off secure
+ttyd1 "/usr/libexec/getty std.9600" unknown off secure
+ttyd2 "/usr/libexec/getty std.9600" unknown off secure
+ttyd3 "/usr/libexec/getty std.9600" unknown off secure</programlisting>
+
+	<para><literal>ttyd0</literal> through <literal>ttyd3</literal>
+	  corresponds to <devicename>COM1</devicename> through
+	  <devicename>COM4</devicename>.  Change <literal>off</literal> to
+	  <literal>on</literal> for the desired port.  If you have changed the
+	  speed of the serial port, you need to change
+	  <literal>std.9600</literal> to match the current setting, e.g.
+	  <literal>std.19200</literal>.</para>
+
+	<para>You may also want to change the terminal type from
+	  <literal>unknown</literal> to the actual type of your serial
+	  terminal.</para>
+
+	<para>After editing the file, you must <command>kill -HUP 1</command>
+	  to make this change take effect.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="serialconsole-loader">
+      <title>Changing Console from the Boot Loader</title>
+
+      <para>Previous sections described how to set up the serial console by
+	tweaking the boot block.  This section shows that you can specify the
+	console by entering some commands and environment variables in the
+	boot loader.  As the boot loader is invoked at the third stage of the
+	boot process, after the boot block, the settings in the boot loader
+	will override the settings in the boot block.</para>
+
+      <sect3>
+	<title>Setting Up the Serial Console</title>
+
+	<para>You can easily specify the boot loader and the kernel to use the
+	  serial console by writing just one line in
+	  <filename>/boot/loader.rc</filename>:</para>
+
+	<programlisting>set console="comconsole"</programlisting>
+
+	<para>This will take effect regardless of the settings in the boot
+	  block discussed in the previous section.</para>
+
+	<para>You had better put the above line as the first line of
+	  <filename>/boot/loader.rc</filename> so as to see boot messages  on
+	  the serial console as early as possible.</para>
+
+	<para>Likewise, you can specify the internal console as:</para>
+
+	<programlisting>set console="vidconsole"</programlisting>
+
+	<para>If you do not set the boot loader environment variable
+	  <envar>console</envar>, the boot loader, and subsequently the
+	  kernel, will use whichever console indicated by the
+	  <option>-h</option> option in the  boot block.</para>
+
+	<para>In versions 3.2 or later, you may specify the console in
+	  <filename>/boot/loader.conf.local</filename> or
+	  <filename>/boot/loader.conf</filename>, rather than in
+	  <filename>/boot/loader.rc</filename>.  In this method your
+	  <filename>/boot/loader.rc</filename> should look like:</para>
+
+	<programlisting>include /boot/loader.4th
+start</programlisting>
+
+	<para>Then, create <filename>/boot/loader.conf.local</filename>  and
+	  put the following line there.</para>
+
+	<programlisting>console=comconsole</programlisting>
+
+	<para>or</para>
+
+	<programlisting>console=vidconsole</programlisting>
+
+	<para>See &man.loader.conf.5; for more information.</para>
+
+	<note>
+	  <para>At the moment, the boot loader has no option equivalent to the
+	    <option>-P</option> option in the boot block, and there is no
+	    provision to automatically select the internal console and the
+	    serial console based on the presence of the keyboard.</para>
+	</note>
+      </sect3>
+
+      <sect3>
+	<title>Using a Serial Port Other Than <devicename>sio0</devicename> for
+	  the Console</title>
+
+	<para>You need to recompile the boot loader to use a serial port other
+	  than <devicename>sio0</devicename> for the serial console. Follow the
+	  procedure described in <xref linkend="serialconsole-com2">.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="serialconsole-caveats">
+      <title>Caveats</title>
+
+      <para>The idea here is to allow people to set up dedicated servers  that
+	require no graphics hardware or attached keyboards.  Unfortunately,
+	while most systems will let you boot without a keyboard, there
+	are quite a few that will not let you boot without a graphics adapter.
+	Machines with AMI BIOSes can be configured to  boot with no graphics
+	adapter installed simply by changing the <quote>graphics adapter</quote> setting in
+	the CMOS configuration to <quote>Not installed.</quote></para>
+
+      <para>However, many machines do not support this option and will refuse
+	to boot if you have no display hardware in the system.  With these
+	machines, you will have to leave some kind of graphics card plugged in,
+	(even if it is just a junky mono board) although you will not have to
+	attach a monitor. You might also try installing an AMI
+	BIOS.</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/pl_PL.ISO8859-2/books/handbook/txtfiles.ent b/pl_PL.ISO8859-2/books/handbook/txtfiles.ent
new file mode 100644
index 0000000000..95f9cd9639
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/txtfiles.ent
@@ -0,0 +1,72 @@
+<!-- 
+     Creates entities for each .txt screenshot that is included in the 
+     Handbook.
+
+     Each entity is named txt.dir.foo, where dir is the directory in
+     which it is stored, and foo is its filename, without the '.txt' 
+     extension.
+
+     Entities should be listed in alphabetical order.
+ 
+     $FreeBSD$
+     Original revision: 1.2
+-->
+
+<!ENTITY txt.install.adduser1	 	SYSTEM "install/adduser1.txt">
+<!ENTITY txt.install.adduser2	 	SYSTEM "install/adduser2.txt">
+<!ENTITY txt.install.adduser3	 	SYSTEM "install/adduser3.txt">
+<!ENTITY txt.install.boot-mgr	 	SYSTEM "install/boot-mgr.txt">
+<!ENTITY txt.install.console-saver1	SYSTEM "install/console-saver1.txt">
+<!ENTITY txt.install.console-saver2	SYSTEM "install/console-saver2.txt">
+<!ENTITY txt.install.console-saver3	SYSTEM "install/console-saver3.txt">
+<!ENTITY txt.install.console-saver4	SYSTEM "install/console-saver4.txt">
+<!ENTITY txt.install.desktop	 	SYSTEM "install/desktop.txt">
+<!ENTITY txt.install.disklabel-auto	SYSTEM "install/disklabel-auto.txt">
+<!ENTITY txt.install.disklabel-ed1	SYSTEM "install/disklabel-ed1.txt">
+<!ENTITY txt.install.disklabel-ed2	SYSTEM "install/disklabel-ed2.txt">
+<!ENTITY txt.install.disklabel-fs	SYSTEM "install/disklabel-fs.txt">
+<!ENTITY txt.install.disklabel-root1	SYSTEM "install/disklabel-root1.txt">
+<!ENTITY txt.install.disklabel-root2	SYSTEM "install/disklabel-root2.txt">
+<!ENTITY txt.install.disklabel-root3	SYSTEM "install/disklabel-root3.txt">
+<!ENTITY txt.install.dist-set	 	SYSTEM "install/dist-set.txt">
+<!ENTITY txt.install.dist-set2	 	SYSTEM "install/dist-set2.txt">
+<!ENTITY txt.install.docmenu1	 	SYSTEM "install/docmenu1.txt">
+<!ENTITY txt.install.ed0-conf	 	SYSTEM "install/ed0-conf.txt">
+<!ENTITY txt.install.ed0-conf2	 	SYSTEM "install/ed0-conf2.txt">
+<!ENTITY txt.install.edit-inetd-conf	SYSTEM "install/edit-inetd-conf.txt">
+<!ENTITY txt.install.fdisk-drive1	SYSTEM "install/fdisk-drive1.txt">
+<!ENTITY txt.install.fdisk-drive2	SYSTEM "install/fdisk-drive2.txt">
+<!ENTITY txt.install.fdisk-edit1	SYSTEM "install/fdisk-edit1.txt">
+<!ENTITY txt.install.fdisk-edit2	SYSTEM "install/fdisk-edit2.txt">
+<!ENTITY txt.install.ftp-anon1	 	SYSTEM "install/ftp-anon1.txt">
+<!ENTITY txt.install.ftp-anon2	 	SYSTEM "install/ftp-anon2.txt">
+<!ENTITY txt.install.hdwrconf	 	SYSTEM "install/hdwrconf.txt">
+<!ENTITY txt.install.keymap	 	SYSTEM "install/keymap.txt">
+<!ENTITY txt.install.main-doc	 	SYSTEM "install/main-doc.txt">
+<!ENTITY txt.install.main-keymap	SYSTEM "install/main-keymap.txt">
+<!ENTITY txt.install.main-options	SYSTEM "install/main-options.txt">
+<!ENTITY txt.install.main-std	 	SYSTEM "install/main-std.txt">
+<!ENTITY txt.install.main1	 	SYSTEM "install/main1.txt">
+<!ENTITY txt.install.mainexit	 	SYSTEM "install/mainexit.txt">
+<!ENTITY txt.install.media	 	SYSTEM "install/media.txt">
+<!ENTITY txt.install.mouse1	 	SYSTEM "install/mouse1.txt">
+<!ENTITY txt.install.mouse2	 	SYSTEM "install/mouse2.txt">
+<!ENTITY txt.install.mouse3	 	SYSTEM "install/mouse3.txt">
+<!ENTITY txt.install.mouse4	 	SYSTEM "install/mouse4.txt">
+<!ENTITY txt.install.mouse5	 	SYSTEM "install/mouse5.txt">
+<!ENTITY txt.install.mouse6	 	SYSTEM "install/mouse6.txt">
+<!ENTITY txt.install.nfs-server-edit	SYSTEM "install/nfs-server-edit.txt">
+<!ENTITY txt.install.options	 	SYSTEM "install/options.txt">
+<!ENTITY txt.install.pkg-cat	 	SYSTEM "install/pkg-cat.txt">
+<!ENTITY txt.install.pkg-confirm	SYSTEM "install/pkg-confirm.txt">
+<!ENTITY txt.install.pkg-install	SYSTEM "install/pkg-install.txt">
+<!ENTITY txt.install.pkg-sel	 	SYSTEM "install/pkg-sel.txt">
+<!ENTITY txt.install.probstart	 	SYSTEM "install/probstart.txt">
+<!ENTITY txt.install.security	 	SYSTEM "install/security.txt">
+<!ENTITY txt.install.sysinstall-exit	SYSTEM "install/sysinstall-exit.txt">
+<!ENTITY txt.install.timezone1	 	SYSTEM "install/timezone1.txt">
+<!ENTITY txt.install.timezone2	 	SYSTEM "install/timezone2.txt">
+<!ENTITY txt.install.timezone3	 	SYSTEM "install/timezone3.txt">
+<!ENTITY txt.install.userconfig	 	SYSTEM "../../../share/images/books/handbook/install/userconfig.txt">
+<!ENTITY txt.install.userconfig2	SYSTEM "../../../share/images/books/handbook/install/userconfig2.txt">
+<!ENTITY txt.install.xf86setup	 	SYSTEM "install/xf86setup.txt">
diff --git a/pl_PL.ISO8859-2/books/handbook/users/Makefile b/pl_PL.ISO8859-2/books/handbook/users/Makefile
new file mode 100644
index 0000000000..dfa2918b7b
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/users/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	users/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/users/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/users/chapter.sgml
new file mode 100644
index 0000000000..8b1baf6584
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/users/chapter.sgml
@@ -0,0 +1,1040 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="users">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+        <firstname>Neil</firstname>
+	<surname>Blakey-Milner</surname>
+	<contrib>Contributed by </contrib>
+      </author>
+    </authorgroup>
+    <!-- Feb 2000 -->
+  </chapterinfo>
+
+  <title>Users and Basic Account Management</title>
+  
+  <sect1 id="users-synopsis">
+    <title>Synopsis</title>
+    
+    <para>FreeBSD allows multiple users to use the computer at the same time.
+      Obviously, only one of those users can be sitting in front of the screen and
+      keyboard at any one time
+      <footnote>
+	<para>Well, unless you hook up multiple terminals, but we will
+	save that for <xref linkend="serialcomms">.</para>
+      </footnote>, but any number of users can log in through the
+      network to get their work done.  To use the system every user must have
+      an account.</para>
+    
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The differences between the various user accounts on a FreeBSD
+	  system.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to add user accounts.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to remove user accounts.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to change account details, such as the user's full name, or
+	preferred shell.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to set limits on a per-account basis, to control the
+	  resources such as memory and CPU time that accounts and groups of
+	  accounts are allowed to access.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use groups to make account management easier.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand the basics of &unix; and FreeBSD (<xref
+	    linkend="basics">).</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="users-introduction">
+    <title>Introduction</title>
+
+    <para>All access to the system is achieved via accounts, and all
+      processes are run by users, so user and account management are
+      of integral importance on FreeBSD systems.</para>
+
+    <para>Every account on a FreeBSD system has certain information associated
+      with it to identify the account.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>User name</term>
+
+	<listitem>
+	  <para>The user name as it would be typed at the
+	    <prompt>login:</prompt> prompt.  User names must be unique across
+	    the computer; you may not have two users with the same
+	    user name.  There are a number of rules for creating valid user
+	    names, documented in &man.passwd.5;; you would typically use user
+	    names that consist of eight or fewer all lower case
+	    characters.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Password</term>
+
+	<listitem>
+	  <para>Each account has a password associated with it.  The password
+	    may be blank, in which case no password will be required to access
+	    the system.  This is normally a very bad idea; every account
+	    should have a password.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>User ID (UID)</term>
+
+	<listitem>
+	  <para>The UID is a number, traditionally from 0 to 65535<footnote id="users-largeuidgid">
+	      <para>It is possible to use UID/GIDs as large as
+		4294967295, but such IDs can cause serious problems
+		with software that makes assumptions about the values
+		of IDs.</para>
+	    </footnote>, used to uniquely identify
+	    the user to the system.  Internally, FreeBSD uses the UID to
+	    identify users&mdash;any FreeBSD commands that allow you to
+	    specify a user name will convert it to the UID before working with
+	    it.  This means that you can have several accounts with different
+	    user names but the same UID.  As far as FreeBSD is concerned these
+	    accounts are one user.  It is unlikely you will ever need to do
+	    this.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Group ID (GID)</term>
+
+	<listitem>
+	  <para>The GID is a number, traditionally from 0 to 65535<footnoteref linkend="users-largeuidgid">, used to uniquely identify
+	    the primary group that the user belongs to.  Groups are a
+	    mechanism for controlling access to resources based on a user's
+	    GID rather than their UID.  This can significantly reduce the size
+	    of some configuration files.  A user may also be in more than one
+	    group.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Login class</term>
+
+	<listitem>
+	  <para>Login classes are an extension to the group mechanism that
+	    provide additional flexibility when tailoring the system to
+	    different users.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Password change time</term>
+
+	<listitem>
+	  <para>By default FreeBSD does not force users to change their
+	    passwords periodically.  You can enforce this on a per-user basis,
+	    forcing some or all of your users to change their passwords after
+	    a certain amount of time has elapsed.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Account expiry time</term>
+
+	<listitem>
+	  <para>By default FreeBSD does not expire accounts.  If you are
+	    creating accounts that you know have a limited lifespan, for
+	    example, in a school where you have accounts for the students,
+	    then you can specify when the account expires.  After the expiry
+	    time has elapsed the account cannot be used to log in to the
+	    system, although the account's directories and files will
+	    remain.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>User's full name</term>
+
+	<listitem>
+	  <para>The user name uniquely identifies the account to FreeBSD, but
+	    does not necessarily reflect the user's real name.  This
+	    information can be associated with the account.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>Home directory</term>
+
+	<listitem>
+	  <para>The home directory is the full path to a directory on the
+	    system in which the user will start when logging on to the
+	    system.  A common convention is to put all user home directories
+	    under
+	    <filename>/home/<replaceable>username</replaceable></filename>
+	    or <filename>/usr/home/<replaceable>username</replaceable></filename>.
+	    The user would store their personal files in their home directory,
+	    and any directories they may create in there.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>User shell</term>
+
+	<listitem>
+	  <para>The shell provides the default environment users use to
+	    interact with the system.  There are many different kinds of
+	    shells, and experienced users will have their own preferences,
+	    which can be reflected in their account settings.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>There are three main types of accounts: the <link
+	linkend="users-superuser">Superuser</link>, <link
+	linkend="users-system">system users</link>, and <link
+	linkend="users-user">user accounts</link>.  The Superuser
+      account, usually called <username>root</username>, is used to
+      manage the system with no limitations on privileges.  System
+      users run services.  Finally, user accounts are used by real
+      people, who log on, read mail, and so forth.</para>
+  </sect1>
+    
+  <sect1 id="users-superuser">
+    <title>The Superuser Account</title>
+    
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary>superuser (root)</secondary>
+    </indexterm>
+    <para>The superuser account, usually called
+      <username>root</username>, comes preconfigured to facilitate
+      system administration, and should not be used for day-to-day
+      tasks like sending and receiving mail, general exploration of
+      the system, or programming.</para>
+      
+    <para>This is because the superuser, unlike normal user accounts,
+      can operate without limits, and misuse of the superuser account
+      may result in spectacular disasters.  User accounts are unable
+      to destroy the system by mistake, so it is generally best to use
+      normal user accounts whenever possible, unless you especially
+      need the extra privilege.</para>
+
+    <para>You should always double and triple-check commands you issue
+      as the superuser, since an extra space or missing character can
+      mean irreparable data loss.</para>
+
+    <para>So, the first thing you should do after reading this
+      chapter is to create an unprivileged user account for yourself
+      for general usage if you have not already.  This applies equally
+      whether you are running a multi-user or single-user machine.
+      Later in this chapter, we discuss how to create additional
+      accounts, and how to change between the normal user and
+      superuser.</para>
+  </sect1>
+    
+  <sect1 id="users-system">
+    <title>System Accounts</title>
+
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary>system</secondary>
+    </indexterm>
+    <para>System users are those used to run services such as DNS,
+      mail, web servers, and so forth.  The reason for this is
+      security; if all services ran as the superuser, they could
+      act without restriction.</para>
+
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary><username>daemon</username></secondary>
+    </indexterm>
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary><username>operator</username></secondary>
+    </indexterm>
+    <para>Examples of system users are <username>daemon</username>,
+      <username>operator</username>, <username>bind</username> (for
+      the Domain Name Service), <username>news</username>, and
+      <username>www</username>.</para>
+
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary><username>nobody</username></secondary>
+    </indexterm>
+    <para><username>nobody</username> is the generic unprivileged
+      system user.  However, it is important to keep in mind that the
+      more services that use <username>nobody</username>, the more
+      files and processes that user will become associated with, and
+      hence the more privileged that user becomes.</para>
+  </sect1>
+
+  <sect1 id="users-user">
+    <title>User Accounts</title>
+
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary>user</secondary>
+    </indexterm>
+    <para>User accounts are the primary means of access for real
+      people to the system, and these accounts insulate the user and
+      the environment, preventing the users from damaging the system
+      or other users, and allowing users to customize their
+      environment without affecting others.</para>
+
+    <para>Every person accessing your system should have a unique user
+      account.  This allows you to find out who is doing what, prevent
+      people from clobbering each others' settings or reading each
+      others' mail, and so forth.</para>
+
+    <para>Each user can set up their own environment to accommodate
+      their use of the system, by using alternate shells, editors, key
+      bindings, and language.</para>
+  </sect1>
+
+  <sect1 id="users-modifying">
+    <title>Modifying Accounts</title>
+
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary>modifying</secondary>
+    </indexterm>
+
+    <para>There are a variety of different commands available in the
+      &unix; environment to manipulate user accounts.  The most common
+      commands are summarized below, followed by more detailed
+      examples of their usage.</para>
+
+    <informaltable frame="none" pgwide="1">
+      <tgroup cols="2">
+	<colspec colwidth="1*">
+	<colspec colwidth="2*">
+
+	<thead>
+	  <row>
+	    <entry>Command</entry>
+	    <entry>Summary</entry>
+	  </row>
+	</thead>
+	<tbody>
+	  <row>
+	    <entry>&man.adduser.8;</entry>
+	    <entry>The recommended command-line application for adding
+	    new users.</entry>
+	  </row>
+	  <row>
+	    <entry>&man.rmuser.8;</entry>
+	    <entry>The recommended command-line application for
+	    removing users.</entry>
+	  </row>
+	  <row>
+	    <entry>&man.chpass.1;</entry>
+	    <entry>A flexible tool to change user database information.</entry>
+	  </row>
+	  <row>
+	    <entry>&man.passwd.1;</entry>
+	    <entry>The simple command-line tool to change user
+	    passwords.</entry>
+	  </row>
+	  <row>
+	    <entry>&man.pw.8;</entry>
+	    <entry>A powerful and flexible tool to modify all aspects
+	    of user accounts.</entry>
+	  </row>
+	</tbody>
+      </tgroup>
+    </informaltable>
+
+    <sect2 id="users-adduser">
+      <title><command>adduser</command></title>
+
+      <indexterm>
+        <primary>accounts</primary>
+        <secondary>adding</secondary>
+      </indexterm>
+      <indexterm>
+        <primary><command>adduser</command></primary>
+      </indexterm>
+      <indexterm>
+        <primary><filename class="directory">/usr/share/skel</filename></primary>
+      </indexterm>
+      <indexterm><primary>skeleton directory</primary></indexterm>
+      <para>&man.adduser.8; is a simple program for
+	adding new users.  It creates entries in the system
+	<filename>passwd</filename> and <filename>group</filename>
+	files.  It will also create a home directory for the new user,
+	copy in the default configuration files (<quote>dotfiles</quote>) from
+	<filename>/usr/share/skel</filename>, and can optionally mail
+	the new user a welcome message.</para>
+
+      <note>
+	<para>The password you type in is not echoed, nor are asterisks
+	  displayed.  Make sure that you do not mistype the password.
+	  </para>
+      </note>
+
+      <note>
+	<para>Just use &man.adduser.8; without arguments
+	  from now on, and you will not have to go through changing the
+	  defaults.  If the program asks you to change the defaults,
+	  exit the program, and try the <option>-s</option>
+	  option.</para>
+      </note>
+
+      <example>
+	<title>Adding a user on &os;</title>
+
+	<screen>&prompt.root; <userinput>adduser</userinput>
+Username: <userinput>jru</userinput>
+Full name: <userinput>J. Random User</userinput>
+Uid (Leave empty for default):
+Login group [jru]:
+Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput>
+Login class [default]:
+Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput>
+Home directory [/home/jru]:
+Use password-based authentication? [yes]:
+Use an empty password? (yes/no) [no]:
+Use a random password? (yes/no) [no]:
+Enter password:
+Enter password again:
+Lock out the account after creation? [no]:
+Username   : jru
+Password   : ****
+Full Name  : J. Random User
+Uid        : 1001
+Class      :
+Groups     : jru wheel
+Home       : /home/jru
+Shell      : /usr/local/bin/zsh
+Locked     : no
+OK? (yes/no): <userinput>yes</userinput>
+adduser: INFO: Successfully added (jru) to the user database.
+Add another user? (yes/no): <userinput>no</userinput>
+Goodbye!
+&prompt.root;</screen>
+      </example>
+    </sect2>
+
+    <sect2 id="users-rmuser">
+      <title><command>rmuser</command></title>
+
+      <indexterm><primary><command>rmuser</command></primary></indexterm>
+      <indexterm>
+        <primary>accounts</primary>
+        <secondary>removing</secondary>
+      </indexterm>
+
+      <para>You can use &man.rmuser.8; to
+	completely remove a user from the system.
+	&man.rmuser.8; performs the following
+	steps:</para>
+
+      <procedure>
+	<step>
+	  <para>Removes the user's &man.crontab.1; entry (if
+	    any).</para>
+	</step>
+	<step>
+	  <para>Removes any &man.at.1; jobs belonging to the
+	    user.</para>
+	</step>
+	<step>
+	  <para>Kills all processes owned by the user.</para>
+	</step>
+	<step>
+	  <para>Removes the user from the system's local password
+	    file.</para>
+	</step>
+	<step>
+	  <para>Removes the user's home directory (if it is owned by
+	    the user).</para>
+	</step>
+	<step>
+	  <para>Removes the incoming mail files belonging to the user
+	    from <filename>/var/mail</filename>.</para>
+	</step>
+	<step>
+	  <para>Removes all files owned by the user from temporary
+	    file storage areas such as <filename>/tmp</filename>.</para>
+	</step>
+	<step>
+	  <para>Finally, removes the username from all groups to which
+	    it belongs in <filename>/etc/group</filename>.
+	    
+	    <note>
+	      <para>If a group becomes empty and the group name is the
+		same as the username, the group is removed; this
+		complements the per-user unique groups created by
+		&man.adduser.8;.</para>
+	    </note>
+	  </para>
+	</step>
+      </procedure>
+
+      <para>&man.rmuser.8; cannot be used to remove
+	superuser accounts, since that is almost always an indication
+	of massive destruction.</para>
+
+      <para>By default, an interactive mode is used, which attempts to
+	make sure you know what you are doing.</para>
+
+      <example>
+	<title><command>rmuser</command> Interactive Account Removal</title>
+
+	<screen>&prompt.root; <userinput>rmuser jru</userinput>
+Matching password entry:
+jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
+Is this the entry you wish to remove? <userinput>y</userinput>
+Remove user's home directory (/home/jru)? <userinput>y</userinput>
+Updating password file, updating databases, done.
+Updating group file: trusted (removing group jru -- personal group is empty) done.
+Removing user's incoming mail file /var/mail/jru: done.
+Removing files belonging to jru from /tmp: done.
+Removing files belonging to jru from /var/tmp: done.
+Removing files belonging to jru from /var/tmp/vi.recover: done.
+&prompt.root;</screen>
+      </example>
+    </sect2>
+
+    <sect2 id="users-chpass">
+      <title><command>chpass</command></title>
+
+      <indexterm><primary><command>chpass</command></primary></indexterm>
+      <para>&man.chpass.1; changes user database
+	information such as passwords, shells, and personal
+	information.</para>
+
+      <para>Only system administrators, as the superuser, may change
+	other users' information and passwords with 
+	&man.chpass.1;.</para>
+
+      <para>When passed no options, aside from an optional username,
+	&man.chpass.1; displays an editor
+	containing user information.  When the user exists from the
+	editor, the user database is updated with the new
+	information.</para>
+
+      <note>
+	<para>You will be asked for your password
+	 after exiting the editor if you are not the superuser.</para>
+      </note>
+
+      <example>
+	<title>Interactive <command>chpass</command> by Superuser</title>
+
+	<screen>#Changing user database information for jru.
+Login: jru
+Password: *
+Uid [#]: 1001
+Gid [# or name]: 1001
+Change [month day year]:
+Expire [month day year]:
+Class:
+Home directory: /home/jru
+Shell: /usr/local/bin/zsh
+Full Name: J. Random User
+Office Location:
+Office Phone:
+Home Phone:
+Other information:</screen>
+      </example>
+
+      <para>The normal user can change only a small subset of this
+	information, and only for themselves.</para>
+
+      <example>
+	<title>Interactive <command>chpass</command> by Normal User</title>
+
+	<screen>#Changing user database information for jru.
+Shell: /usr/local/bin/zsh
+Full Name: J. Random User
+Office Location:
+Office Phone:
+Home Phone:
+Other information:</screen>
+      </example>
+
+      <note>
+	<para>&man.chfn.1; and &man.chsh.1; are
+	  just links to &man.chpass.1;, as 
+	  are &man.ypchpass.1;,
+	  &man.ypchfn.1;, and
+	  &man.ypchsh.1;.  NIS support is automatic, so
+	  specifying the <literal>yp</literal> before the command is
+	  not necessary.  If this is confusing to you, do not worry, NIS will
+	  be covered in <xref linkend="network-servers">.</para>
+      </note>
+    </sect2>
+    <sect2 id="users-passwd">
+      <title><command>passwd</command></title>
+
+      <indexterm><primary><command>passwd</command></primary></indexterm>
+      <indexterm>
+        <primary>accounts</primary>
+        <secondary>changing password</secondary>
+      </indexterm>
+      <para>&man.passwd.1; is the usual way to
+	change your own password as a user, or another user's password
+	as the superuser.</para>
+
+      <note>
+	<para>To prevent accidental or unauthorized changes, the original
+	  password must be entered before a new password can be set.</para>
+      </note>
+
+      <example>
+	<title>Changing Your Password</title>
+
+	<screen>&prompt.user; <userinput>passwd</userinput>
+Changing local password for jru.
+Old password:
+New password:
+Retype new password:
+passwd: updating the database...
+passwd: done</screen>
+      </example>
+
+      <example>
+	<title>Changing Another User's Password as the Superuser</title>
+
+        <screen>&prompt.root; <userinput>passwd jru</userinput>
+Changing local password for jru.
+New password:
+Retype new password:
+passwd: updating the database...
+passwd: done</screen>
+      </example>
+
+      <note>
+	<para>As with &man.chpass.1;,
+	  &man.yppasswd.1; is just a link to
+	  &man.passwd.1;, so NIS works with either
+	  command.</para>
+      </note>
+    </sect2>
+
+
+    <sect2 id="users-pw">
+      <title><command>pw</command></title>
+      <indexterm><primary><command>pw</command></primary></indexterm>
+
+      <para>&man.pw.8; is a command line utility to create, remove,
+	modify, and display users and groups.  It functions as a front
+	end to the system user and group files.  &man.pw.8;
+	has a very powerful set of command line options that make it
+	suitable for use in shell scripts, but new users may find it
+	more complicated than the other commands presented
+	here.</para>
+    </sect2>
+
+
+  </sect1>
+
+  <sect1 id="users-limiting">
+    <title>Limiting Users</title>
+
+    <indexterm><primary>limiting users</primary></indexterm>
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary>limiting</secondary>
+    </indexterm>
+    <para>If you have users, the ability to limit their system use may
+      have come to mind.  FreeBSD provides
+      several ways an administrator can limit the amount of system
+      resources an individual may use.  These limits are
+      divided into two sections: disk quotas, and other resource
+      limits.</para>
+
+    <indexterm><primary>quotas</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>quotas</secondary>
+    </indexterm>
+    <indexterm><primary>disk quotas</primary></indexterm>
+    <para>Disk quotas limit disk usage to users, and
+      they
+      provide a way to quickly check that usage without
+      calculating it every time.  Quotas are discussed in <xref
+      linkend="quotas">.</para>
+
+    <para>The other resource limits include ways to limit the amount of
+      CPU, memory, and other resources a user may consume.  These are
+      defined using login classes and are discussed here.</para>
+
+    <indexterm>
+      <primary><filename>/etc/login.conf</filename></primary>
+    </indexterm>
+    <para>Login classes are defined in
+      <filename>/etc/login.conf</filename>.  The precise semantics are
+      beyond the scope of this section, but are described in detail in the
+      &man.login.conf.5; manual page.  It is sufficient to say that each
+      user is assigned to a login class (<literal>default</literal> by
+      default), and that each login class has a set of login capabilities
+      associated with it.  A login capability is a
+      <literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal>
+      pair, where <replaceable>name</replaceable> is a well-known
+      identifier and <replaceable>value</replaceable> is an arbitrary
+      string processed accordingly depending on the name.  Setting up login
+      classes and capabilities is rather straight-forward and is also
+      described in &man.login.conf.5;.</para>
+      
+    <note>
+      <para>The system does not normally read the configuration in
+	<filename>/etc/login.conf</filename> directly, but reads the database
+	file <filename>/etc/login.conf.db</filename> which provides
+	faster lookups.
+	To generate <filename>/etc/login.conf.db</filename> from
+	<filename>/etc/login.conf</filename>, execute the following
+	command:</para>
+
+      <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
+    </note>
+
+    <para>Resource limits are different from plain vanilla login
+      capabilities in two ways.  First, for every limit, there is a soft
+      (current) and hard limit.  A soft limit may be adjusted by the user
+      or application, but may be no higher than the hard limit.  The latter
+      may be lowered by the user, but never raised.  Second, most resource
+      limits apply per process to a specific user, not the user as a whole.
+      Note, however, that these differences are mandated by the specific
+      handling of the limits, not by the implementation of the login
+      capability framework (i.e., they are not <emphasis>really</emphasis>
+      a special case of login capabilities).</para>
+
+    <para>And so, without further ado, below are the most commonly used
+      resource limits (the rest, along with all the other login
+      capabilities, may be found in &man.login.conf.5;).</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><literal>coredumpsize</literal></term>
+
+	<listitem>
+    <indexterm><primary>coredumpsize</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>coredumpsize</secondary>
+    </indexterm>
+	  <para>The limit on the size of a core file generated by a program
+	  is, for obvious reasons, subordinate to other limits on disk
+	  usage (e.g., <literal>filesize</literal>, or disk quotas).
+	  Nevertheless, it is often used as a less-severe method of
+	  controlling disk space consumption: since users do not generate
+	  core files themselves, and often do not delete them, setting this
+	  may save them from running out of disk space should a large
+	  program (e.g., <application>emacs</application>) crash.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>cputime</literal></term>
+
+	<listitem>
+    <indexterm><primary>cputime</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>cputime</secondary>
+    </indexterm>
+	  <para>This is the maximum amount of CPU time a user's process may
+	    consume.  Offending processes will be killed by the kernel.
+
+	    <note>
+	      <para>This is a limit on CPU <emphasis>time</emphasis>
+	        consumed, not percentage of the CPU as displayed in some
+	        fields by &man.top.1; and &man.ps.1;.  A limit on the
+	        latter is, at the time of this writing, not possible, and
+	        would be rather useless: a compiler&mdash;probably a
+	        legitimate task&mdash;can easily use almost 100% of a CPU
+	        for some time.</para>
+	    </note>
+	  </para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>filesize</literal></term>
+
+	<listitem>
+    <indexterm><primary>filesize</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>filesize</secondary>
+    </indexterm>
+	  <para>This is the maximum size of a file the user may possess.
+	    Unlike <link linkend="quotas">disk quotas</link>, this limit is
+	    enforced on individual files, not the set of all files a user
+	    owns.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>maxproc</literal></term>
+
+	<listitem>
+    <indexterm><primary>maxproc</primary></indexterm>
+        <indexterm>
+      <primary>limiting users</primary>
+      <secondary>maxproc</secondary>
+    </indexterm>
+	  <para>This is the maximum number of processes a user may be
+	    running.  This includes foreground and background processes
+	    alike.  For obvious reasons, this may not be larger than the
+	    system limit specified by the <varname>kern.maxproc</varname>
+	    &man.sysctl.8;.  Also note that setting this 
+	    too small may hinder a
+	    user's productivity: it is often useful to be logged in
+	    multiple times or execute pipelines.  Some tasks, such as
+	    compiling a large program, also spawn multiple processes (e.g.,
+	    &man.make.1;, &man.cc.1;, and other intermediate
+	    preprocessors).</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>memorylocked</literal></term>
+
+	<listitem>
+    <indexterm><primary>memorylocked</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>memorylocked</secondary>
+    </indexterm>
+	  <para>This is the maximum amount a memory a process may have
+	    requested to be locked into main memory (e.g., see
+	    &man.mlock.2;).  Some system-critical programs, such as
+            &man.amd.8;, lock into main memory such that in the event
+	    of being swapped out, they do not contribute to
+	    a system's trashing in time of trouble.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>memoryuse</literal></term>
+
+	<listitem>
+    <indexterm><primary>memoryuse</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>memoryuse</secondary>
+    </indexterm>
+	  <para>This is the maximum amount of memory a process may consume
+	    at any given time.  It includes both core memory and swap
+	    usage.  This is not a catch-all limit for restricting memory
+	    consumption, but it is a good start.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>openfiles</literal></term>
+
+	<listitem>
+    <indexterm><primary>openfiles</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>openfiles</secondary>
+    </indexterm>
+	  <para>This is the maximum amount of files a process may have
+	    open.  In FreeBSD, files are also used to represent sockets and
+	    IPC channels; thus, be careful not to set this too low.  The
+	    system-wide limit for this is defined by the
+	    <varname>kern.maxfiles</varname> &man.sysctl.8;.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>sbsize</literal></term>
+
+	<listitem>
+    <indexterm><primary>sbsize</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>sbsize</secondary>
+    </indexterm>
+	  <para>This is the limit on the amount of network memory, and thus
+	    mbufs, a user may consume.  This originated as a response to an
+	    old DoS attack by creating a lot of sockets, but can be
+	    generally used to limit network communications.</para>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><literal>stacksize</literal></term>
+
+	<listitem>
+    <indexterm><primary>stacksize</primary></indexterm>
+    <indexterm>
+      <primary>limiting users</primary>
+      <secondary>stacksize</secondary>
+    </indexterm>
+	  <para>This is the maximum size a process' stack may grow to.
+	    This alone is not sufficient to limit the amount of memory a
+	    program may use; consequently, it should be used in conjunction
+	    with other limits.</para>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>There are a few other things to remember when setting resource
+      limits.  Following are some general tips, suggestions, and
+      miscellaneous comments.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Processes started at system startup by
+          <filename>/etc/rc</filename> are assigned to the
+          <literal>daemon</literal> login class.</para>
+      </listitem>
+
+      <listitem>
+        <para>Although the <filename>/etc/login.conf</filename> that comes
+          with the system is a good source of reasonable values for most
+          limits, only you, the administrator, can know what is appropriate
+          for your system.  Setting a limit too high may open your system
+          up to abuse, while setting it too low may put a strain on
+          productivity.</para>
+      </listitem>
+
+      <listitem>
+        <para>Users of the X Window System (X11) should probably be granted
+	  more resources than other users.  X11 by itself takes a lot of
+	  resources, but it also encourages users to run more programs
+	  simultaneously.</para>
+      </listitem>
+
+      <listitem>
+        <para>Remember that many limits apply to individual processes, not
+          the user as a whole.  For example, setting 
+	  <varname>openfiles</varname> to 50 means
+          that each process the user runs may open up to 50 files.  Thus,
+          the gross amount of files a user may open is the value of
+          <literal>openfiles</literal> multiplied by the value of
+          <literal>maxproc</literal>.  This also applies to memory
+          consumption.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>For further information on resource limits and login classes and
+      capabilities in general, please consult the relevant manual pages:
+      &man.cap.mkdb.1;, &man.getrlimit.2;, &man.login.conf.5;.</para>
+  </sect1>
+
+  <sect1 id="users-groups">
+    <title>Groups</title>
+
+    <indexterm><primary>groups</primary></indexterm>
+    <indexterm>
+      <primary><filename>/etc/groups</filename></primary>
+    </indexterm>
+    <indexterm>
+      <primary>accounts</primary>
+      <secondary>groups</secondary>
+    </indexterm>
+    <para>A group is simply a list of users.  Groups are identified by
+      their group name and GID (Group ID).  In FreeBSD (and most other &unix; like
+      systems), the two factors the kernel uses to decide whether a process
+      is allowed to do something is its user ID and list of groups it
+      belongs to.  Unlike a user ID, a process has a list of groups
+      associated with it.  You may hear some things refer to the <quote>group ID</quote>
+      of a user or process; most of the time, this just means the first
+      group in the list.</para>
+
+    <para>The group name to group ID map is in
+      <filename>/etc/group</filename>.  This is a plain text file with four
+      colon-delimited fields.  The first field is the group name, the
+      second is the encrypted password, the third the group ID, and the
+      fourth the comma-delimited list of members.  It can safely be edited
+      by hand (assuming, of course, that you do not make any syntax
+      errors!).  For a more complete description of the syntax, see the
+      &man.group.5; manual page.</para>
+
+    <para>If you do not want to edit <filename>/etc/group</filename>
+      manually, you can use the &man.pw.8; command to add and edit groups.
+      For example, to add a group called <groupname>teamtwo</groupname> and
+      then confirm that it exists you can use:</para>
+
+    <example>
+      <title>Adding a Group Using &man.pw.8;</title>
+
+      <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:</screen>
+    </example>
+
+    <para>The number <literal>1100</literal> above is the group ID of the
+      group <groupname>teamtwo</groupname>.  Right now,
+      <groupname>teamtwo</groupname> has no members, and is thus rather
+      useless.  Let's change that by inviting <username>jru</username> to
+      the <groupname>teamtwo</groupname> group.</para>
+
+    <example>
+      <title>Adding Somebody to a Group Using &man.pw.8;</title>
+
+      <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:jru</screen>
+    </example>
+
+    <para>The argument to the <option>-M</option> option is a
+      comma-delimited list of users who are members of the group.  From the
+      preceding sections, we know that the password file also contains a
+      group for each user.  The latter (the user) is automatically added to
+      the group list by the system; the user will not show up as a member
+      when using the <option>groupshow</option> command to &man.pw.8;,
+      but will show up when the information is queried via &man.id.1; or
+      similar tool.  In other words, &man.pw.8; only manipulates the
+      <filename>/etc/group</filename> file; it will never attempt to read
+      additionally data from <filename>/etc/passwd</filename>.</para>
+
+    <example>
+      <title>Using &man.id.1; to Determine Group Membership</title>
+
+      <screen>&prompt.user; <userinput>id jru</userinput>
+uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen>
+    </example>
+
+    <para>As you can see, <username>jru</username> is a member of the
+      groups <groupname>jru</groupname> and
+      <groupname>teamtwo</groupname>.</para>
+
+    <para>For more information about &man.pw.8;, see its manual page, and
+      for more information on the format of
+      <filename>/etc/group</filename>, consult the &man.group.5; manual
+      page.</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/pl_PL.ISO8859-2/books/handbook/vinum/Makefile b/pl_PL.ISO8859-2/books/handbook/vinum/Makefile
new file mode 100644
index 0000000000..eca585a9aa
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/vinum/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	vinum/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/vinum/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/vinum/chapter.sgml
new file mode 100644
index 0000000000..c3224799c8
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/vinum/chapter.sgml
@@ -0,0 +1,1449 @@
+<!--
+	The Vinum Volume Manager
+	By Greg Lehey (grog at lemis dot com)
+
+	Added to the Handbook by Hiten Pandya <hmp@FreeBSD.org>
+	and Tom Rhodes <trhodes@FreeBSD.org>
+
+	For the FreeBSD Documentation Project
+	$FreeBSD$
+-->
+
+<chapter id="vinum-vinum">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Greg</firstname>
+	<surname>Lehey</surname>
+	<contrib>Originally written by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>The Vinum Volume Manager</title>
+  
+  <sect1 id="vinum-synopsis">
+    <title>Synopsis</title>
+
+
+<para>No matter what disks you have, there are always potential problems:</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>
+
+<para>One way some users safeguard themselves against such issues is
+through the use of multiple, and sometimes redundant, disks.</para>
+
+<para>In addition to supporting various cards and controllers for hardware
+RAID systems, the base FreeBSD system includes the Vinum Volume Manager,
+a block device driver that implements virtual disk drives.</para>
+
+<para>Vinum provides more flexibility, performance, and reliability than
+traditional disk storage, and implements RAID-0, RAID-1, and RAID-5
+models both individually and in combination.</para>
+
+<para>This chapter provides an overview of potential problems with traditional
+disk storage, and an introduction to the Vinum Volume Manager.</para>
+
+    <note><para>Starting with FreeBSD 5, Vinum has been rewritten in
+    order to fit into the GEOM architecture (<xref linkend="GEOM">),
+    retaining the original ideas, terminology, and on-disk metadata.
+    This rewrite is called <emphasis>gvinum</emphasis> (for <emphasis>
+    GEOM vinum</emphasis>).  The following text usually refers to
+    <emphasis>Vinum</emphasis> as an abstract name, regardless of the
+    implementation variant.  Any command invocations should now be
+    done using the <command>gvinum</command> command, and the name of
+    the kernel module has been changed from
+    <filename>vinum.ko</filename> to
+    <filename>geom_vinum.ko</filename>, and all device nodes reside
+    under <filename>/dev/gvinum</filename> instead of
+    <filename>/dev/vinum</filename>.  As of FreeBSD 6, the old Vinum
+    implementation is no longer available in the code
+    base.</para></note>
+
+  </sect1>
+
+  <sect1 id="vinum-intro">
+    <title>Disks Are Too Small</title>
+
+    <indexterm><primary>Vinum</primary></indexterm>
+    <indexterm><primary>RAID</primary>
+    <secondary>software</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 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>disk concatenation</primary>
+    </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>disk striping</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Vinum</primary>
+      <secondary>striping</secondary>
+    </indexterm>
+    <indexterm>
+      <primary>RAID</primary>
+    </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>
+      <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 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>disk mirroring</primary>
+      </indexterm>
+      <indexterm>
+	<primary>Vinum</primary>
+	<secondary>mirroring</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; 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; disk storage
+	    framework, it would be possible to use &unix;
+	    partitions as the building block for multi-disk plexes,
+	    but in fact this turns out to be too inflexible:
+	    &unix; disks can have only a limited number of
+	    partitions.  Instead, Vinum subdivides a single
+	    &unix; 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; 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" frame="none">
+	<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.gvinum.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.gvinum.8; produces the following
+	output:</para>
+
+      <programlisting width="97">
+      &prompt.root; gvinum -&gt; <userinput>create config1</userinput>
+      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.gvinum.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 width="97">
+	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 width="92">
+	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; 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 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>Vinum objects are assigned device nodes in the hierarchy
+      <filename>/dev/gvinum</filename>.  The configuration shown above
+      would cause Vinum to create the following device nodes:</para>
+
+    <itemizedlist>
+      <listitem>
+        <note><para>This only applies to the historic Vinum
+	implemenation.</para></note>
+
+	<para>The control devices
+	  <filename>/dev/vinum/control</filename> and
+	  <filename>/dev/vinum/controld</filename>, which are used
+	  by &man.gvinum.8; and the Vinum daemon respectively.</para>
+      </listitem>
+
+      <listitem>
+	<para>Device entries for each volume.
+	  These are the main devices used by Vinum.  Thus the configuration
+	  above would include the devices
+	  <filename>/dev/gvinum/myvol</filename>,
+	  <filename>/dev/gvinum/mirror</filename>,
+	  <filename>/dev/gvinum/striped</filename>,
+	  <filename>/dev/gvinum/raid5</filename> and
+	  <filename>/dev/gvinum/raid10</filename>.</para>
+      </listitem>
+
+      <listitem>
+        <note><para>This only applies to the historic Vinum
+	implemenation.</para></note>
+
+	<para>A directory <filename>/dev/vinum/drive</filename>
+	  with entries for each drive.  These entries are in fact
+	  symbolic links to the corresponding disk nodes.</para>
+      </listitem>
+
+      <listitem>
+	<para>All volumes get direct entries under
+	  <filename>/dev/gvinum/</filename>.</para>
+      </listitem>
+
+      <listitem>
+	<para>The directories
+	  <filename>/dev/gvinum/plex</filename>, and
+	  <filename>/dev/gvinum/sd</filename>, which contain
+	  device nodes for each plex and for each subdisk,
+	  respectively.</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.gvinum.8; creates the following
+      structure in <filename>/dev/gvinum</filename>:</para>
+
+    <programlisting>
+	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 plex
+	crwxr-xr--  1 root  wheel   91,   2 Apr 13 16:46 s64
+	drwxr-xr-x  2 root  wheel       512 Apr 13 16:46 sd
+
+    /dev/vinum/plex:
+    total 0
+    crwxr-xr--  1 root  wheel   25, 0x10000002 Apr 13 16:46 s64.p0
+    
+    /dev/vinum/sd:
+    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</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; 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 <filename>/dev/ad0a</filename> or
+	  <filename>/dev/da2h</filename>.  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
+	  <filename>/dev/gvinum/concat</filename>, 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/gvinum/concat</userinput>
+newfs: /dev/gvinum/concat: can't figure out file system partition</screen>
+
+	<para>In order to create a file system on this volume, use
+	  &man.newfs.8;:</para>
+
+	<screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput></screen>
+
+	<note><para>On &os; versions prior to 5.0 &man.newfs.8; requires
+	    an additional -v flag and the old device naming
+	    scheme:</para></note>
+
+	<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.gvinum.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 width="119">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; drive
+	  IDs.</para>
+  
+      <sect3 id="vinum-rc-startup">
+	<title>Automatic Startup</title>
+
+	<note><para>This information only relates to the historic
+	Vinum implementation.  <emphasis>Gvinum</emphasis> always
+	features an automatic startup once the kernel module is
+	loaded.</para></note>
+
+        <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>
+
+  <sect1 id="vinum-root">
+    <title>Using Vinum for the Root Filesystem</title>
+
+    <para>For a machine that has fully-mirrored filesystems using
+      Vinum, it is desirable to also mirror the root filesystem.
+      Setting up such a configuration is less trivial than mirroring
+      an arbitrary filesystem because:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>The root filesystem must be available very early during
+	  the boot process, so the Vinum infrastructure must already be
+	  available at this time.</para>
+      </listitem>
+      <listitem>
+	<para>The volume containing the root filesystem also contains
+	  the system bootstrap and the kernel, which must be read
+	  using the host system's native utilities (e. g. the BIOS on
+	  PC-class machines) which often cannot be taught about the
+	  details of Vinum.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>In the following sections, the term <quote>root
+      volume</quote> is generally used to describe the Vinum volume
+      that contains the root filesystem.  It is probably a good idea
+      to use the name <literal>"root"</literal> for this volume, but
+      this is not technically required in any way.  All command
+      examples in the following sections assume this name though.</para>
+
+    <sect2>
+      <title>Starting up Vinum Early Enough for the Root
+	Filesystem</title>
+
+      <para>There are several measures to take for this to
+	happen:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>Vinum must be available in the kernel at boot-time.
+	    Thus, the method to start Vinum automatically described in
+	    <xref linkend="vinum-rc-startup"> is not applicable to
+	    accomplish this task, and the
+	    <literal>start_vinum</literal> parameter must actually
+	    <emphasis>not</emphasis> be set when the following setup
+	    is being arranged.	The first option would be to compile
+	    Vinum statically into the kernel, so it is available all
+	    the time, but this is usually not desirable.  There is
+	    another option as well, to have
+	    <filename>/boot/loader</filename> (<xref
+	    linkend="boot-loader">) load the vinum kernel module
+	    early, before starting the kernel.	This can be
+	    accomplished by putting the line:</para>
+
+	  <programlisting>geom_vinum_load="YES"</programlisting>
+
+	  <para>into the file
+	    <filename>/boot/loader.conf</filename>.</para>
+	</listitem>
+
+	<listitem>
+	  <note><para>For <emphasis>Gvinum</emphasis>, all startup
+	  is done automatically once the kernel module has been
+	  loaded, so the procedure described above is all that is
+	  needed.  The following text documents the behaviour of
+	  the historic Vinum system, for the sake of older
+	  setups.</para></note>
+
+	  <para>Vinum must be initialized early since it needs to
+	    supply the volume for the root filesystem.	By default,
+	    the Vinum kernel part is not looking for drives that might
+	    contain Vinum volume information until the administrator
+	    (or one of the startup scripts) issues a <command>vinum
+	    start</command> command.</para>
+
+	  <note><para>The following paragraphs are outlining the steps
+	    needed for FreeBSD 5.X and above.  The setup required for
+	    FreeBSD 4.X differs, and is described below in <xref
+	    linkend="vinum-root-4x">.</para></note>
+
+	  <para>By placing the line:</para>
+
+	  <programlisting>vinum.autostart="YES"</programlisting>
+
+	  <para>into <filename>/boot/loader.conf</filename>, Vinum is
+	    instructed to automatically scan all drives for Vinum
+	    information as part of the kernel startup.</para>
+
+	  <para>Note that it is not necessary to instruct the kernel
+	    where to look for the root filesystem.
+	    <filename>/boot/loader</filename> looks up the name of the
+	    root device in <filename>/etc/fstab</filename>, and passes
+	    this information on to the kernel.	When it comes to mount
+	    the root filesystem, the kernel figures out from the
+	    device name provided which driver to ask to translate this
+	    into the internal device ID (major/minor number).</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Making a Vinum-based Root Volume Accessible to the
+	Bootstrap</title>
+
+      <para>Since the current FreeBSD bootstrap is only 7.5 KB of
+	code, and already has the burden of reading files (like
+	<filename>/boot/loader</filename>) from the UFS filesystem, it
+	is sheer impossible to also teach it about internal Vinum
+	structures so it could parse the Vinum configuration data, and
+	figure out about the elements of a boot volume itself.	Thus,
+	some tricks are necessary to provide the bootstrap code with
+	the illusion of a standard <literal>"a"</literal> partition
+	that contains the root filesystem.</para>
+
+      <para>For this to be possible at all, the following requirements
+	must be met for the root volume:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>The root volume must not be striped or RAID-5.</para>
+	</listitem>
+
+	<listitem>
+	  <para>The root volume must not contain more than one
+	    concatenated subdisk per plex.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Note that it is desirable and possible that there are
+	multiple plexes, each containing one replica of the root
+	filesystem.  The bootstrap process will, however, only use one
+	of these replica for finding the bootstrap and all the files,
+	until the kernel will eventually mount the root filesystem
+	itself.	 Each single subdisk within these plexes will then
+	need its own <literal>"a"</literal> partition illusion, for
+	the respective device to become bootable.  It is not strictly
+	needed that each of these faked <literal>"a"</literal>
+	partitions is located at the same offset within its device,
+	compared with other devices containing plexes of the root
+	volume.	 However, it is probably a good idea to create the
+	Vinum volumes that way so the resulting mirrored devices are
+	symmetric, to avoid confusion.</para>
+
+      <para>In order to set up these <literal>"a"</literal> partitions,
+	for each device containing part of the root volume, the
+	following needs to be done:</para>
+
+      <procedure>
+	<step>
+	  <para>The location (offset from the beginning of the device)
+	    and size of this device's subdisk that is part of the root
+	    volume need to be examined, using the command:</para>
+
+	  <screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen>
+
+	  <para>Note that Vinum offsets and sizes are measured in
+	    bytes.  They must be divided by 512 in order to obtain the
+	    block numbers that are to be used in the
+	    <command>bsdlabel</command> command.</para>
+	</step>
+
+	<step>
+	  <para>Run the command:</para>
+
+	  <screen>&prompt.root; <userinput>bsdlabel -e <replaceable>devname</replaceable></userinput></screen>
+
+	  <para>for each device that participates in the root volume.
+	    <replaceable>devname</replaceable> must be either the name
+	    of the disk (like <devicename>da0</devicename>) for disks
+	    without a slice (aka. fdisk) table, or the name of the
+	    slice (like <devicename>ad0s1</devicename>).</para>
+
+	  <para>If there is already an <literal>"a"</literal>
+	    partition on the device (presumably, containing a
+	    pre-Vinum root filesystem), it should be renamed to
+	    something else, so it remains accessible (just in case),
+	    but will no longer be used by default to bootstrap the
+	    system.  Note that active partitions (like a root
+	    filesystem currently mounted) cannot be renamed, so this
+	    must be executed either when being booted from a
+	    <quote>Fixit</quote> medium, or in a two-step process,
+	    where (in a mirrored situation) the disk that has not been
+	    currently booted is being manipulated first.</para>
+
+	  <para>Then, the offset the Vinum partition on this
+	    device (if any) must be added to the offset of the
+	    respective root volume subdisk on this device.  The
+	    resulting value will become the
+	    <literal>"offset"</literal> value for the new
+	    <literal>"a"</literal> partition.  The
+	    <literal>"size"</literal> value for this partition can be
+	    taken verbatim from the calculation above.	The
+	    <literal>"fstype"</literal> should be
+	    <literal>4.2BSD</literal>.	The
+	    <literal>"fsize"</literal>, <literal>"bsize"</literal>,
+	    and <literal>"cpg"</literal> values should best be chosen
+	    to match the actual filesystem, though they are fairly
+	    unimportant within this context.</para>
+
+	  <para>That way, a new <literal>"a"</literal> partition will
+	    be established that overlaps the Vinum partition on this
+	    device.  Note that the <command>bsdlabel</command> will
+	    only allow for this overlap if the Vinum partition has
+	    properly been marked using the <literal>"vinum"</literal>
+	    fstype.</para>
+	</step>
+
+	<step>
+	  <para>That's all!  A faked <literal>"a"</literal> partition
+	    does exist now on each device that has one replica of the
+	    root volume.  It is highly recommendable to verify the
+	    result again, using a command like:</para>
+
+	  <screen>&prompt.root; <userinput>fsck -n /dev/<replaceable>devname</replaceable>a</userinput></screen>
+	</step>
+      </procedure>
+
+      <para>It should be remembered that all files containing control
+	information must be relative to the root filesystem in the
+	Vinum volume which, when setting up a new Vinum root volume,
+	might not match the root filesystem that is currently active.
+	So in particular, the files <filename>/etc/fstab</filename>
+	and <filename>/boot/loader.conf</filename> need to be taken
+	care of.</para>
+
+      <para>At next reboot, the bootstrap should figure out the
+	appropriate control information from the new Vinum-based root
+	filesystem, and act accordingly.  At the end of the kernel
+	initialization process, after all devices have been announced,
+	the prominent notice that shows the success of this setup is a
+	message like:</para>
+
+      <screen>Mounting root from ufs:/dev/gvinum/root</screen>
+    </sect2>
+
+    <sect2>
+      <title>Example of a Vinum-based Root Setup</title>
+
+      <para>After the Vinum root volume has been set up, the output of
+	<command>gvinum l -rv root</command> could look like:</para>
+
+	<screen>
+...
+Subdisk root.p0.s0:
+		Size:        125829120 bytes (120 MB)
+		State: up
+		Plex root.p0 at offset 0 (0  B)
+		Drive disk0 (/dev/da0h) at offset 135680 (132 kB)
+
+Subdisk root.p1.s0:
+		Size:        125829120 bytes (120 MB)
+		State: up
+		Plex root.p1 at offset 0 (0  B)
+		Drive disk1 (/dev/da1h) at offset 135680 (132 kB)
+	</screen>
+
+      <para>The values to note are <literal>135680</literal> for the
+	offset (relative to partition
+	<filename>/dev/da0h</filename>).  This translates to 265
+	512-byte disk blocks in <command>bsdlabel</command>'s terms.
+	Likewise, the size of this root volume is 245760 512-byte
+	blocks.	 <filename>/dev/da1h</filename>, containing the
+	second replica of this root volume, has a symmetric
+	setup.</para>
+
+      <para>The bsdlabel for these devices might look like:</para>
+
+	<screen>
+...
+8 partitions:
+#        size   offset    fstype   [fsize bsize bps/cpg]
+  a:   245760      281    4.2BSD     2048 16384     0   # (Cyl.    0*- 15*)
+  c: 71771688        0    unused        0     0         # (Cyl.    0 - 4467*)
+  h: 71771672       16     vinum                        # (Cyl.    0*- 4467*)
+	</screen>
+
+      <para>It can be observed that the <literal>"size"</literal>
+	parameter for the faked <literal>"a"</literal> partition
+	matches the value outlined above, while the
+	<literal>"offset"</literal> parameter is the sum of the offset
+	within the Vinum partition <literal>"h"</literal>, and the
+	offset of this partition within the device (or slice).	This
+	is a typical setup that is necessary to avoid the problem
+	described in <xref linkend="vinum-root-panic">.	 It can also
+	be seen that the entire <literal>"a"</literal> partition is
+	completely within the <literal>"h"</literal> partition
+	containing all the Vinum data for this device.</para>
+
+      <para>Note that in the above example, the entire device is
+	dedicated to Vinum, and there is no leftover pre-Vinum root
+	partition, since this has been a newly set-up disk that was
+	only meant to be part of a Vinum configuration, ever.</para>
+    </sect2>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <para>If something goes wrong, a way is needed to recover from
+	the situation.	The following list contains few known pitfalls
+	and solutions.</para>
+
+      <sect3>
+	<title>System Bootstrap Loads, but System Does Not Boot</title>
+
+	<para>If for any reason the system does not continue to boot,
+	  the bootstrap can be interrupted with by pressing the
+	  <keycap>space</keycap> key at the 10-seconds warning.	 The
+	  loader variables (like <literal>vinum.autostart</literal>)
+	  can be examined using the <command>show</command>, and
+	  manipulated using <command>set</command> or
+	  <command>unset</command> commands.</para>
+
+	<para>If the only problem was that the Vinum kernel module was
+	  not yet in the list of modules to load automatically, a
+	  simple <command>load geom_vinum</command> will help.</para>
+
+	<para>When ready, the boot process can be continued with a
+	  <command>boot -as</command>.	The options
+	  <option>-as</option> will request the kernel to ask for the
+	  root filesystem to mount (<option>-a</option>), and make the
+	  boot process stop in single-user mode (<option>-s</option>),
+	  where the root filesystem is mounted read-only.  That way,
+	  even if only one plex of a multi-plex volume has been
+	  mounted, no data inconsistency between plexes is being
+	  risked.</para>
+
+	<para>At the prompt asking for a root filesystem to mount, any
+	  device that contains a valid root filesystem can be entered.
+	  If <filename>/etc/fstab</filename> had been set up
+	  correctly, the default should be something like
+	  <literal>ufs:/dev/gvinum/root</literal>.  A typical alternate
+	  choice would be something like
+	  <literal>ufs:da0d</literal> which could be a
+	  hypothetical partition that contains the pre-Vinum root
+	  filesystem.  Care should be taken if one of the alias
+	  <literal>"a"</literal> partitions are entered here that are
+	  actually reference to the subdisks of the Vinum root device,
+	  because in a mirrored setup, this would only mount one piece
+	  of a mirrored root device.  If this filesystem is to be
+	  mounted read-write later on, it is necessary to remove the
+	  other plex(es) of the Vinum root volume since these plexes
+	  would otherwise carry inconsistent data.</para>
+      </sect3>
+
+      <sect3>
+	<title>Only Primary Bootstrap Loads</title>
+
+	<para>If <filename>/boot/loader</filename> fails to load, but
+	  the primary bootstrap still loads (visible by a single dash
+	  in the left column of the screen right after the boot
+	  process starts), an attempt can be made to interrupt the
+	  primary bootstrap at this point, using the
+	  <keycap>space</keycap> key.  This will make the bootstrap
+	  stop in stage two, see <xref linkend="boot-boot1">.  An
+	  attempt can be made here to boot off an alternate partition,
+	  like the partition containing the previous root filesystem
+	  that has been moved away from <literal>"a"</literal>
+	  above.</para>
+      </sect3>
+
+      <sect3 id="vinum-root-panic">
+	<title>Nothing Boots, the Bootstrap
+	  Panics</title>
+
+	<para>This situation will happen if the bootstrap had been
+	  destroyed by the Vinum installation.	Unfortunately, Vinum
+	  accidentally currently leaves only 4 KB at the beginning of
+	  its partition free before starting to write its Vinum header
+	  information.	However, the stage one and two bootstraps plus
+	  the bsdlabel embedded between them currently require 8 KB.
+	  So if a Vinum partition was started at offset 0 within a
+	  slice or disk that was meant to be bootable, the Vinum setup
+	  will trash the bootstrap.</para>
+
+	<para>Similarly, if the above situation has been recovered,
+	  for example by booting from a <quote>Fixit</quote> medium,
+	  and the bootstrap has been re-installed using
+	  <command>bsdlabel -B</command> as described in <xref
+	  linkend="boot-boot1">, the bootstrap will trash the Vinum
+	  header, and Vinum will no longer find its disk(s).  Though
+	  no actual Vinum configuration data or data in Vinum volumes
+	  will be trashed by this, and it would be possible to recover
+	  all the data by entering exact the same Vinum configuration
+	  data again, the situation is hard to fix at all.  It would
+	  be necessary to move the entire Vinum partition by at least
+	  4 KB off, in order to have the Vinum header and the system
+	  bootstrap no longer collide.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="vinum-root-4x">
+      <title>Differences for FreeBSD 4.X</title>
+
+      <para>Under FreeBSD 4.X, some internal functions required to
+	make Vinum automatically scan all disks are missing, and the
+	code that figures out the internal ID of the root device is
+	not smart enough to handle a name like
+	<filename>/dev/vinum/root</filename> automatically.
+	Therefore, things are a little different here.</para>
+
+      <para>Vinum must explicitly be told which disks to scan, using a
+	line like the following one in
+	<filename>/boot/loader.conf</filename>:</para>
+
+      <programlisting>vinum.drives="/dev/<replaceable>da0</replaceable> /dev/<replaceable>da1</replaceable>"</programlisting>
+
+      <para>It is important that all drives are mentioned that could
+	possibly contain Vinum data.  It does not harm if
+	<emphasis>more</emphasis> drives are listed, nor is it
+	necessary to add each slice and/or partition explicitly, since
+	Vinum will scan all slices and partitions of the named drives
+	for valid Vinum headers.</para>
+
+      <para>Since the routines used to parse the name of the root
+	filesystem, and derive the device ID (major/minor number) are
+	only prepared to handle <quote>classical</quote> device names
+	like <filename>/dev/ad0s1a</filename>, they cannot make
+	any sense out of a root volume name like
+	<filename>/dev/vinum/root</filename>.  For that reason,
+	Vinum itself needs to pre-setup the internal kernel parameter
+	that holds the ID of the root device during its own
+	initialization.	 This is requested by passing the name of the
+	root volume in the loader variable
+	<literal>vinum.root</literal>.	The entry in
+	<filename>/boot/loader.conf</filename> to accomplish this
+	looks like:</para>
+
+      <programlisting>vinum.root="root"</programlisting>
+
+      <para>Now, when the kernel initialization tries to find out the
+	root device to mount, it sees whether some kernel module has
+	already pre-initialized the kernel parameter for it.  If that
+	is the case, <emphasis>and</emphasis> the device claiming the
+	root device matches the major number of the driver as figured
+	out from the name of the root device string being passed (that
+	is, <literal>"vinum"</literal> in our case), it will use the
+	pre-allocated device ID, instead of trying to figure out one
+	itself.	 That way, during the usual automatic startup, it can
+	continue to mount the Vinum root volume for the root
+	filesystem.</para>
+
+      <para>However, when <command>boot -a</command> has been
+	requesting to ask for entering the name of the root device
+	manually, it must be noted that this routine still cannot
+	actually parse a name entered there that refers to a Vinum
+	volume.  If any device name is entered that does not refer to
+	a Vinum device, the mismatch between the major numbers of the
+	pre-allocated root parameter and the driver as figured out
+	from the given name will make this routine enter its normal
+	parser, so entering a string like
+	<literal>ufs:da0d</literal> will work as expected. Note
+	that if this fails, it is however no longer possible to
+	re-enter a string like <literal>ufs:vinum/root</literal>
+	again, since it cannot be parsed.  The only way out is to
+	reboot again, and start over then.  (At the
+	<quote>askroot</quote> prompt, the initial
+	<filename>/dev/</filename> can always be omitted.)</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/pl_PL.ISO8859-2/books/handbook/x11/Makefile b/pl_PL.ISO8859-2/books/handbook/x11/Makefile
new file mode 100644
index 0000000000..06b452cd33
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/x11/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	x11/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/pl_PL.ISO8859-2/books/handbook/x11/chapter.sgml b/pl_PL.ISO8859-2/books/handbook/x11/chapter.sgml
new file mode 100644
index 0000000000..319dc29131
--- /dev/null
+++ b/pl_PL.ISO8859-2/books/handbook/x11/chapter.sgml
@@ -0,0 +1,1680 @@
+<!--
+     The FreeBSD Documentation Project
+
+     $FreeBSD$
+-->
+
+<chapter id="x11">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Ken</firstname>
+	<surname>Tom</surname>
+	<contrib>Updated for X.Org's X11 server by </contrib>
+      </author>
+      <author>
+	<firstname>Marc</firstname>
+	<surname>Fonvieille</surname>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>The X Window System</title>
+
+  <sect1 id="x11-synopsis">
+    <title>Synopsis</title>
+
+    <para>FreeBSD uses X11 to provide users with
+      a powerful graphical user interface.  X11
+      is an open-source implementation of the X Window System that
+      includes both <application>&xorg;</application> and
+      <application>&xfree86;</application>.  &os; versions up to and
+      including &os;&nbsp;5.2.1-RELEASE
+      will find the default installation to be
+      <application>&xfree86;</application>, the X11 server released by
+      The &xfree86; Project, Inc.  As of &os;&nbsp;5.3-RELEASE, the
+      default and official flavor of X11 was changed to
+      <application>&xorg;</application>, the X11 server developed by
+      the X.Org Foundation.</para>
+
+    <para>This chapter will cover the installation and configuration
+      of X11 with emphasis on
+      <application>&xorg;</application>.</para>
+
+    <para>For more information on the video hardware that X11
+      supports, check either the <ulink
+      url="http://www.x.org/">&xorg;</ulink> or <ulink
+      url="http://www.XFree86.org/">&xfree86;</ulink> web
+      sites.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>The various components of the X Window System, and how they
+          interoperate.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to install and configure X11.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to install and use different window managers.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use &truetype; fonts in X11.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to set up your system for graphical logins
+          (<application>XDM</application>).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem><para>Know how to install additional third-party
+        software (<xref linkend="ports">).</para></listitem>
+    </itemizedlist>
+
+    <note>
+      <para>This chapter covers the installation and the configuration
+	of both <application>&xorg;</application> and
+	<application>&xfree86;</application> X11 servers.  For the most
+	part, configuration files, commands and syntaxes are identical.
+	In the case where there are differences, both
+	<application>&xorg;</application> and
+	<application>&xfree86;</application> syntaxes will be
+	shown.</para>
+    </note>
+  </sect1>
+
+  <sect1 id="x-understanding">
+    <title>Understanding X</title>
+
+    <para>Using X for the first time can be somewhat of a shock to someone
+      familiar with other graphical environments, such as &microsoft.windows; or
+      &macos;.</para>
+
+    <para>While it is not necessary to understand all of the details of various
+      X components and how they interact, some basic knowledge makes
+      it possible to take advantage of X's strengths.</para>
+
+    <sect2>
+      <title>Why X?</title>
+
+      <para>X is not the first window system written for &unix;, but it is the
+        most popular of them.  X's original development team had worked on another
+        window system prior to writing X.  That system's name was
+        <quote>W</quote> (for <quote>Window</quote>).  X was just the next
+        letter in the Roman alphabet.</para>
+
+      <para>X can be called <quote>X</quote>, <quote>X Window System</quote>,
+	<quote>X11</quote>, and a number of other terms.  You may find
+	that using the term <quote>X Windows</quote> to describe X11
+	can be offensive to some people; for a bit more insight on
+	this, see &man.X.7;.</para>
+    </sect2>
+
+    <sect2>
+      <title>The X Client/Server Model</title>
+
+      <para>X was designed from the beginning to be network-centric, and
+        adopts a <quote>client-server</quote> model.</para>
+
+      <para>In the X model, the
+        <quote>X server</quote> runs on the computer that has the keyboard,
+        monitor, and mouse attached.  The server's responsibility includes tasks such as managing
+        the display, handling input from the keyboard and mouse, and so on.
+        Each X application (such as <application>XTerm</application>, or
+        <application>&netscape;</application>) is a <quote>client</quote>.  A
+        client sends messages to the server such as <quote>Please draw a
+          window at these coordinates</quote>, and the server sends back
+          messages such as <quote>The user just clicked on the OK
+          button</quote>.</para>
+
+      <para>In a home or small
+        office environment, the X server and the X clients commonly run on
+        the same computer.  However, it is perfectly possible to run the X
+        server on a less powerful desktop computer, and run X applications
+        (the clients) on, say, the powerful and expensive machine that serves
+        the office.  In this scenario the communication between the X client
+        and server takes place over the network.</para>
+
+      <para>This confuses some people, because the X terminology is
+        exactly backward to what they expect.  They expect the <quote>X
+          server</quote> to be the big powerful machine down the hall, and
+        the <quote>X client</quote> to be the machine on their desk.</para>
+
+      <para>It is important to remember that the X server is the machine with the monitor and
+        keyboard, and the X clients are the programs that display the
+        windows.</para>
+
+      <para>There is nothing in the protocol that forces the client and
+        server machines to be running the same operating system, or even to
+        be running on the same type of computer.  It is certainly possible to
+        run an X server on &microsoft.windows; or Apple's &macos;, and there are
+        various free and commercial applications available that do exactly
+        that.</para>
+
+      <para>Starting with &os;&nbsp;5.3-RELEASE, the X server that
+	installs with &os; is <application>&xorg;</application>,
+        and is available for free, under a
+        license very similar to the FreeBSD license.  Commercial X servers for
+        FreeBSD are also available.</para>
+    </sect2>
+
+    <sect2>
+      <title>The Window Manager</title>
+
+      <para>The X design philosophy is much like the &unix; design philosophy,
+        <quote>tools, not policy</quote>.  This means that X does not try to
+        dictate how a task is to be accomplished.  Instead, tools are provided
+        to the user, and it is the user's responsibility to decide how to use
+        those tools.</para>
+
+      <para>This philosophy extends to X not dictating what windows should
+        look like on screen, how to move them around with the mouse, what
+        keystrokes should be used to move between windows (i.e.,
+        <keycombo action="simul">
+          <keycap>Alt</keycap>
+          <keycap>Tab</keycap>
+        </keycombo>, in the case of &microsoft.windows;), what the title bars
+        on each window should look like, whether or not they have close
+        buttons on them, and so on.</para>
+
+      <para>Instead, X delegates this responsibility to an application called
+        a <quote>Window Manager</quote>.  There are dozens of window
+        managers available for X: <application>AfterStep</application>,
+        <application>Blackbox</application>, <application>ctwm</application>,
+        <application>Enlightenment</application>,
+        <application>fvwm</application>, <application>Sawfish</application>,
+        <application>twm</application>,
+        <application>Window Maker</application>, and more.  Each of these
+        window managers provides a different look and feel; some of them
+        support <quote>virtual desktops</quote>; some of them allow customized
+        keystrokes to manage the desktop; some have a <quote>Start</quote>
+        button or similar device; some are <quote>themeable</quote>, allowing
+        a complete change of look-and-feel by applying a new theme.  These
+        window managers, and many more, are available in the
+        <filename>x11-wm</filename> category of the Ports Collection.</para>
+
+      <para>In addition, the <application>KDE</application> and
+	<application>GNOME</application> desktop environments both have their
+	own window managers which integrate with the desktop.</para>
+
+      <para>Each window manager also has a different configuration mechanism;
+        some expect configuration file written by hand, others feature
+        GUI tools for most of the configuration tasks; at least one
+        (<application>Sawfish</application>) has a configuration file written
+        in a dialect of the Lisp language.</para>
+
+      <note>
+        <title>Focus Policy</title>
+
+        <para>Another feature the window manager is responsible for is the
+          mouse <quote>focus policy</quote>.  Every windowing system
+          needs some means of choosing a window to be actively receiving
+          keystrokes, and should visibly indicate which window is active as
+          well.</para>
+
+        <para>A familiar focus policy is called <quote>click-to-focus</quote>.
+          This is the model utilized by &microsoft.windows;, in which a window
+          becomes active upon receiving a mouse click.</para>
+
+        <para>X does not support any particular focus policy.  Instead, the
+          window manager controls which window has the focus at any one time.
+          Different window managers will support different focus methods.  All
+          of them support click to focus, and the majority of them support
+          several others.</para>
+
+        <para>The most popular focus policies are:</para>
+
+        <variablelist>
+          <varlistentry>
+            <term>focus-follows-mouse</term>
+
+            <listitem>
+              <para>The window that is under the mouse pointer is the
+                window that has the focus.  This may not necessarily be
+                the window that is on top of all the other windows.
+                The focus is changed by pointing at another window, there
+                is no need to click in it as well.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>sloppy-focus</term>
+
+            <listitem>
+              <para>This policy is a small extension to focus-follows-mouse.
+                With focus-follows-mouse, if the mouse is moved over the
+                root window (or background) then no window has the focus,
+                and keystrokes are simply lost.  With sloppy-focus, focus is
+                only changed when the cursor enters a new window, and not
+                when exiting the current window.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>click-to-focus</term>
+
+            <listitem>
+              <para>The active window is selected by mouse click.  The
+                window may then be <quote>raised</quote>, and appear in
+                front of all other windows.  All keystrokes will now be
+                directed to this window, even if the cursor is moved to
+                another window.</para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+
+        <para>Many window managers support other policies, as well as
+          variations on these.  Be sure to consult the documentation for
+          the window manager itself.</para>
+      </note>
+    </sect2>
+
+    <sect2>
+      <title>Widgets</title>
+
+      <para>The X approach of providing tools and not policy extends to the
+        widgets seen on screen in each application.</para>
+
+      <para><quote>Widget</quote> is a term for all the items in the user
+        interface that can be clicked or manipulated in some way; buttons,
+        check boxes, radio buttons, icons, lists, and so on.  &microsoft.windows;
+        calls these <quote>controls</quote>.</para>
+
+      <para>&microsoft.windows; and Apple's &macos; both have a very rigid widget
+        policy.  Application developers are supposed to ensure that their
+        applications share a common look and feel.  With X, it was not
+        considered sensible to mandate a particular graphical style, or set
+        of widgets to adhere to.</para>
+
+      <para>As a result, do not expect X applications to have a common
+        look and feel.  There are several popular widget sets and
+        variations, including the original Athena widget set from MIT,
+        <application>&motif;</application> (on which the widget set in
+        &microsoft.windows; was modeled, all bevelled edges and three shades of
+        grey), <application>OpenLook</application>, and others.</para>
+
+      <para>Most newer X applications today will use a modern-looking widget
+        set, either Qt, used by <application>KDE</application>, or
+        GTK+, used by the
+        <application>GNOME</application>
+        project.  In this respect, there is some convergence in
+        look-and-feel of the &unix; desktop, which certainly makes things
+        easier for the novice user.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="x-install">
+    <title>Installing X11</title>
+
+    <para><application>&xorg;</application> or
+      <application>&xfree86;</application> may be installed on &os;.
+      Beginning with &os;&nbsp;5.3-RELEASE,
+      <application>&xorg;</application> is the default X11
+      implementation for &os;.  <application>&xorg;</application> is
+      the X server of the open source X Window System implementation released by the X.Org
+      Foundation.  <application>&xorg;</application> is based on the code of
+      <application>&xfree86&nbsp;4.4RC2</application> and X11R6.6.
+      The X.Org Foundation released X11R6.7 in April 2004 and
+      X11R6.8.2 in February 2005, this latter is the version
+      currently available in the &os; Ports Collection.</para>
+
+    <para>To build and install <application>&xorg;</application> from the
+      Ports Collection:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+    <note>
+      <para>To build <application>&xorg;</application> in its
+	entirety, be sure to have at least 4&nbsp;GB of free space
+	available.</para>
+    </note>
+
+    <para>To build and install <application>&xfree86;</application>
+      from the Ports Collection:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/ports/x11/XFree86-4</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+    <para>Alternatively, X11
+      can be installed directly from packages.
+      Binary packages to use with &man.pkg.add.1; tool are also available for
+      X11.  When the remote fetching
+      feature of &man.pkg.add.1; is used, the version number of the
+      package must be removed.  &man.pkg.add.1; will automatically fetch
+      the latest version of the application.</para>
+
+    <para>So to fetch and install the package of
+      <application>&xorg;</application>, simply type:</para>
+
+    <screen>&prompt.root; <userinput>pkg_add -r xorg</userinput></screen>
+
+    <para>The <application>&xfree86;&nbsp;4.X</application> package can be
+      installed by typing:</para>
+
+    <screen>&prompt.root; <userinput>pkg_add -r XFree86</userinput></screen>
+
+    <note><para>The examples above will install the complete
+      X11 distribution including the
+      servers, clients, fonts etc.  Separate packages and ports of X11
+      are also
+      available.</para></note>
+
+    <para>The rest of this chapter will explain how to configure
+      X11, and how to set up a productive desktop
+      environment.</para>
+
+    <sect2 id="x-to-xorg">
+      <title>Moving from <application>&xfree86;</application> to
+	<application>&xorg;</application></title>
+
+      <para>As with any port, you should check the
+	<filename>/usr/ports/UPDATING</filename> file for changes.
+	Included in this file are instructions for converting your
+	system from <application>&xfree86;</application> to
+	<application>&xorg;</application>.</para>
+
+      <para>Use <application>CVSup</application> to update your ports
+	tree prior to attempting any conversion.  You will also need
+	to install <filename
+	role="package">sysutils/portupgrade</filename> prior to
+	converting your X11 installation.</para>
+
+      <para>In your <filename>/etc/make.conf</filename> you will need
+	to add the variable <literal>X_WINDOW_SYSTEM=xorg</literal>.
+	This ensures that your system knows which X11 is being used.
+	The older <literal>XFREE86_VERSION</literal> variable has been
+	deprecated and has been replaced with the
+	<literal>X_WINDOW_SYSTEM</literal> variable.</para>
+
+      <para>Then, use the following commands:</para>
+
+      <screen>&prompt.root; <userinput>pkg_delete -f /var/db/pkg/imake-4* /var/db/pkg/XFree86-*</userinput>
+&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput>
+&prompt.root; <userinput>make install clean</userinput>
+&prompt.root; <userinput>pkgdb -F</userinput></screen>
+
+      <para>The &man.pkgdb.1; command is part of the
+	<application>portupgrade</application> software and will
+	update various package dependencies.</para>
+
+      <note>
+	<para>To build <application>&xorg;</application> in its
+	  entirety, be sure to have at least 4&nbsp;GB of free space
+	  available.</para>
+      </note>
+    </sect2>
+  </sect1>
+
+  <sect1 id="x-config">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Christopher</firstname>
+          <surname>Shumway</surname>
+          <contrib>Contributed by </contrib>
+          <!-- July 2001 -->
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>X11 Configuration</title>
+
+
+    <indexterm><primary>&xfree86;&nbsp;4.X</primary></indexterm>
+    <indexterm><primary>&xfree86;</primary></indexterm>
+    <indexterm><primary>&xorg;</primary></indexterm>
+    <indexterm><primary>X11</primary></indexterm>
+
+    <sect2>
+      <title>Before Starting</title>
+
+      <para>Before configuration of X11
+        the following information about the target system is needed:</para>
+
+      <itemizedlist>
+        <listitem><para>Monitor specifications</para></listitem>
+        <listitem><para>Video Adapter chipset</para></listitem>
+        <listitem><para>Video Adapter memory</para></listitem>
+      </itemizedlist>
+
+      <indexterm><primary>horizontal scan rate</primary></indexterm>
+      <indexterm><primary>vertical scan rate</primary></indexterm>
+
+      <para>The specifications for the monitor are used by
+        X11 to determine the resolution and
+        refresh rate to run at.  These specifications can usually be
+        obtained from the documentation that came with the monitor or from
+        the manufacturer's website.  There are two ranges of numbers that
+        are needed, the horizontal scan rate and the vertical synchronization
+        rate.</para>
+
+      <para>The video adapter's chipset defines what driver module
+        X11 uses to talk to the graphics
+        hardware.  With most chipsets, this can be automatically
+        determined, but it is still useful to know in case the automatic
+        detection does not work correctly.</para>
+
+      <para>Video memory on the graphic adapter determines the
+        resolution and color depth which the system can run at.  This is
+        important to know so the user knows the limitations of the
+        system.</para>
+
+    </sect2>
+
+    <sect2>
+      <title>Configuring X11</title>
+
+      <para>Configuration of X11 is
+        a multi-step process.  The first step is to build an initial
+        configuration file.
+        As the super user, simply
+        run:</para>
+
+      <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen>
+
+      <para>In the case of <application>&xfree86;</application>
+	type:</para>
+
+      <screen>&prompt.root; <userinput>XFree86 -configure</userinput></screen>
+
+      <para>This will generate an
+        X11 configuration skeleton file in the
+        <filename>/root</filename> directory called
+	<filename>xorg.conf.new</filename> (whether you &man.su.1; or
+	do a direct login affects the inherited supervisor
+	<envar>$HOME</envar> directory variable).
+	For <application>&xfree86;</application>, this configuration
+	file is called  <filename>XF86Config.new</filename>.  The
+        X11 program will attempt to probe
+        the graphics hardware on the system and write a
+        configuration file to load the proper drivers for the detected
+        hardware on the target system.</para>
+
+      <para>The next step is to test the existing
+        configuration to verify that <application>&xorg;</application>
+        can work with the graphics
+        hardware on the target system.  To perform this task,
+        type:</para>
+
+      <screen>&prompt.root; <userinput>Xorg -config xorg.conf.new</userinput></screen>
+
+      <para><application>&xfree86;</application> users will type:</para>
+
+      <screen>&prompt.root; <userinput>XFree86 -xf86config XF86Config.new</userinput></screen>
+
+      <para>If a black and grey grid and an X mouse cursor appear,
+        the configuration was successful.  To exit the test, just press
+        <keycombo action="simul">
+          <keycap>Ctrl</keycap>
+          <keycap>Alt</keycap>
+          <keycap>Backspace</keycap>
+        </keycombo> simultaneously.</para>
+
+	<note><para>If the mouse does not work, you will need to first
+	  configure it before proceeding.  See <xref linkend="mouse">
+	  in the &os; install chapter.</para></note>
+
+      <indexterm><primary>X11 tuning</primary></indexterm>
+
+      <para>Next, tune the <filename>xorg.conf.new</filename> (or <filename>XF86Config.new</filename> if you are running <application>&xfree86;</application>)
+        configuration file to taste.  Open the file in a text editor such
+        as &man.emacs.1; or &man.ee.1;.  First, add the
+        frequencies for the target system's monitor.  These are usually
+        expressed as a horizontal and vertical synchronization rate.  These
+        values are added to the <filename>xorg.conf.new</filename> file
+        under the <literal>"Monitor"</literal> section:</para>
+
+      <programlisting>Section "Monitor"
+        Identifier   "Monitor0"
+        VendorName   "Monitor Vendor"
+        ModelName    "Monitor Model"
+        HorizSync    30-107
+        VertRefresh  48-120
+EndSection</programlisting>
+
+      <para>The <literal>HorizSync</literal> and
+        <literal>VertRefresh</literal> keywords may be missing in the
+        configuration file.  If they are, they need to be added, with
+        the correct horizontal synchronization rate placed after the
+        <literal>HorizSync</literal> keyword and the vertical
+        synchronization rate after the <literal>VertRefresh</literal>
+        keyword.  In the example above the target monitor's rates were
+        entered.</para>
+
+      <para>X allows DPMS (Energy Star) features to be used with capable
+        monitors. The &man.xset.1; program controls the time-outs and can force
+        standby, suspend, or off modes.  If you wish to enable DPMS features
+        for your monitor, you must add the following line to the monitor
+        section:</para>
+
+      <programlisting>
+        Option       "DPMS"</programlisting>
+
+      <indexterm>
+        <primary><filename>xorg.conf</filename></primary>
+      </indexterm>
+      <indexterm>
+        <primary><filename>XF86Config</filename></primary>
+      </indexterm>
+
+      <para>While the <filename>xorg.conf.new</filename> (or <filename>XF86Config.new</filename>)
+        configuration file is still open in an editor, select
+        the default resolution and color depth desired.  This is
+        defined in the <literal>"Screen"</literal> section:</para>
+
+      <programlisting>Section "Screen"
+        Identifier "Screen0"
+        Device     "Card0"
+        Monitor    "Monitor0"
+        DefaultDepth 24
+        SubSection "Display"
+                Viewport  0 0
+                Depth     24
+                Modes     "1024x768"
+        EndSubSection
+EndSection</programlisting>
+
+      <para>The <literal>DefaultDepth</literal> keyword describes
+        the color depth to run at by default.  This can be overridden
+        with the <option>-depth</option> command line switch to
+        &man.Xorg.1; (or &man.XFree86.1;).
+        The <literal>Modes</literal> keyword
+        describes the resolution to run at for the given color depth.
+        Note that only VESA standard modes are supported as defined by
+        the target system's graphics hardware.
+        In the example above, the default color depth is twenty-four
+        bits per pixel.  At this color depth, the accepted resolution is
+        1024 by 768
+        pixels.</para>
+
+      <para>Finally, write the configuration file and test it using
+        the test mode given above.</para>
+
+      <note>
+	<para>One of the tools available to assist you during
+	  troubleshooting process are the X11 log files, which contain
+	  information on each device that the X11 server attaches to.
+	  <application>&xorg;</application> log file names are in the format
+	  of <filename>/var/log/Xorg.0.log</filename>
+	  (<application>&xfree86;</application> log file names follow the
+	  format of <filename>XFree86.0.log</filename>).  The exact name
+	  of the log can vary from <filename>Xorg.0.log</filename> to
+	  <filename>Xorg.8.log</filename> and so forth.</para>
+      </note>
+
+      <para>If all is well, the configuration
+        file needs to be installed in a common location where
+        &man.Xorg.1; (or &man.XFree86.1;)
+        can find it.
+	This is typically <filename>/etc/X11/xorg.conf</filename> or
+	<filename>/usr/X11R6/etc/X11/xorg.conf</filename> (for
+	<application>&xfree86;</application> it is called
+        <filename>/etc/X11/XF86Config</filename> or
+        <filename>/usr/X11R6/etc/X11/XF86Config</filename>).</para>
+
+      <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen>
+
+      <para>For <application>&xfree86;</application>:</para>
+
+      <screen>&prompt.root; <userinput>cp XF86Config.new /etc/X11/XF86Config</userinput></screen>
+
+      <para>The X11 configuration process is now
+        complete.  In order to start
+        <application>&xfree86;&nbsp;4.X</application> with &man.startx.1;,
+        install the <filename role="package">x11/wrapper</filename> port.
+	<application>&xorg;</application> already includes the wrapper
+	code and does not require the installation of the wrapper port.
+	The X11 server may also be started with the use of
+        &man.xdm.1;.</para>
+
+      <note><para>There is also a graphical configuration tool,
+	&man.xorgcfg.1; (&man.xf86cfg.1; for <application>&xfree86;</application>), that comes with the
+	X11 distribution.  It
+	allows you to interactively define your configuration by choosing
+	the appropriate drivers and settings.  This program can be invoked from the console, by typing the command <command>xorgcfg -textmode</command>.  For more details,
+	refer to the &man.xorgcfg.1; and &man.xf86cfg.1; manual pages.</para>
+
+      <para>Alternatively, there is also a tool called &man.xorgconfig.1;
+	(&man.xf86config.1; for <application>&xfree86;</application>),
+	this program is a console utility that is less user friendly,
+	but it may work in situations where the other tools do
+	not.</para></note>
+
+    </sect2>
+
+    <sect2>
+      <title>Advanced Configuration Topics</title>
+
+      <sect3>
+        <title>Configuration with &intel; i810 Graphics Chipsets</title>
+
+        <indexterm><primary>Intel i810 graphic chipset</primary></indexterm>
+
+        <para>Configuration with &intel; i810 integrated chipsets
+          requires the <devicename>agpgart</devicename>
+          AGP programming interface for X11
+          to drive the card.  See the &man.agp.4; driver manual page
+	  for more information.</para>
+
+        <para>This will allow configuration of the hardware as any other
+          graphics board.  Note on systems without the &man.agp.4;
+	  driver compiled in the kernel, trying to load the module
+	  with &man.kldload.8; will not work.  This driver has to be
+	  in the kernel at boot time through being compiled in or
+	  using <filename>/boot/loader.conf</filename>.</para>
+
+	<para>If you are using <application>&xfree86;&nbsp;4.1.0</application> (or
+	  later) and messages about unresolved symbols like
+          <literal>fbPictureInit</literal> appear, try adding the
+          following line after <literal>Driver "i810"</literal> in the
+          X11 configuration file:</para>
+        <programlisting>Option "NoDDC"</programlisting>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="x-fonts">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Murray</firstname>
+          <surname>Stokely</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>Using Fonts in X11</title>
+
+    <sect2 id="type1">
+    <title>Type1 Fonts</title>
+    <para>The default fonts that ship with
+      X11 are less than ideal for typical
+    desktop publishing applications.  Large presentation fonts show up
+    jagged and unprofessional looking, and small fonts in
+    <application>&netscape;</application> are almost completely unintelligible.
+    However, there are several free, high quality Type1 (&postscript;) fonts
+    available which can be readily used
+    with X11.  For instance, the URW font collection
+    (<filename role="package">x11-fonts/urwfonts</filename>) includes
+    high quality versions of standard type1 fonts (<trademark class="registered">Times Roman</trademark>,
+    <trademark class="registered">Helvetica</trademark>, <trademark class="registered">Palatino</trademark> and others).  The Freefonts collection
+    (<filename role="package">x11-fonts/freefonts</filename>) includes
+    many more fonts, but most of them are intended for use in
+    graphics software such as the <application>Gimp</application>, and are not
+    complete enough to serve as screen fonts.  In addition,
+    X11 can be configured to use
+    &truetype; fonts with a minimum of effort.  For more details on
+    this, see the &man.X.7; manual page or the
+    <link linkend="truetype">section on &truetype; fonts</link>.</para>
+
+    <para>To install the above Type1 font collections from the ports
+        collection, run the following commands:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+    <para>And likewise with the freefont or other collections.  To have the X
+      server detect these fonts, add an appropriate line to the
+      X server configuration file in <filename>/etc/X11/</filename>
+      (<filename>xorg.conf</filename> for
+      <application>&xorg;</application> and
+      <filename>XF86Config</filename> for
+      <application>&xfree86;</application>), which reads:</para>
+
+      <programlisting>FontPath "/usr/X11R6/lib/X11/fonts/URW/"</programlisting>
+
+      <para>Alternatively, at the command line in the X session
+        run:</para>
+
+      <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/URW</userinput>
+&prompt.user; <userinput>xset fp rehash</userinput></screen>
+
+      <para>This will work but will be lost when the X session is closed,
+    unless it is added to the startup file (<filename>~/.xinitrc</filename>
+    for a normal <command>startx</command> session,
+    or <filename>~/.xsession</filename> when logging in through a
+    graphical login manager like <application>XDM</application>).
+    A third way is to use the new
+    <filename>/usr/X11R6/etc/fonts/local.conf</filename> file: see the
+    section on <link linkend="antialias">anti-aliasing</link>.
+    </para>
+    </sect2>
+
+    <sect2 id="truetype">
+    <title>&truetype; Fonts</title>
+
+    <indexterm><primary>TrueType Fonts</primary></indexterm>
+    <indexterm><primary>fonts</primary>
+      <secondary>TrueType</secondary>
+    </indexterm>
+
+    <para>Both <application>&xfree86;&nbsp;4.X</application> and <application>&xorg;</application> have built in support
+    for rendering &truetype; fonts.  There are two different modules
+    that can enable this functionality.  The freetype module is used
+    in this example because it is more consistent with the other font
+    rendering back-ends.  To enable the freetype module just add the
+    following line to the <literal>"Module"</literal> section of the
+    <filename>/etc/X11/xorg.conf</filename> or
+    <filename>/etc/X11/XF86Config</filename> file.</para>
+
+    <programlisting>Load  "freetype"</programlisting>
+
+    <para>For <application>&xfree86;&nbsp;3.3.X</application>, a separate
+      &truetype; font server is needed.
+      <application>Xfstt</application> is commonly used for
+      this purpose.  To install <application>Xfstt</application>,
+      simply install the port
+      <filename role="package">x11-servers/Xfstt</filename>.</para>
+
+    <para>Now make a directory for the &truetype; fonts (for example,
+      <filename>/usr/X11R6/lib/X11/fonts/TrueType</filename>)
+      and copy all of the &truetype; fonts into this directory.  Keep in
+      mind that &truetype; fonts cannot be directly taken from a
+      &macintosh;; they must be in &unix;/&ms-dos;/&windows; format for use by
+      X11.  Once the files have been
+      copied into this directory, use
+      <application>ttmkfdir</application> to create a
+      <filename>fonts.dir</filename> file, so that the X font renderer
+      knows that these new files have been installed.
+      <command>ttmkfdir</command> is available from the FreeBSD
+      Ports Collection as
+      <filename role="package">x11-fonts/ttmkfdir</filename>.</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/TrueType</userinput>
+&prompt.root; <userinput>ttmkfdir &gt; fonts.dir</userinput></screen>
+
+    <para>Now add the &truetype; directory to the font
+      path.  This is just the same as described above for <link
+      linkend="type1">Type1</link> fonts, that is, use</para>
+
+    <screen>&prompt.user; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/TrueType</userinput>
+&prompt.user; <userinput>xset fp rehash</userinput></screen>
+
+    <para>or add a <literal>FontPath</literal> line to the
+       <filename>xorg.conf</filename> (or <filename>XF86Config</filename>) file.</para>
+
+      <para>That's it.  Now <application>&netscape;</application>,
+        <application>Gimp</application>,
+        <application>&staroffice;</application>, and all of the other X
+        applications should now recognize the installed &truetype;
+        fonts.  Extremely small fonts (as with text in a high resolution
+        display on a web page) and extremely large fonts (within
+        <application>&staroffice;</application>) will look much better
+        now.</para>
+    </sect2>
+
+    <sect2 id="antialias">
+    <sect2info>
+      <authorgroup>
+        <author>
+          <firstname>Joe Marcus</firstname>
+          <surname>Clarke</surname>
+          <contrib>Updated by </contrib>
+          <!-- May 2003 -->
+        </author>
+      </authorgroup>
+    </sect2info>
+    <title>Anti-Aliased Fonts</title>
+
+    <indexterm><primary>anti-aliased fonts</primary></indexterm>
+    <indexterm><primary>fonts</primary>
+      <secondary>anti-aliased</secondary></indexterm>
+
+    <para>Anti-aliasing has been available in X11 since
+      <application>&xfree86;</application> 4.0.2.  However, font
+      configuration was cumbersome before the introduction of
+      <application>&xfree86;</application> 4.3.0.
+      Beginning with
+      <application>&xfree86;</application> 4.3.0, all fonts in X11
+      that are found
+      in <filename>/usr/X11R6/lib/X11/fonts/</filename> and
+      <filename>~/.fonts/</filename> are automatically 
+      made available for anti-aliasing to Xft-aware applications.  Not
+      all applications are Xft-aware, but many have received Xft support.
+      Examples of Xft-aware applications include Qt 2.3 and higher (the 
+      toolkit for the <application>KDE</application> desktop), 
+      GTK+ 2.0 and higher (the toolkit for the 
+      <application>GNOME</application> desktop), and 
+      <application>Mozilla</application> 1.2 and higher.
+    </para>
+
+    <para>In order to control which fonts are anti-aliased, or to
+      configure anti-aliasing properties, create (or edit, if it
+      already exists) the file
+      <filename>/usr/X11R6/etc/fonts/local.conf</filename>.  Several
+      advanced features of the Xft font system can be tuned using
+      this file; this section describes only some simple
+      possibilities.  For more details, please see
+      &man.fonts-conf.5;.</para>
+
+    <indexterm><primary>XML</primary></indexterm>
+
+    <para>This file must be in XML format.  Pay careful attention to
+      case, and make sure all tags are properly closed.  The file
+      begins with the usual XML header followed by a DOCTYPE
+      definition, and then the <literal>&lt;fontconfig&gt;</literal> tag:</para>
+
+    <programlisting>
+      &lt;?xml version="1.0"?&gt;
+      &lt;!DOCTYPE fontconfig SYSTEM "fonts.dtd"&gt;
+      &lt;fontconfig&gt;
+    </programlisting>
+
+    <para>As previously stated, all fonts in
+      <filename>/usr/X11R6/lib/X11/fonts/</filename> as well as
+      <filename>~/.fonts/</filename> are already made available to
+      Xft-aware applications.  If you wish to add another directory
+      outside of these two directory trees, add a line similar to the
+      following to
+      <filename>/usr/X11R6/etc/fonts/local.conf</filename>:</para>
+
+    <programlisting>&lt;dir&gt;/path/to/my/fonts&lt;/dir&gt;</programlisting>
+
+    <para>After adding new fonts, and especially new font directories,
+      you should run the following command to rebuild the font
+      caches:</para>
+
+    <screen>&prompt.root; <userinput>fc-cache -f</userinput></screen>
+
+    <para>Anti-aliasing makes borders slightly fuzzy, which makes very
+      small text more readable and removes <quote>staircases</quote> from
+      large text, but can cause eyestrain if applied to normal text.  To
+      exclude font sizes smaller than 14 point from anti-aliasing, include
+      these lines:</para>
+
+      <programlisting>        &lt;match target="font"&gt;
+            &lt;test name="size" compare="less"&gt;
+                &lt;double&gt;14&lt;/double&gt;
+            &lt;/test&gt;
+            &lt;edit name="antialias" mode="assign"&gt;
+                &lt;bool&gt;false&lt;/bool&gt;
+            &lt;/edit&gt;
+        &lt;/match&gt;
+        &lt;match target="font"&gt;
+            &lt;test name="pixelsize" compare="less" qual="any"&gt;
+                &lt;double&gt;14&lt;/double&gt;
+            &lt;/test&gt;
+            &lt;edit mode="assign" name="antialias"&gt;
+                &lt;bool&gt;false&lt;/bool&gt;
+            &lt;/edit&gt;
+        &lt;/match&gt;</programlisting>
+
+    <indexterm><primary>fonts</primary>
+      <secondary>spacing</secondary></indexterm>
+
+    <para>Spacing for some monospaced fonts may also be inappropriate
+      with anti-aliasing.  This seems to be an issue with
+      <application>KDE</application>, in particular.  One possible fix for
+      this is to force the spacing for such fonts to be 100.  Add the
+      following lines:</para>
+
+     <programlisting>       &lt;match target="pattern" name="family"&gt;
+           &lt;test qual="any" name="family"&gt;
+               &lt;string&gt;fixed&lt;/string&gt;
+           &lt;/test&gt;
+           &lt;edit name="family" mode="assign"&gt;
+               &lt;string&gt;mono&lt;/string&gt;
+           &lt;/edit&gt;
+        &lt;/match&gt;
+        &lt;match target="pattern" name="family"&gt;
+            &lt;test qual="any" name="family"&gt;
+                &lt;string&gt;console&lt;/string&gt;
+            &lt;/test&gt;
+            &lt;edit name="family" mode="assign"&gt;
+                &lt;string&gt;mono&lt;/string&gt;
+            &lt;/edit&gt;
+        &lt;/match&gt;</programlisting>
+
+      <para>(this aliases the other common names for fixed fonts as
+        <literal>"mono"</literal>), and then add:</para>
+
+      <programlisting>         &lt;match target="pattern" name="family"&gt;
+             &lt;test qual="any" name="family"&gt;
+                 &lt;string&gt;mono&lt;/string&gt;
+             &lt;/test&gt;
+             &lt;edit name="spacing" mode="assign"&gt;
+                 &lt;int&gt;100&lt;/int&gt;
+             &lt;/edit&gt;
+         &lt;/match&gt;      </programlisting>
+
+      <para>Certain fonts, such as Helvetica, may have a problem when
+	anti-aliased.  Usually this manifests itself as a font that
+	seems cut in half vertically.  At worst, it may cause
+	applications such as <application>Mozilla</application> to
+	crash.  To avoid this, consider adding the following to
+	<filename>local.conf</filename>:</para>
+
+      <programlisting>         &lt;match target="pattern" name="family"&gt;
+             &lt;test qual="any" name="family"&gt;
+                 &lt;string&gt;Helvetica&lt;/string&gt;
+             &lt;/test&gt;
+             &lt;edit name="family" mode="assign"&gt;
+                 &lt;string&gt;sans-serif&lt;/string&gt;
+             &lt;/edit&gt;
+         &lt;/match&gt;        </programlisting>
+
+      <para>Once you have finished editing
+        <filename>local.conf</filename> make sure you end the file
+        with the <literal>&lt;/fontconfig&gt;</literal> tag.  Not doing this will cause
+        your changes to be ignored.</para>
+
+       <para>The default font set that comes with 
+	 X11 is not very
+         desirable when it comes to anti-aliasing.  A much better
+	 set of default fonts can be found in the 
+	 <filename role="package">x11-fonts/bitstream-vera</filename>
+	 port.  This port will install a
+	 <filename>/usr/X11R6/etc/fonts/local.conf</filename> file
+	 if one does not exist already.  If the file does exist,
+	 the port will create a <filename>/usr/X11R6/etc/fonts/local.conf-vera
+	 </filename> file.  Merge the contents of this file into
+	 <filename>/usr/X11R6/etc/fonts/local.conf</filename>, and the 
+	 Bitstream fonts will automatically replace the default 
+	 X11 Serif, Sans Serif, and Monospaced
+	 fonts.</para>
+
+       <para>Finally, users can add their own settings via their personal 
+        <filename>.fonts.conf</filename> files.  To do this, each user should 
+	simply create a <filename>~/.fonts.conf</filename>.  This file must 
+	also be in XML format.</para>
+
+       <indexterm><primary>LCD screen</primary></indexterm>
+       <indexterm><primary>Fonts</primary>
+         <secondary>LCD screen</secondary></indexterm>
+
+       <para>One last point: with an LCD screen, sub-pixel sampling may be
+        desired.  This basically treats the (horizontally separated)
+        red, green and blue components separately to improve the horizontal
+        resolution; the results can be dramatic.  To enable this, add the
+        line somewhere in the <filename>local.conf</filename> file:</para>
+
+       <programlisting>
+         &lt;match target="font"&gt;
+             &lt;test qual="all" name="rgba"&gt;
+                 &lt;const&gt;unknown&lt;/const&gt;
+             &lt;/test&gt;
+             &lt;edit name="rgba" mode="assign"&gt;
+                 &lt;const&gt;rgb&lt;/const&gt;
+             &lt;/edit&gt;
+         &lt;/match&gt;
+       </programlisting>
+
+       <note><para>Depending on the sort of display,
+	 <literal>rgb</literal> may need to be changed to <literal>bgr</literal>,
+	 <literal>vrgb</literal> or <literal>vbgr</literal>: experiment and
+	 see which works best.</para></note>
+
+       <indexterm>
+	 <primary>Mozilla</primary>
+         <secondary>disabling anti-aliased fonts</secondary>
+       </indexterm>
+
+       <para>Anti-aliasing should be enabled the next time the X
+         server is started.  However, programs must know how to take
+         advantage of it.  At present, the Qt toolkit does,
+         so the entire <application>KDE</application> environment can
+         use anti-aliased fonts.
+         GTK+ and 
+         <application>GNOME</application> can also be made to use 
+         anti-aliasing via the <quote>Font</quote> capplet (see <xref
+         linkend="x11-wm-gnome-antialias"> for details).  By default,
+         <application>Mozilla</application> 1.2 and greater will 
+         automatically use anti-aliasing. To disable this, rebuild 
+         <application>Mozilla</application> with the
+         <makevar>-DWITHOUT_XFT</makevar> flag.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="x-xdm">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Seth</firstname>
+          <surname>Kingsley</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+      </authorgroup>
+    </sect1info>
+    <title>The X Display Manager</title>
+    <sect2>
+      <title>Overview</title>
+
+      <indexterm><primary>X Display Manager</primary></indexterm>
+      <para>The X Display Manager (<application>XDM</application>) is
+        an optional part of the X Window System that is used for login
+        session management.  This is useful for several types of
+        situations, including minimal <quote>X Terminals</quote>,
+        desktops, and large network display
+        servers.  Since the X Window System is network and protocol
+        independent, there are a wide variety of possible configurations
+        for running X clients and servers on different machines
+        connected by a network.  <application>XDM</application> provides
+        a graphical interface for choosing which display server to
+        connect to, and entering authorization information such as a
+        login and password combination.</para>
+
+      <para>Think of <application>XDM</application> as
+        providing the same functionality to the user as the
+        &man.getty.8; utility (see <xref linkend="term-config"> for
+          details).  That is, it performs system logins to the display
+          being connected to and then runs a session manager on behalf of
+          the user (usually an X window
+          manager).  <application>XDM</application> then waits for this
+          program to exit, signaling that the user is done and should be
+          logged out of the display.  At this point,
+          <application>XDM</application> can display the login and display
+          chooser screens for the next user to login.</para>
+    </sect2>
+
+    <sect2>
+      <title>Using XDM</title>
+
+      <para>The <application>XDM</application> daemon program is
+        located in <filename>/usr/X11R6/bin/xdm</filename>.  This program
+        can be run at any time as <username>root</username> and it will
+        start managing the X display on the local machine.  If
+        <application>XDM</application> is to be run every
+        time the machine boots up, a convenient way to do this is by
+        adding an entry to <filename>/etc/ttys</filename>.  For more
+        information about the format and usage of this file, see <xref
+        linkend="term-etcttys">.  There is a line in the default
+        <filename>/etc/ttys</filename> file for running the
+        <application>XDM</application> daemon on a virtual terminal:</para>
+
+      <screen>ttyv8   "/usr/X11R6/bin/xdm -nodaemon"  xterm   off secure</screen>
+
+      <para>By default this entry is disabled; in order to enable it
+        change field 5 from <literal>off</literal> to
+        <literal>on</literal> and restart &man.init.8; using the
+        directions in <xref linkend="term-hup">.  The first field, the
+        name of the terminal this program will manage, is
+        <literal>ttyv8</literal>.  This means that
+        <application>XDM</application> will start running on the 9th
+        virtual terminal.</para>
+    </sect2>
+
+    <sect2>
+      <title>Configuring XDM</title>
+
+      <para>The <application>XDM</application> configuration directory
+        is located in <filename>/usr/X11R6/lib/X11/xdm</filename>.  In
+        this directory there are several files used to change the
+        behavior and appearance of
+        <application>XDM</application>.  Typically these files will
+        be found:</para>
+
+        <informaltable frame="none" pgwide="1">
+          <tgroup cols="2">
+            <thead>
+              <row>
+                <entry>File</entry>
+                <entry>Description</entry>
+              </row>
+            </thead>
+
+            <tbody>
+              <row>
+                <entry><filename>Xaccess</filename></entry>
+                <entry>Client authorization ruleset.</entry>
+              </row>
+
+              <row>
+                <entry><filename>Xresources</filename></entry>
+                <entry>Default X resource values.</entry>
+              </row>
+
+              <row>
+                <entry><filename>Xservers</filename></entry>
+                <entry>List of remote and local displays to manage.</entry>
+              </row>
+
+              <row>
+                <entry><filename>Xsession</filename></entry>
+                <entry>Default session script for logins.</entry>
+              </row>
+
+              <row>
+                <entry><filename>Xsetup_</filename>*</entry>
+                <entry>Script to launch applications before the login
+                  interface.</entry>
+              </row>
+
+              <row>
+                <entry><filename>xdm-config</filename></entry>
+                <entry>Global configuration for all displays running on
+                  this machine.</entry>
+              </row>
+
+              <row>
+                <entry><filename>xdm-errors</filename></entry>
+                <entry>Errors generated by the server program.</entry>
+              </row>
+
+              <row>
+                <entry><filename>xdm-pid</filename></entry>
+                <entry>The process ID of the currently running XDM.</entry>
+              </row>
+            </tbody>
+          </tgroup>
+        </informaltable>
+
+      <para>Also in this directory are a few scripts and programs used
+        to set up the desktop when <application>XDM</application> is
+        running.  The purpose of each of these files will be briefly
+        described.  The exact syntax and usage of all of these files is
+        described in &man.xdm.1;.</para>
+
+      <para>The default configuration is a simple rectangular login
+        window with the hostname of the machine displayed at the top in
+        a large font and <quote>Login:</quote> and
+        <quote>Password:</quote> prompts below.  This is a good starting
+        point for changing the look and feel of
+        <application>XDM</application> screens.</para>
+
+      <sect3>
+        <title>Xaccess</title>
+
+        <para>The protocol for connecting to
+          <application>XDM</application> controlled displays is called
+          the X Display Manager Connection Protocol (XDMCP).  This file
+          is a ruleset for controlling XDMCP connections from remote
+	  machines.  It is ignored unless the <filename>xdm-config</filename>
+	  is changed to listen for remote connections.  By default, it does
+	  not allow any clients to connect.</para>
+      </sect3>
+
+      <sect3>
+        <title>Xresources</title>
+        <para>This is an application-defaults file for the display
+          chooser and the login screens.  This is where the appearance
+          of the login program can be modified.  The format is identical
+          to the app-defaults file described in the
+	  X11 documentation.</para>
+      </sect3>
+
+      <sect3>
+        <title>Xservers</title>
+        <para>This is a list of the remote displays the chooser should
+          provide as choices.</para>
+      </sect3>
+
+      <sect3>
+        <title>Xsession</title>
+        <para>This is the default session script for
+          <application>XDM</application> to run after a user has logged
+          in.  Normally each user will have a customized session script
+          in <filename>~/.xsession</filename> that overrides this
+          script.</para>
+      </sect3>
+
+      <sect3>
+        <title>Xsetup_*</title>
+        <para>These will be run automatically before displaying the
+          chooser or login interfaces.  There is a script for each
+          display being used, named <filename>Xsetup_</filename> followed
+          by the local display number (for instance
+          <filename>Xsetup_0</filename>).  Typically these scripts will
+          run one or two programs in the background such as
+          <command>xconsole</command>.</para>
+      </sect3>
+
+      <sect3>
+        <title>xdm-config</title>
+        <para>This contains settings in the form of app-defaults
+          that are applicable to every display that this installation
+          manages.</para>
+      </sect3>
+
+      <sect3>
+        <title>xdm-errors</title>
+        <para>This contains the output of the X servers that
+          <application>XDM</application> is trying to run.  If a display
+          that <application>XDM</application> is trying to start hangs
+          for some reason, this is a good place to look for error
+          messages.  These messages are also written to the user's
+          <filename>~/.xsession-errors</filename> file on a per-session
+          basis.</para>
+      </sect3>
+    </sect2>
+
+    <sect2>
+      <title>Running a Network Display Server</title>
+
+      <para>In order for other clients to connect to the display
+        server, edit the access control rules, and enable the connection
+        listener.  By default these are set to conservative values.
+        To make <application>XDM</application> listen for connections,
+        first comment out a line in the <filename>xdm-config</filename>
+        file:</para>
+
+      <screen>! SECURITY: do not listen for XDMCP or Chooser requests
+! Comment out this line if you want to manage X terminals with xdm
+DisplayManager.requestPort:     0</screen>
+
+      <para>and then restart <application>XDM</application>.  Remember that
+        comments in app-defaults files begin with a <quote>!</quote>
+        character, not the usual <quote>#</quote>.  More strict
+        access controls may be desired.  Look at the example
+        entries in <filename>Xaccess</filename>, and refer to the
+        &man.xdm.1; manual page.</para>
+    </sect2>
+
+     <sect2>
+        <title>Replacements for XDM</title>
+
+        <para>Several replacements for the default
+          <application>XDM</application> program exist.  One of them,
+          <application>kdm</application> (bundled with
+          <application>KDE</application>) is described later in this
+          chapter.  The <application>kdm</application> display manager offers many visual
+          improvements and cosmetic frills, as well as the
+          functionality to allow users to choose their window manager
+          of choice at login time.</para>
+     </sect2>
+  </sect1>
+
+  <sect1 id="x11-wm">
+    <sect1info>
+      <authorgroup>
+        <author>
+          <firstname>Valentino</firstname>
+          <surname>Vaschetto</surname>
+          <contrib>Contributed by </contrib>
+        </author>
+        <!-- June 2001 -->
+      </authorgroup>
+    </sect1info>
+
+    <title>Desktop Environments</title>
+
+    <para>This section describes the different desktop environments
+      available for X on FreeBSD.  A <quote>desktop environment</quote>
+      can mean anything ranging from a simple window manager to a
+      complete suite of desktop applications, such as
+      <application>KDE</application> or <application>GNOME</application>.
+    </para>
+
+    <sect2 id="x11-wm-gnome">
+      <title>GNOME</title>
+
+      <sect3 id="x11-wm-gnome-about">
+        <title>About GNOME</title>
+
+        <indexterm><primary>GNOME</primary></indexterm>
+        <para><application>GNOME</application> is a user-friendly
+          desktop environment that enables users to easily use and
+          configure their computers.  <application>GNOME</application>
+          includes a panel (for starting applications and displaying
+          status), a desktop (where data and applications can be
+          placed), a set of standard desktop tools and applications, and
+          a set of conventions that make it easy for applications to
+          cooperate and be consistent with each other.  Users of other
+          operating systems or environments should feel right at home
+          using the powerful graphics-driven environment that
+          <application>GNOME</application> provides.  More
+	  information regarding <application>GNOME</application> on
+	  FreeBSD can be found on the <ulink
+	  url="http://www.FreeBSD.org/gnome">FreeBSD GNOME
+	  Project</ulink>'s web site.  The web site also contains fairly
+	  comprehensive FAQs about installing, configuring, and managing
+	  <application>GNOME</application>.</para>
+      </sect3>
+
+      <sect3 id="x11-wm-gnome-install">
+        <title>Installing GNOME</title>
+
+        <para>The easiest way to install
+          <application>GNOME</application> is through the
+          <quote>Desktop Configuration</quote> menu during the FreeBSD
+	  installation process as described in <xref
+	  linkend="default-desktop"> of Chapter&nbsp;2.  It can also
+          be easily installed from a package or the ports
+          collection:</para>
+
+        <para>To install the <application>GNOME</application> package
+          from the network, simply type:</para>
+
+        <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen>
+
+        <para>To build <application>GNOME</application> from source, use
+          the ports tree:</para>
+
+        <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+        <para>Once <application>GNOME</application> is installed,
+          the X server must be told to start
+          <application>GNOME</application> instead of a default window
+          manager.</para>
+
+        <para>The easiest way to start
+          <application>GNOME</application> is with
+          <application>GDM</application>, the GNOME Display Manager.
+          <application>GDM</application>, which is installed as a part
+          of the <application>GNOME</application> desktop (but is
+          disabled by default), can be enabled by adding
+          <literal>gdm_enable="YES"</literal> to
+          <filename>/etc/rc.conf</filename>.  Once you have rebooted,
+          <application>GNOME</application> will start automatically
+          once you log in &mdash; no further configuration is
+          necessary.</para>
+
+        <para><application>GNOME</application> may also be started
+	  from the command-line by properly configuring a file named
+	  <filename>.xinitrc</filename>.
+          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 the configuration file,
+          then it is enough simply to 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 an older 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" &gt; ~/.xsession</userinput>
+&prompt.user; <userinput>echo "/usr/X11R6/bin/gnome-session" &gt;&gt; ~/.xsession</userinput>
+&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen>
+
+        <para>Yet another option is to configure the display manager to
+          allow choosing the window manager at login time; the section on
+          <link linkend="x11-wm-kde-details">KDE details</link>
+          explains how to do this for <application>kdm</application>, the
+          display manager of <application>KDE</application>.</para>
+      </sect3>
+
+      <sect3 id="x11-wm-gnome-antialias">
+        <title>Anti-aliased Fonts with GNOME</title>
+
+        <indexterm><primary>GNOME</primary>
+          <secondary>anti-aliased fonts</secondary></indexterm>
+	<para>X11
+	  supports anti-aliasing via its <quote>RENDER</quote> extension.
+	  GTK+ 2.0 and greater (the toolkit used by
+	  <application>GNOME</application>) can make use of this
+	  functionality.  Configuring anti-aliasing is described in
+	  <xref linkend="antialias">.  So, with up-to-date software,
+	  anti-aliasing is possible within the
+	  <application>GNOME</application> desktop.  Just go to
+	  <menuchoice>
+	    <guimenu>Applications</guimenu>
+	    <guisubmenu>Desktop Preferences</guisubmenu>
+	    <guimenuitem>Font</guimenuitem></menuchoice>, and select either
+	  <guibutton>Best shapes</guibutton>, 
+	  <guibutton>Best contrast</guibutton>, or
+	  <guibutton>Subpixel smoothing (LCDs)</guibutton>.  For a
+	  GTK+ application that is not part of the 
+	  <application>GNOME</application> desktop, set the
+	  environment variable <varname>GDK_USE_XFT</varname> to
+	  <literal>1</literal> before launching the program.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="x11-wm-kde">
+      <title>KDE</title>
+
+      <indexterm><primary>KDE</primary></indexterm>
+      <sect3 id="x11-wm-kde-about">
+        <title>About KDE</title>
+
+        <para><application>KDE</application> is an easy to use
+          contemporary desktop environment.  Some of the things that
+          <application>KDE</application> brings to the user are:</para>
+
+        <itemizedlist>
+          <listitem>
+	    <para>A beautiful contemporary desktop</para>
+	  </listitem>
+
+          <listitem>
+	    <para>A desktop exhibiting complete network transparency</para>
+	  </listitem>
+
+          <listitem>
+	    <para>An integrated help system allowing for convenient,
+	      consistent access to help on the use of the
+	      <application>KDE</application> desktop and its
+	      applications</para>
+	  </listitem>
+
+          <listitem>
+	    <para>Consistent look and feel of all
+              <application>KDE</application> applications</para>
+	  </listitem>
+
+          <listitem>
+	    <para>Standardized menu and toolbars, keybindings, color-schemes,
+	      etc.</para>
+	  </listitem>
+
+          <listitem>
+	    <para>Internationalization: <application>KDE</application>
+              is available in more than 40 languages</para>
+	  </listitem>
+
+          <listitem>
+	    <para>Centralized consisted dialog driven desktop
+	      configuration</para>
+	  </listitem>
+
+          <listitem>
+	    <para>A great number of useful
+              <application>KDE</application> applications</para>
+	  </listitem>
+        </itemizedlist>
+
+        <para><application>KDE</application> comes with a web browser called
+          <application>Konqueror</application>, which represents
+          a solid competitor to other existing web browsers on &unix;
+          systems.  More information on <application>KDE</application>
+          can be found on the <ulink url="http://www.kde.org/">KDE
+          website</ulink>.  For FreeBSD specific information and
+	  resources on <application>KDE</application>, consult
+	  the <ulink url="http://freebsd.kde.org/">FreeBSD-KDE
+	  team</ulink>'s website.</para>
+      </sect3>
+
+      <sect3 id="x11-wm-kde-install">
+        <title>Installing KDE</title>
+
+        <para>Just as with <application>GNOME</application> or any
+          other desktop environment, the easiest way to install
+          <application>KDE</application> is through the <quote>Desktop
+          Configuration</quote> menu during the FreeBSD installation
+	  process as described in <xref linkend="default-desktop"> of Chapter
+	  2.  Once again, the software can be easily installed from a package
+	  or from the Ports Collection:</para>
+
+        <para>To install the <application>KDE</application> package
+          from the network, simply type:</para>
+
+        <screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen>
+
+	<para>&man.pkg.add.1; will automatically fetch the latest version
+	  of the application.</para>
+
+        <para>To build <application>KDE</application> from source,
+          use the ports tree:</para>
+
+        <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+        <para>After <application>KDE</application> has been installed,
+          the X server must be told to launch this application
+          instead of the default window manager.  This is accomplished
+          by editing the <filename>.xinitrc</filename> file:</para>
+
+        <screen>&prompt.user; <userinput>echo "exec startkde" &gt; ~/.xinitrc</userinput></screen>
+
+	<para>Now, whenever the X Window System is invoked with
+	  <command>startx</command>,
+          <application>KDE</application> will be the desktop.</para>
+
+        <para>If a display manager such as
+          <application>XDM</application> is being used, the
+          configuration is slightly different.  Edit the
+          <filename>.xsession</filename> file instead.  Instructions
+          for <application>kdm</application> are described later in
+          this chapter.</para>
+      </sect3>
+    </sect2>
+
+    <sect2 id="x11-wm-kde-details">
+        <title>More Details on KDE</title>
+
+        <para>Now that <application>KDE</application> is installed on
+          the system, most things can be discovered through the
+          help pages, or just by pointing and clicking at various menus.
+          &windows; or &mac; users will feel quite at home.</para>
+
+        <para>The best reference for <application>KDE</application> is
+          the on-line documentation.  <application>KDE</application>
+          comes with its own web browser,
+          <application>Konqueror</application>, dozens of useful
+          applications, and extensive documentation.  The remainder of
+          this section discusses the technical items that are
+          difficult to learn by random exploration.</para>
+
+      <sect3 id="x11-wm-kde-kdm">
+        <title>The KDE Display Manager</title>
+
+        <indexterm><primary>KDE</primary>
+          <secondary>display manager</secondary></indexterm>
+        <para>An administrator of a multi-user system may wish to have
+          a graphical login screen to welcome users.
+          <link linkend="x-xdm">XDM</link> can be
+          used, as described earlier.  However,
+          <application>KDE</application> includes an
+          alternative, <application>kdm</application>, which is designed
+          to look more attractive and include more login-time options.
+          In particular, users can easily choose (via a menu) which
+          desktop environment (<application>KDE</application>,
+          <application>GNOME</application>, or something else) to run
+          after logging on.</para>
+
+        <para>To enable <application>kdm</application>, the
+	  <literal>ttyv8</literal> entry in <filename>/etc/ttys</filename>
+	  has to be adapted.  The line should look as follows:</para>
+
+	<programlisting>ttyv8 "/usr/local/bin/kdm -nodaemon" xterm on secure</programlisting>
+      </sect3>
+
+     </sect2>
+
+     <sect2 id="x11-wm-xfce">
+         <title>XFce</title>
+       <sect3 id="x11-wm-xfce-about">
+         <title>About XFce</title>
+
+        <para><application>XFce</application> is a desktop environment
+          based on the GTK+
+          toolkit used by <application>GNOME</application>, but is much
+          more lightweight and meant for those who want a simple,
+          efficient desktop which is nevertheless easy to use and
+          configure.  Visually, it looks very much like
+          <application>CDE</application>, found on commercial &unix;
+          systems.  Some of <application>XFce</application>'s features
+          are:</para>
+
+         <itemizedlist>
+           <listitem>
+	     <para>A simple, easy-to-handle desktop</para>
+           </listitem>
+
+           <listitem>
+	     <para>Fully configurable via mouse, with drag and
+               drop, etc </para>
+           </listitem>
+
+           <listitem>
+	     <para>Main panel similar to <application>CDE</application>, with
+	       menus, applets and applications launchers</para>
+           </listitem>
+
+           <listitem>
+	     <para>Integrated window manager, file manager, sound manager,
+	       <application>GNOME</application> compliance module, and other
+	       things</para>
+           </listitem>
+
+           <listitem>
+	     <para>Themeable (since it uses GTK+)</para>
+           </listitem>
+
+           <listitem>
+	     <para>Fast, light and efficient: ideal for older/slower machines
+	       or machines with memory limitations</para>
+           </listitem>
+         </itemizedlist>
+
+         <para>More information on <application>XFce</application>
+          can be found on the <ulink url="http://www.xfce.org/">XFce
+            website</ulink>.</para>
+       </sect3>
+
+       <sect3 id="x11-wm-xfce-install">
+         <title>Installing XFce</title>
+
+        <para>A binary package for <application>XFce</application>
+          exists (at the time of writing).  To install, simply type:</para>
+
+        <screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen>
+
+        <para>Alternatively, to build from source, use the ports
+          collection:</para>
+
+        <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+        <para>Now, tell the X server to launch
+         <application>XFce</application> the next time X is started.
+         Simply type this:</para>
+
+        <screen>&prompt.user; <userinput>echo "/usr/X11R6/bin/startxfce4" &gt; ~/.xinitrc</userinput></screen>
+
+        <para>The next time X is started,
+          <application>XFce</application> will be the desktop.
+          As before, if a display manager like
+          <application>XDM</application> is being used, create an
+          <filename>.xsession</filename>, as described in the
+          section on <link linkend="x11-wm-gnome">GNOME</link>, but
+          with the <filename>/usr/X11R6/bin/startxfce4</filename>
+          command; or, configure the display manager to allow
+          choosing a desktop at login time, as explained in
+          the section on <link linkend="x11-wm-kde-kdm">kdm</link>.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+</chapter>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->