Attachment 34384 Details for Bug 55883 – file.diff

[patch] file.diff

file.diff (text/plain), 261.34 KB, created by Gea-Suan Lin on 2003-08-23 00:10:15 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Gea-Suan Lin

Created: 2003-08-23 00:10:15 UTC

Size: 261.34 KB

patch

obsolete

>--- /usr/doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml	Mon Jul 21 21:35:50 2003
>+++ chapter.sgml	Sat Aug 23 07:00:11 2003
>@@ -1,6773 +0,0 @@
>-
>-
>-<chapter id="advanced-networking">
>-  <title>Advanced Networking</title>
>-
>-  <sect1 id="advanced-networking-synopsis">
>-    <title>Synopsis</title>
>-
>-    <para>This chapter will cover some of the more frequently used network
>-      services on Unix systems.  We will cover how to define, setup, test and
>-      maintain all of the network services that FreeBSD utilizes.  In addition,
>-      there have been example configuration files included throughout this
>-      chapter for you to benefit from.</para>
>-
>-    <para>After reading this chapter, you will know:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>The basics of gateways and routes.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to make FreeBSD act as a bridge.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup a network filesystem.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup network booting on a diskless machine.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup a network information server for sharing user
>-	  accounts.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup automatic network settings using DHCP.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup a domain name server.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to synchronize the time and date, and setup a
>-	  time server, with the NTP protocol.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup network address translation.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to manage the <command>inetd</command> daemon.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to connect two computers via PLIP.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>How to setup IPv6 on a FreeBSD machine.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>Before reading this chapter, you should:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Understand the basics of the <filename>/etc/rc</filename> scripts.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Be familiar with basic network terminology.</para>
>-      </listitem>
>-    </itemizedlist>
>-  </sect1>
>-
>-  <sect1 id="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 <literal>224</literal>) deals
>-	with multicasting, which will be covered in another section.</para>
>-
>-      <para>Finally, various attributes of each route can be seen in
>-	the <literal>Flags</literal> column.  Below is a short table
>-	of some of these flags and their meanings:</para>
>-
>-      <informaltable frame="none">
>-	<tgroup cols="2">
>-	  <tbody>
>-	    <row>
>-	      <entry>U</entry>
>-	      <entry>Up: The route is active.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>H</entry>
>-	      <entry>Host: The route destination is a single host.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>G</entry>
>-	      <entry>Gateway: Send anything for this destination on to this
>-		remote system, which will figure out from there where to send
>-		it.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>S</entry>
>-	      <entry>Static: This route was configured manually, not
>-		automatically generated by the system.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>C</entry>
>-	      <entry>Clone: Generates a new route based upon this route for
>-		machines we connect to.  This type of route is normally used
>-		for local networks.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>W</entry>
>-	      <entry>WasCloned: Indicated a route that was auto-configured
>-		based upon a local area network (Clone) route.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>L</entry>
>-	      <entry>Link: Route involves references to Ethernet
>-		hardware.</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </informaltable>
>-    </sect2>
>-
>-    <sect2 id="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>
>-
>-      <literallayout>
>-[Local2]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
>-      </literallayout>
>-
>-      <para>The hosts <hostid>Local1</hostid> and
>-	<hostid>Local2</hostid> are at your site.
>-	<hostid>Local1</hostid> is connected to an ISP via a dial up
>-	PPP connection.  This PPP server computer is connected through
>-	a local area network to another gateway computer through an
>-	external interface to the ISPs Internet feed.</para>
>-
>-      <para>The default routes for each of your machines will be:</para>
>-
>-      <informaltable frame="none">
>-	<tgroup cols="3">
>-	  <thead>
>-	    <row>
>-	      <entry>Host</entry>
>-	      <entry>Default Gateway</entry>
>-	      <entry>Interface</entry>
>-	    </row>
>-	  </thead>
>-
>-	  <tbody>
>-	    <row>
>-	      <entry>Local2</entry>
>-	      <entry>Local1</entry>
>-	      <entry>Ethernet</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>Local1</entry>
>-	      <entry>T1-GW</entry>
>-	      <entry>PPP</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </informaltable>
>-
>-      <para>A common question is <quote>Why (or how) would we set
>-	the <hostid>T1-GW</hostid> to be the default gateway for
>-	<hostid>Local1</hostid>, rather than the ISP server it is
>-	connected to?</quote>.</para>
>-
>-      <para>Remember, since the PPP interface is using an address on the ISP's
>-	local network for your side of the connection, routes for any other
>-	machines on the ISP's local network will be automatically generated.
>-	Hence, you will already know how to reach the <hostid>T1-GW</hostid>
>-	machine, so there is no need for the intermediate step
>-	of sending traffic to the ISP server.</para>
>-
>-      <para>As a final note, it is common to use the address <hostid
>-	  role="ipaddr">X.X.X.1</hostid> as the gateway address for your local
>-	network.  So (using the same example), if your local class-C address
>-	space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
>-	using <hostid role="ipaddr">10.9.9</hostid> then the default routes
>-	would be:</para>
>-
>-      <informaltable frame="none">
>-	<tgroup cols="2">
>-	  <thead>
>-	    <row>
>-	      <entry>Host</entry>
>-	      <entry>Default Route</entry>
>-	    </row>
>-	  </thead>
>-	  <tbody>
>-	    <row>
>-	      <entry>Local2 (10.20.30.2)</entry>
>-	      <entry>Local1 (10.20.30.1)</entry>
>-	    </row>
>-	    <row>
>-	      <entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
>-	      <entry>T1-GW (10.9.9.1)</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </informaltable>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Dual Homed Hosts</title>
>-      <indexterm><primary>dual homed hosts</primary></indexterm>
>-      <para>There is one other type of configuration that we should cover, and
>-	that is a host that sits on two different networks.  Technically, any
>-	machine functioning as a gateway (in the example above, using a PPP
>-	connection) counts as a dual-homed host.  But the term is really only
>-	used to refer to a machine that sits on two local-area
>-	networks.</para>
>-
>-      <para>In one case, the machine has two Ethernet cards, each
>-	having an address on the separate subnets.  Alternately, the
>-	machine may only have one Ethernet card, and be using
>-	&man.ifconfig.8; aliasing.  The former is used if two
>-	physically separate Ethernet networks are in use, the latter
>-	if there is one physical network segment, but two logically
>-	separate subnets.</para>
>-
>-      <para>Either way, routing tables are set up so that each subnet knows
>-	that this machine is the defined gateway (inbound route) to the other
>-	subnet.  This configuration, with the machine acting as a router
>-	between the two subnets, is often used when we need to implement
>-	packet filtering or firewall security in either or both
>-	directions.</para>
>-
>-      <para>If you want this machine to actually forward packets
>-        between the two interfaces, you need to tell FreeBSD to enable
>-        this ability.</para>
>-    </sect2>
>-
>-    <sect2 id="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 gated 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>
>-
>-      <para>Even when FreeBSD is configured in this way, it does not
>-	completely comply with the Internet standard requirements for
>-	routers.  It comes close enough for ordinary use,
>-	however.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Routing Propagation</title>
>-      <indexterm><primary>routing propagation</primary></indexterm>
>-      <para>We have already talked about how we define our routes to the
>-	outside world, but not about how the outside world finds us.</para>
>-
>-      <para>We already know that routing tables can be set up so that all
>-	traffic for a particular address space (in our examples, a class-C
>-	subnet) can be sent to a particular host on that network, which will
>-	forward the packets inbound.</para>
>-
>-      <para>When you get an address space assigned to your site, your service
>-	provider will set up their routing tables so that all traffic for your
>-	subnet will be sent down your PPP link to your site.  But how do sites
>-	across the country know to send to your ISP?</para>
>-
>-      <para>There is a system (much like the distributed DNS information) that
>-	keeps track of all assigned address-spaces, and defines their point of
>-	connection to the Internet Backbone.  The <quote>Backbone</quote> are
>-	the main trunk lines that carry Internet traffic across the country,
>-	and around the world.  Each backbone machine has a copy of a master
>-	set of tables, which direct traffic for a particular network to a
>-	specific backbone carrier, and from there down the chain of service
>-	providers until it reaches your network.</para>
>-
>-      <para>It is the task of your service provider to advertise to the
>-	backbone sites that they are the point of connection (and thus the
>-	path inward) for your site.  This is known as route
>-	propagation.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Troubleshooting</title>
>-      <indexterm>
>-        <primary><command>traceroute</command></primary>
>-      </indexterm>
>-      <para>Sometimes, there is a problem with routing propagation, and some
>-	sites are unable to connect to you.  Perhaps the most useful command
>-	for trying to figure out where routing is breaking down is the
>-	  &man.traceroute.8; command.  It is equally useful if you cannot seem
>-	to make a connection to a remote machine (i.e. &man.ping.8;
>-	fails).</para>
>-
>-      <para>The &man.traceroute.8; command is run with the name of the remote
>-	host you are trying to connect to.  It will show the gateway hosts
>-	along the path of the attempt, eventually either reaching the target
>-	host, or terminating because of a lack of connection.</para>
>-
>-      <para>For more information, see the manual page for
>-	  &man.traceroute.8;.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Multicast Routing</title>
>-      <indexterm>
>-	<primary>multicast</primary>
>-	<secondary>options 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 DVMRP via
>-	<filename>/etc/mrouted.conf</filename>.  More details on
>-	multicast configuration may be found in the man pages for
>-	mrouted.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="network-wireless">
>-    <sect1info>
>-      <authorgroup>
>-        <author>
>-          <firstname>Eric</firstname>
>-          <surname>Anderson</surname>
>-          <contrib>Written by </contrib>
>-        </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>Introduction</title>
>-      <para>It can be very useful to be able to use a computer without the
>-      annoyance of having a network cable attached at all times.  FreeBSD can
>-      be used as a wireless client, and even as a wireless <quote>access
>-      point</quote>.</para>
>-   </sect2>
>-
>-   <sect2>
>-     <title>Wireless Modes of Operation</title>
>-     <para>There are two different ways to configure 802.11 wireless devices:
>-      BSS and IBSS.</para>
>-
>-     <sect3>
>-       <title>BSS Mode</title>
>-       <para>BSS mode is the mode that typically is used.  BSS mode is
>-        also called infrastructure mode.  In this mode, a number of
>-        wireless access points are connected to a wired network.  Each
>-        wireless network has its own name.  This name is called the
>-        SSID of the network.</para>
>-
>-       <para>Wireless clients connect to these wireless access
>-        points. The IEEE 802.11 standard defines the protocol that
>-        wireless networks use to connect.  A wireless client can be
>-        tied to a specific network, when a SSID is set.  A wireless
>-        client can also attach to any network by not explicitly
>-        setting a SSID.</para>
>-     </sect3>
>-
>-     <sect3>
>-       <title>IBSS Mode</title>
>-       <para>IBSS mode, also called ad-hoc mode, is designed for point
>-         to point connections.  There are actually two types of ad-hoc
>-         mode.  One is IBSS mode, also called ad-hoc or IEEE ad-hoc
>-         mode.  This mode is defined by the IEEE 802.11 standards.
>-         The second is called demo ad-hoc mode or Lucent ad-hoc mode
>-         (and sometimes, confusingly, ad-hoc mode).  This is the old,
>-         pre-802.11 ad-hoc mode and should only be used for legacy
>-	 installations.  We will not cover either of the ad-hoc modes
>-         further.</para>
>-     </sect3>
>-   </sect2>
>-
>-   <sect2>
>-     <title>Infrastructure Mode</title>
>-     <sect3>
>-       <title>Access Points</title>
>-
>-       <para>Access points are wireless networking devices that allow
>-        one or more wireless clients to use the device as a central
>-        hub.  When using an access point, all clients communicate
>-        through the access point.  Multiple access points are often
>-        used to cover a complete area such as a house, business, or
>-        park with a wireless network.</para>
>-
>-       <para>Access points typically have multiple network
>-       connections: the wireless card, and one or more wired Ethernet
>-       adapters for connection to the rest of the network.
>-       </para>
>-
>-       <para>Access points can either be purchased prebuilt, or you
>-        can build your own with FreeBSD and a supported wireless card.
>-        Several vendors make wireless access points and wireless cards
>-        with various features.</para>
>-     </sect3>
>-
>-     <sect3>
>-       <title>Building a FreeBSD Access Point</title>
>-       <indexterm><primary>wireless networking</primary>
>-         <secondary>access point</secondary>
>-       </indexterm>
>-
>-       <sect4><title>Requirements</title>
>-
>-         <para>In order to set up a wireless access point with
>-          FreeBSD, you need to have a compatible wireless card.
>-          Currently, only cards with the Prism chipset are
>-          supported. You will also need a wired network card that is
>-          supported by FreeBSD (this should not be difficult to find,
>-          FreeBSD supports a lot of different devices).  For this
>-          guide, we will assume you want to &man.bridge.4; all traffic
>-          between the wireless device and the network attached to the
>-          wired network card.</para>
>-
>-	 <para>The hostap functionality that FreeBSD uses to implement
>-           the access point works best with certain versions of
>-           firmware.  Prism 2 cards should use firmware version 1.3.4
>-           or newer.  Prism 2.5 and Prism 3 cards should use firmware
>-           1.4.9.  Older versions of the firmware way or may not
>-           function correctly.  At this time, the only way to update
>-           cards is with windows firmware update utilities available
>-           from your card's manufacturer.</para>
>-       </sect4>
>-
>-       <sect4>
>-         <title>Setting It Up</title>
>-         <para>First, make sure your system can see the wireless card:</para>
>-         <screen>&prompt.root; <userinput>ifconfig -a</userinput>
>-wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>-        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
>-        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
>-        ether 00:09:2d:2d:c9:50
>-        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
>-        status: no carrier
>-        ssid ""
>-        stationname "FreeBSD Wireless node"
>-        channel 10 authmode OPEN powersavemode OFF powersavesleep 100
>-        wepmode OFF weptxkey 1</screen>
>-
>-         <para>Do not worry about the details now, just make sure it shows you
>-          something to indicate you have a wireless card installed.
>-	  If you have trouble seeing the wireless interface, and you
>-	  are using a PC Card, you may want to check out
>-	  &man.pccardc.8; and &man.pccardd.8; manual pages for more
>-	  information.</para>
>-
>-         <para>Next, you will need to load a module in order to get
>-          the bridging part of FreeBSD ready for the access point.  In
>-          order to load the &man.bridge.4; module, simply run the
>-          following command:</para>
>-
>-         <screen>&prompt.root; <userinput>kldload bridge</userinput></screen>
>-
>-         <para>It should not have produced any errors when loading the
>-          module.  If it did, you may need to compile the
>-          &man.bridge.4; code into your kernel.  The <link
>-          linkend="network-bridging">Bridging</link> section of the handbook
>-          should be able to help you accomplish that task.</para>
>-
>-         <para>Now that you have the bridging stuff done, we need to
>-          tell the FreeBSD kernel which interfaces to bridge together.
>-          We do that by using &man.sysctl.8;:</para>
>-
>-         <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput>
>-&prompt.root; <userinput>sysctl net.link.ether.bridge_cfg="wi0 xl0"</userinput>
>-&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>
>-
>-         <para>Now it is time for the wireless card setup.</para>
>-         <para>The following command will set the card into an access point:</para>
>-
>-         <screen>
>-&prompt.root; <userinput>ifconfig wi0 ssid my_net channel 11 media DS/11Mbps mediaopt hostap up stationname "FreeBSD AP"</userinput>
>-         </screen>
>-
>-         <para>The &man.ifconfig.8; line brings the
>-	  <devicename>wi0</devicename> interface up, sets its SSID to
>-	  <literal>my_net</literal>, and sets the station name to
>-	  <literal>FreeBSD AP</literal>.  The <option>media
>-	  DS/11Mbps</option> sets the card into 11Mbps mode and is
>-	  needed for any <option>mediaopt</option> to take effect.
>-	  The <option>mediaopt hostap</option> option places the
>-	  interface into access point mode.  The <option>channel
>-	  11</option> option sets the 802.11b channel to use.  The
>-	  &man.wicontrol.8; man page has valid channel options for
>-	  your regulatory domain.
>-         </para>
>-
>-         <para>Now you should have a complete functioning access point
>-          up and running.  You are encouraged to read
>-          &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for
>-          further information.
>-         </para>
>-
>-         <para>It is also suggested that you read the section on encryption that follows.</para>
>-       </sect4>
>-
>-       <sect4>
>-         <title>Status Information</title>
>-	 <para>Once the access point is configured and operational,
>-	   operators will want to see the clients that are associated
>-	   with the access point.  At any time, the operator may type:</para>
>-
>-         <screen>&prompt.root; <userinput>wicontrol -l</userinput>
>-1 station:
>-00:09:b7:7b:9d:16  asid=04c0, flags=3&lt;ASSOC,AUTH&gt;, caps=1&lt;ESS&gt;, rates=f&lt;1M,2M,5.5M,11M&gt;, sig=38/15
>-</screen>
>-
>-         <para>This shows that there's one station associated, along
>-           with its parameters.  The signal indicated should be used
>-           as a relative indication of strength only.  Its
>-           translation to dBm or other units varies between different
>-           firmware revisions.</para>
>-       </sect4>
>-     </sect3>
>-
>-     <sect3>
>-       <title>Clients</title>
>-
>-       <para>A wireless client is a system that accesses an access
>-       point or another client directly. </para>
>-
>-       <para>Typically, wireless clients only have one network device,
>-       the wireless networking card.<para>
>-
>-       <para>There are a few different ways to configure a wireless
>-        client.  These are based on the different wireless modes,
>-        generally BSS (infrastructure mode, which requires an access
>-        point), and IBSS (ad-hoc, or peer-to-peer mode).  In our
>-        example, we will use the most popular of the two, BSS mode, to
>-        talk to an access point.</para>
>-
>-       <sect4>
>-       <title>Requirements</title>
>-       <para>There is only one real requirement for setting up FreeBSD as a wireless client.
>-        You will need a wireless card that is supported by FreeBSD.</para>
>-       </sect4>
>-
>-       <sect4>
>-       <title>Setting Up a Wireless FreeBSD Client</title>
>-
>-       <para>You will need to know a few things about the wireless
>-        network you are joining before you start.  In this example, we
>-        are joining a network that has a name of
>-        <literal>my_net</literal>, and encryption turned off.</para>
>-
>-       <para>Note: In this example, we are not using encryption, which
>-        is a dangerous situation.  In the next section, you will learn
>-        how to turn on encryption, and why it is important to do so,
>-        and why some encryption technologies still do not completely
>-        protect you.</para>
>-
>-       <para>Make sure your card is recognized by FreeBSD:</para>
>-
>-       <screen>&prompt.root; <userinput>ifconfig -a</userinput>
>-wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>-        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
>-        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
>-        ether 00:09:2d:2d:c9:50
>-        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
>-        status: no carrier
>-        ssid ""
>-        stationname "FreeBSD Wireless node"
>-        channel 10 authmode OPEN powersavemode OFF powersavesleep 100
>-        wepmode OFF weptxkey 1</screen>
>-
>-       <para>Now, we will set the card to the correct settings for our
>-       network:</para>
>-
>-       <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net</userinput></screen>
>-
>-       <para>Replace <hostid role="IPAddr">192.168.0.20</hostid> and
>-        <hostid role="Netmask">255.255.255.0</hostid> with a valid IP
>-        address and netmask on your wired network.  Remember, our
>-        access point is bridging the data between the wireless
>-        network, and the wired network, so it will appear to the other
>-        devices on your network that you are on the wired network just
>-        as they are.</para>
>-
>-       <para>Once you have done that, you should be able to ping hosts
>-        on the wired network just as if you were connected using a
>-        standard wired connection.</para>
>-
>-       <para>If you are experiencing problems with your wireless
>-        connection, check to make sure that your are associated
>-        (connected) to the access point:</para>
>-
>-       <screen>&prompt.root; <userinput>ifconfig wi0</userinput></screen>
>-
>-       <para>should return some information, and you should see:</para>
>-       <screen>status: associated</screen>
>-
>-       <para>If it does not show associated, then you may be out of
>-       range of the access point, do not have encryption on, or
>-       possibly have a configuration problem.</para>
>-
>-       </sect4>
>-     </sect3>
>-
>-     <sect3>
>-      <title>Encryption</title>
>-      <indexterm>
>-        <primary>wireless networking</primary>
>-        <secondary>encryption</secondary>
>-      </indexterm>
>-
>-      <para>Encryption on a wireless network is important because you
>-       no longer have the ability to keep the network contained in a
>-       well protected area.  Your wireless data will be broadcast
>-       across your entire neighborhood, so anyone who cares to read it
>-       can.  This is where encryption comes in.  By encrypting the
>-       data that is sent over the airwaves, you make it much more
>-       difficult for any interested party to grab your data right out
>-       of the air. </para>
>-
>-     <para>The two most common ways to encrypt the data between your
>-      client and the access point, are WEP, and &man.ipsec.4;.</para>
>-
>-     <sect4>
>-     <title>WEP</title>
>-      <indexterm><primary>WEP</primary></indexterm>
>-
>-      <para>WEP is an abbreviation for Wired Equivalency Protocol.
>-       WEP is an attempt to make wireless networks as safe and secure
>-       as a wired network.  Unfortunately, it has been cracked, and is
>-       fairly trivial to break.  This also means it is not something
>-       to rely on when it comes to encrypting sensitive data.  </para>
>-
>-      <para>It is better than nothing, so use the following to turn on
>-       WEP on your new FreeBSD access point:</para>
>-
>-      <screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap</userinput></screen>
>-
>-      <para>And you can turn on WEP on a client with this command:</para>
>-
>-      <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890</userinput></screen>
>-
>-      <para>Note that you should replace the <literal>0x1234567890</literal> with a more unique key.</para>
>-
>-     </sect4>
>-
>-     <sect4>
>-     <title>IPsec</title>
>-
>-     <para>&man.ipsec.4; is a much more robust and powerful tool for
>-       encrypting data across a network.  This is definitely the
>-       preferred way to encrypt wireless data over a network.  You can
>-       read more about &man.ipsec.4; security and how to implement it
>-       in the <link linkend="ipsec">IPsec</link> section of the
>-       handbook.</para>
>-     </sect4>
>-    </sect3>
>-
>-    <sect3>
>-    <title>Tools</title>
>-
>-    <para>There are a small number of tools available for use in
>-      debugging and setting up your wireless network, and here we will
>-      attempt to describe some of them and what they do.</para>
>-
>-    <sect4>
>-    <title>The <application>bsd-airtools</application> Package</title>
>-
>-    <para>The <application>bsd-airtools</application> package is a
>-      complete toolset that includes wireless auditing tools for WEP
>-      key cracking, access point detection, etc.</para>
>-
>-    <para>The <application>bsd-airtools</application> utilities can be
>-      installed from the <filename
>-      role="package">net/bsd-airtools</filename> port.  Information on
>-      installing ports can be found in <xref linkend="ports"> of the
>-      handbook.</para>
>-
>-    <para>The program <command>dstumbler</command> is the packaged
>-      tool that allows for access point discovery and signal to noise
>-      ratio graphing.  If you are having a hard time getting your
>-      access point up and running, <command>dstumbler</command> may
>-      help you get started.</para>
>-
>-    <para>To test your wireless network security, you may choose to
>-      use <quote>dweputils</quote> (<command>dwepcrack</command>,
>-      <command>dwepdump</command> and <command>dwepkeygen</command>)
>-      to help you determine if WEP is the right solution to your
>-      wireless security needs.</para>
>-
>-    </sect4>
>-
>-    <sect4>
>-    <title>The <application>wicontrol</application>, <application>ancontrol</application> and <application>raycontrol</application> Utilities</title>
>-
>-    <para>These are the tools you use to control how your wireless
>-      card behaves on the wireless network.  In the examples above, we
>-      have chosen to use &man.wicontrol.8;, since our wireless card is
>-      a <devicename>wi0</devicename> interface.  If you had a Cisco
>-      wireless device, it would come up as
>-      <devicename>an0</devicename>, and therefore you would use
>-      &man.ancontrol.8;.<para>
>-
>-    </sect4>
>-
>-    <sect4>
>-    <title>The <application>ifconfig</application> Command</title>
>-    <indexterm><primary>ifconfig</primary></indexterm>
>-
>-    <para>&man.ifconfig.8; can be used to do many of the same options
>-      as &man.wicontrol.8;, however it does lack a few options.  Check
>-      &man.ifconfig.8; for command line parameters and options.</para>
>-
>-    </sect4>
>-
>-    </sect3>
>-
>-    <sect3>
>-    <title>Supported Cards</title>
>-    <sect4>
>-    <title>Access Points</title>
>-
>-    <para>The only cards that are currently supported for BSS (as an
>-      access point) mode are devices based on the Prism 2, 2.5, or 3
>-      chipsets. For a complete list, look at &man.wi.4;.</para>
>-
>-    </sect4>
>-
>-    <sect4>
>-    <title>Clients</title>
>-
>-    <para>Almost all 802.11b wireless cards are currently supported
>-      under FreeBSD.  Most cards based on Prism, Spectrum24, Hermes,
>-      Aironet, and Raylink will work as a wireless network card in
>-      IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>
>-
>-    </sect4>
>-    </sect3>
>-
>-   </sect2>
>-  </sect1>
>-
>-
>-  <sect1 id="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 A for file service, and the Production users
>-	  are on server B.  An Ethernet is used to connect all users together,
>-	  and high loads on the network are slowing things down.</para>
>-
>-	<para>If the Editorial users could be segregated on one
>-	  network segment and the Production users on another, the two
>-	  network segments could be connected with a bridge.  Only the
>-	  network traffic destined for interfaces on the
>-	  <quote>other</quote> side of the bridge would be sent to the
>-	  other network, reducing congestion on each network
>-	  segment.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Filtering/Traffic Shaping Firewall</title>
>-	<indexterm><primary>firewall</primary></indexterm>
>-	<indexterm><primary>IP Masquerading</primary></indexterm>
>-
>-	<para>The second common situation is where firewall functionality is
>-	  needed without IP Masquerading (NAT).</para>
>-
>-	<para>An example is a small company that is connected via DSL
>-	  or ISDN to their ISP.  They have a 13 globally-accessible IP
>-	  addresses from their ISP and have 10 PCs on their network.
>-	  In this situation, using a router-based firewall is
>-	  difficult because of subnetting issues.</para>
>-
>-	<indexterm><primary>router</primary></indexterm>
>-	<indexterm><primary>DSL</primary></indexterm>
>-	<indexterm><primary>ISDN</primary></indexterm>
>-	<para>A bridge-based firewall can be configured and dropped into the
>-	  path just downstream of their DSL/ISDN router without any IP
>-	  numbering issues.</para>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Configuring a Bridge</title>
>-
>-      <sect3>
>-	<title>Network Interface Card Selection</title>
>-
>-	<para>A bridge requires at least two network cards to function.
>-	  Unfortunately, not all network interface cards as of FreeBSD&nbsp;4.0
>-	  support bridging.  Read &man.bridge.4; for details on the cards that
>-	  are supported.</para>
>-
>-	<para>Install and test the two network cards before continuing.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Kernel Configuration Changes</title>
>-	<indexterm>
>-	  <primary>kernel options</primary>
>-	  <secondary>options BRIDGE</secondary>
>-	</indexterm>
>-
>-	<para>To enable kernel support for bridging, add the:</para>
>-
>-	<programlisting>options BRIDGE</programlisting>
>-
>-	<para>statement to your kernel configuration file, and rebuild your
>-	  kernel.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Firewall Support</title>
>-	<indexterm><primary>firewall</primary></indexterm>
>-	<para>If you are planning to use the bridge as a firewall, you
>-	  will need to add the <varname>IPFIREWALL</varname> option as
>-	  well.  Read <xref linkend="firewalls"> for general
>-	  information on configuring the bridge as a firewall.</para>
>-
>-	<para>If you need to allow non-IP packets (such as ARP) to flow
>-	  through the bridge, there is an undocumented firewall option that
>-	  must be set.  This option is
>-	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this
>-	  changes the default rule for the firewall to accept any packet.
>-	  Make sure you know how this changes the meaning of your ruleset
>-	  before you set it.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Traffic Shaping Support</title>
>-
>-	<para>If you want to use the bridge as a traffic shaper, you will need
>-	  to add the <literal>DUMMYNET</literal> option to your kernel
>-	  configuration.  Read &man.dummynet.4; for further
>-	  information.</para>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Enabling the Bridge</title>
>-
>-      <para>Add the line:</para>
>-
>-      <programlisting>net.link.ether.bridge=1</programlisting>
>-
>-      <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
>-	runtime, and the line:</para>
>-
>-      <programlisting>net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable></programlisting>
>-
>-      <para>to enable bridging on the specified interfaces (replace
>-	<replaceable>if1</replaceable> and
>-	<replaceable>if2</replaceable> with the names of your two
>-	network interfaces).  If you want the bridged packets to be
>-	filtered by &man.ipfw.8;, you should add:</para>
>-
>-      <programlisting>net.link.ether.bridge_ipfw=1</programlisting>
>-
>-      <para>as well.</para>
>-    </sect2>
>-    
>-    <sect2>
>-      <title>Other Information</title>
>-
>-      <para>If you want to be able to telnet into the bridge from the network,
>-	it is OK to assign one of the network cards an IP address.  The
>-	consensus is that assigning both cards an address is a bad
>-	idea.</para>
>-
>-      <para>If you have multiple bridges on your network, there cannot be more
>-	than one path between any two workstations.  Technically, this means
>-	that there is no support for spanning tree link management.</para>
>-
>-      <para>A bridge can add latency to your ping times, especially for
>-        traffic from one segment to another.
>-      
>-    </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>NFS</title>
>-
>-    <indexterm><primary>NFS</primary></indexterm>
>-    <para>Among the many different filesystems that FreeBSD supports is
>-      the Network File System, also known as <acronym>NFS</acronym>.
>-      <acronym>NFS</acronym> allows a system to share directories and files
>-      with others over a network.  By using <acronym>NFS</acronym>, users and
>-      programs can access files on remote systems almost as if they were local
>-      files.</para>
>-
>-    <para>Some of the most notable benefits that
>-      <acronym>NFS</acronym> can provide are:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Local workstations use less disk space because
>-	  commonly used data can be stored on a single machine and still
>-	  remain accessible to others over the network.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>There is no need for users to have separate home directories
>-	  on every network machine.  Home directories could be setup on the
>-	  <acronym>NFS</acronym> server and made available throughout
>-	  the network.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Storage devices such as floppy disks, CDROM drives, and
>-	  ZIP drives can be used by other machines on the network.
>-	  This may reduce the number of removable media drives
>-	  throughout the network.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <sect2>
>-      <title>How <acronym>NFS</acronym> Works</title>
>-
>-      <para><acronym>NFS</acronym> consists of at least two main parts:
>-        a server and one or more clients.  The client remotely accesses
>-        the data that is stored
>-        on the server machine.  In order for this to function properly a few
>-        processes have to be configured and running:</para>
>-
>-      <note><para>In &os; 5.X, the <application>portmap</application> utility
>-	has been replaced with the <command>rpcbind</command> utility.  Thus,
>-	in &os; 5.X the user is required to replace every instance of
>-	<application>portmap</application> with <command>rpcbind</command>
>-	in the forthcoming examples.</para></note>
>-
>-      <para>The server has to be running the following daemons:</para>
>-      <indexterm>
>-        <primary>NFS</primary>
>-        <secondary>server</secondary>
>-      </indexterm>
>-      <indexterm>
>-        <primary><application>portmap</application></primary>
>-      </indexterm>
>-      <indexterm>
>-        <primary><application>mountd</application></primary>
>-      </indexterm>
>-      <indexterm>
>-        <primary><application>nfsd</application></primary>
>-      </indexterm>
>-
>-      <informaltable frame="none">
>-	<tgroup cols="2">
>-	  <thead>
>-	    <row>
>-	      <entry>Daemon</entry>
>-	      <entry>Description</entry>
>-	    </row>
>-	  </thead>
>-	  <tbody>
>-	    <row>
>-	      <entry>nfsd</entry>
>-	      <entry>The <acronym>NFS</acronym> daemon which services requests from
>-              the <acronym>NFS</acronym> clients.</entry>
>-	    </row>
>-	    <row>
>-	      <entry>mountd</entry>
>-	      <entry>The <acronym>NFS</acronym> mount daemon which carries out
>-		the requests that &man.nfsd.8; passes on to it.</entry>
>-	    </row>
>-	    <row>
>-	      <entry>portmap</entry>
>-	      <entry> The portmapper daemon
>-                allows <acronym>NFS</acronym> clients to discover which port the <acronym>NFS</acronym> server
>-                is using.</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </informaltable>
>-
>-      <para>The client can also run a daemon, known as
>-        <application>nfsiod</application>.  The
>-        <application>nfsiod</application> daemon services the requests
>-        from the <acronym>NFS</acronym> server.  This is optional, and
>-        improves performance, but is not required for normal and
>-        correct operation.  See the &man.nfsiod.8; manual page for
>-        more information.
>-      </para>
>-    </sect2>
>-
>-    <sect2 id="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>portmap_enable="YES"
>-nfs_server_enable="YES"
>-mountd_flags="-r"</programlisting>
>-
>-      <para><command>mountd</command> runs automatically whenever the
>-        <acronym>NFS</acronym> server is enabled.</para>
>-
>-      <para>On the client, make sure this option is present in
>-        <filename>/etc/rc.conf</filename>:</para>
>-
>-      <programlisting>nfs_client_enable="YES"</programlisting>
>-
>-      <para>The <filename>/etc/exports</filename> file specifies which
>-        filesystems <acronym>NFS</acronym> should export (sometimes
>-        referred to as <quote>share</quote>).  Each line in
>-        <filename>/etc/exports</filename> specifies a filesystem to be
>-        exported and which machines have access to that filesystem.
>-        Along with what machines have access to that filesystem,
>-        access options may also be specified.  There are many such
>-        options that can be used in this file but only a few will be
>-        mentioned here.  You can easily discover other options by
>-        reading over the &man.exports.5; manual page.</para>
>-
>-      <para>Here are a few example <filename>/etc/exports</filename>
>-	entries:</para>
>-
>-      <indexterm>
>-        <primary>NFS</primary>
>-        <secondary>export examples</secondary>
>-      </indexterm>
>-
>-      <para>The following examples give an idea of how to export filesystems,
>-        although the settings may be different depending on
>-        your environment and network configuration.
>-        For instance, to export the <filename>/cdrom</filename> directory to
>-	three example machines that have the same domain name as the server
>-	(hence the lack of a domain name for each) or have entries in your
>-	<filename>/etc/hosts</filename> file.  The <option>-ro</option>
>-	flag makes the exported filesystem read-only.  With this flag, the
>-	remote system will not be able to write any changes to the
>-	exported filesystem.</para>
>-
>-      <programlisting>/cdrom -ro host1 host2 host3</programlisting>
>-
>-      <para>The following line exports <filename>/home</filename> to
>-	three hosts by IP address.  This is a useful setup if you have
>-	a private network without a <acronym>DNS</acronym> server
>-	configured.  Optionally the <filename>/etc/hosts</filename>
>-	file could be configured for internal hostnames; please review
>-	&man.hosts.5; for more information.  The
>-	<option>-alldirs</option> flag allows the subdirectories to be
>-	mount points.  In other words, it will not mount the
>-	subdirectories but permit the client to mount only the
>-	directories that are required or needed.</para>
>-
>-      <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
>-
>-      <para>The following line exports <filename>/a</filename> so that
>-	two clients from different domains may access the filesystem.
>-	The <option>-maproot=root</option> flag allows the
>-	<username>root</username> user on the remote system to write
>-	data on the exported filesystem as <username>root</username>.
>-	If the <literal>-maproot=root</literal> flag is not specified,
>-	then even if a user has <username>root</username> access on
>-	the remote system, they will not be able to modify files on
>-	the exported filesystem.</para>
>-
>-      <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
>-
>-      <para>In order for a client to access an exported filesystem,
>-	the client must have permission to do so.  Make sure the
>-	client is listed in your <filename>/etc/exports</filename>
>-	file.</para>
>-
>-      <para>In <filename>/etc/exports</filename>, each line represents
>-	the export information for one filesystem to one host.  A
>-	remote host can only be specified once per filesystem, and may
>-	only have one default entry.  For example, assume that
>-	<filename>/usr</filename> is a single filesystem.  The
>-	following <filename>/etc/exports</filename> would be
>-	invalid:</para>
>-
>-      <programlisting>/usr/src   client
>-/usr/ports client</programlisting>
>-
>-      <para>One filesystem, <filename>/usr</filename>, has two lines
>-	specifying exports to the same host, <hostid>client</hostid>.
>-        The correct format for this situation is:</para>
>-
>-      <programlisting>/usr/src /usr/ports  client</programlisting>
>-
>-      <para>The properties of one filesystem exported to a given host
>-	must all occur on one line.  Lines without a client specified
>-	are treated as a single host.  This limits how you can export
>-	filesystems, but for most people this is not an issue.</para>
>-
>-      <para>The following is an example of a valid export list, where
>-	<filename>/usr</filename> and <filename>/exports</filename>
>-	are local filesystems:</para>
>-
>-      <programlisting># Export src and ports to client01 and client02, but only
>-# client01 has root privileges on it
>-/usr/src /usr/ports -maproot=root    client01
>-/usr/src /usr/ports               client02
>-# The client machines have root and can mount anywhere
>-# on /exports. Anyone in the world can mount /exports/obj read-only
>-/exports -alldirs -maproot=root      client01 client02
>-/exports/obj -ro</programlisting>
>-
>-      <para>You must restart
>-        <command>mountd</command> whenever you modify
>-        <filename>/etc/exports</filename> so the changes can take effect.
>-        This can be accomplished by sending the HUP signal
>-        to the <command>mountd</command> process:</para>
>-
>-      <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
>-
>-      <para>Alternatively, a reboot will make FreeBSD set everything
>-        up properly.  A reboot is not necessary though.
>-        Executing the following commands as <username>root</username>
>-        should start everything up.</para>
>-
>-      <para>On the <acronym>NFS</acronym> server:</para>
>-
>-      <screen>&prompt.root; <userinput>portmap</userinput>
>-&prompt.root; <userinput>nfsd -u -t -n 4</userinput>
>-&prompt.root; <userinput>mountd -r</userinput></screen>
>-
>-      <para>On the <acronym>NFS</acronym> client:</para>
>-
>-      <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>
>-
>-      <para>Now everything should be ready to actually mount a remote file
>-	system.  In these examples the
>-	server's name will be <literal>server</literal> and the client's
>-	name will be <literal>client</literal>.  If you only want to
>-	temporarily mount a remote filesystem or would rather test the
>-	configuration, just execute a command like this as <username>root</username> on the
>-        client:</para>
>-      <indexterm>
>-        <primary>NFS</primary>
>-        <secondary>mounting</secondary>
>-      </indexterm>
>-      <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
>-
>-      <para>This will mount the <filename>/home</filename> directory
>-	on the server at <filename>/mnt</filename> on the client.  If
>-	everything is set up correctly you should be able to enter
>-	<filename>/mnt</filename> on the client and see all the files
>-        that are on the server.</para>
>-
>-      <para>If you want to automatically mount a remote filesystem
>-	each time the computer boots, add the filesystem to the
>-	<filename>/etc/fstab</filename> file.  Here is an example:</para>
>-
>-      <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
>-
>-      <para>The &man.fstab.5; manual page lists all the available options.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Practical Uses</title>
>-
>-      <para><acronym>NFS</acronym> has many practical uses.  Some of the more common
>-        ones are listed below:</para>
>-
>-      <indexterm>
>-        <primary>NFS</primary>
>-        <secondary>uses</secondary>
>-      </indexterm>
>-      <itemizedlist>
>-        <listitem>
>-	  <para>Set several machines to share a CDROM or other media
>-	    among them.  This is cheaper and often a more convenient
>-	    method to install software on multiple machines.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>On large networks, it might be more convenient to
>-	    configure a central <acronym>NFS</acronym> server in which
>-	    to store all the user home directories.  These home
>-	    directories can then be exported to the network so that
>-	    users would always have the same home directory,
>-	    regardless of which workstation they log in to.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Several machines could have a common
>-            <filename>/usr/ports/distfiles</filename> directory.  That
>-            way, when you need to install a port on several machines,
>-            you can quickly access the source without downloading it
>-            on each machine.</para>
>-	</listitem>
>-      </itemizedlist>
>-    </sect2>
>-
>-    <sect2 id="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 filesystem whenever a file or directory within that
>-	filesystem is accessed.  Filesystems that are inactive for a
>-	period of time will also be automatically unmounted by
>-	<application>amd</application>.  Using
>-	<application>amd</application> provides a simple alternative
>-	to permanent mounts, as permanent mounts are usually listed in
>-        <filename>/etc/fstab</filename>.</para>
>-
>-      <para><application>amd</application> operates by attaching
>-	itself as an NFS server to the <filename>/host</filename> and
>-	<filename>/net</filename> directories.  When a file is accessed
>-	within one of these directories, <application>amd</application>
>-	looks up the corresponding remote mount and automatically mounts
>-	it.  <filename>/net</filename> is used to mount an exported
>-	filesystem from an IP address, while <filename>/host</filename>
>-	is used to mount an export from a remote hostname.</para>
>-
>-      <para>An access to a file within
>-	<filename>/host/foobar/usr</filename> would tell
>-	<application>amd</application> to attempt to mount the
>-	<filename>/usr</filename> export on the host
>-	<hostid>foobar</hostid>.</para>
>-
>-      <example>
>-	<title>Mounting an Export with <application>amd</application></title>
>-
>-	<para>You can view the available mounts of a remote host with
>-	  the <command>showmount</command> command.  For example, to
>-	  view the mounts of a host named <hostid>foobar</hostid>, you
>-	  can use:</para>
>-
>-	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
>-Exports list on foobar:
>-/usr                               10.10.10.0
>-/a                                 10.10.10.0
>-&prompt.user; <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 filesystem with the option <option>-r=1024</option>.  These
>-	options may be specified using the fourth field of the
>-	<filename>fstab</filename> entry on the client for automatic
>-	mounts, or by using the <option>-o</option> parameter of the mount
>-	command for manual mounts.</para>
>-
>-      <para>It should be noted that there is a different problem,
>-	sometimes mistaken for this one, when the NFS servers and clients
>-	are on different networks.  If that is the case, make
>-	<emphasis>certain</emphasis> that your routers are routing the
>-	necessary UDP information, or you will not get anywhere, no matter
>-	what else you are doing.</para>
>-
>-      <para>In the following examples, <hostid>fastws</hostid> is the host
>-	(interface) name of a high-performance workstation, and
>-	<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
>-	system with a lower-performance Ethernet adapter.  Also,
>-	<filename>/sharedfs</filename> will be the exported NFS
>-	filesystem (see &man.exports.5;), and
>-	<filename>/project</filename> will be the mount point on the
>-	client for the exported filesystem.  In all cases, note that
>-	additional options, such as <option>hard</option> or
>-	<option>soft</option> and <option>bg</option> may be desirable in
>-	your application.</para>
>-
>-      <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as
>-	the client in <filename>/etc/fstab</filename> on freebox:</para>
>-
>-      <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
>-
>-      <para>As a manual mount command on <hostid>freebox</hostid>:</para>
>-
>-      <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
>-
>-      <para>Examples for the FreeBSD system as the server in
>-	<filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para>
>-
>-      <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
>-
>-      <para>As a manual mount command on <hostid>fastws</hostid>:</para>
>-
>-      <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
>-
>-      <para>Nearly any 16-bit Ethernet adapter will allow operation
>-	without the above restrictions on the read or write size.</para>
>-
>-      <para>For anyone who cares, here is what happens when the failure
>-	occurs, which also explains why it is unrecoverable.  NFS
>-	typically works with a <quote>block</quote> size of 8&nbsp;k (though it
>-	may do fragments of smaller sizes).  Since the maximum Ethernet
>-	packet is around 1500&nbsp;bytes, the NFS <quote>block</quote> gets
>-	split into multiple Ethernet packets, even though it is still a
>-	single unit to the upper-level code, and must be received,
>-	assembled, and <emphasis>acknowledged</emphasis> as a unit.  The
>-	high-performance workstations can pump out the packets which
>-	comprise the NFS unit one right after the other, just as close
>-	together as the standard allows.  On the smaller, lower capacity
>-	cards, the later packets overrun the earlier packets of the same
>-	unit before they can be transferred to the host and the unit as a
>-	whole cannot be reconstructed or acknowledged.  As a result, the
>-	workstation will time out and try again, but it will try again
>-	with the entire 8&nbsp;K unit, and the process will be repeated, ad
>-	infinitum.</para>
>-
>-      <para>By keeping the unit size below the Ethernet packet size
>-	limitation, we ensure that any complete Ethernet packet received
>-	can be acknowledged individually, avoiding the deadlock
>-	situation.</para>
>-
>-      <para>Overruns may still occur when a high-performance workstations
>-	is slamming data out to a PC system, but with the better cards,
>-	such overruns are not guaranteed on NFS <quote>units</quote>.  When
>-	an overrun occurs, the units affected will be retransmitted, and
>-	there will be a fair chance that they will be received, assembled,
>-	and acknowledged.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="network-diskless">
>-    <sect1info>
>-      <authorgroup>
>-        <author>
>-          <firstname>Jean-Fran&ccedil;ois</firstname>
>-          <surname>Dock&egrave;s</surname>
>-          <contrib>Updated by </contrib>
>-        </author>
>-      </authorgroup>
>-    </sect1info>
>-    <title>Diskless Operation</title>
>-
>-    <indexterm><primary>diskless workstation</primary></indexterm>
>-    <indexterm><primary>diskless operation</primary></indexterm>
>-
>-    <para>A FreeBSD machine can boot over the network and operate without a
>-      local disk, using filesystems mounted from an NFS server.  No system
>-      modification is necessary, beyond standard configuration files.
>-      Such a system is easy to  set up because all the necessary elements
>-      are readily available:</para>
>-    <itemizedlist>
>-      <listitem>
>-	<para>There are at least two possible methods to load the kernel over
>-	  the network:</para>
>-	<itemizedlist>
>-	  <listitem>
>-	    <para><emphasis>PXE</emphasis>: Intel's Preboot Execution
>-	      Environment system is a form of smart boot ROM built into some
>-	      networking cards or motherboards.  See &man.pxeboot.8; for more
>-	      details.</para>
>-	  </listitem>
>-	  <listitem>
>-	    <para><emphasis>The <application>etherboot</application>
>-	      port</emphasis> (<filename
>-	      role="package">net/etherboot</filename>) produces
>-	      ROM-able code to boot kernels over the network.  The
>-	      code can be either burnt into a boot PROM on a network
>-	      card, or loaded from a local floppy (or hard) disk
>-	      drive, or from a running MS-DOS system.  Many network
>-	      cards are supported.</para>
>-	  </listitem>
>-	</itemizedlist>
>-	</listitem>
>-
>-      <listitem>
>-	<para>A sample script
>-	  (<filename>/usr/share/examples/diskless/clone_root</filename>) eases
>-	  the creation and maintenance of the workstation's root filesystem
>-	  on the server.  The script will probably require a little
>-	  customization but it will get you started very quickly.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Standard system startup files exist in <filename>/etc</filename>
>-	  to detect and support a diskless system startup.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Swapping, if needed, can be done either to an NFS file or to
>-	  a local disk.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>There are many ways to set up diskless workstations.  Many
>-      elements are involved, and most can be customized to suit local
>-      taste.  The following will describe the setup of a complete system,
>-      emphasizing simplicity and compatibility with the
>-      standard FreeBSD startup scripts.  The system described has the
>-      following characteristics:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>The diskless workstations use a shared
>-	  read-only <filename>root</filename> filesystem, and a shared
>-	  read-only <filename>/usr</filename>.</para>
>-	<para>The <filename>root</filename> filesystem is a copy of a
>-	  standard FreeBSD root (typically the server's), with some
>-	  configuration files overridden by ones specific to diskless
>-	  operation or, possibly, to the workstation they belong to.</para>
>-	<para>The parts of the <filename>root</filename> which have to be
>-	  writable are overlaid with &man.mfs.8; filesystems.  Any changes
>-	  will be lost when the system reboots.</para>
>-      </listitem>
>-      <listitem>
>-	<para>The kernel is loaded by <application>etherboot
>-	  </application>, using DHCP (or BOOTP) and TFTP.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <caution><para>As described, this system is insecure.  It should
>-	live in a protected area of a network, and be untrusted by
>-	other hosts.</para>
>-    </caution>
>-
>-
>-    <sect2>
>-      <title>Setup Instructions</title>
>-
>-      <sect3>
>-	<title>Configuring DHCP/BOOTP</title>
>-	<indexterm>
>-	  <primary>diskless operation</primary>
>-	  <secondary>booting</secondary>
>-	</indexterm>
>-
>-	<para>There are two protocols that are commonly used to boot a
>-	  workstation that retrieves its configuration over the network: BOOTP
>-	  and DHCP.  They are used at several points in the workstation
>-	  bootstrap:</para>
>-	<itemizedlist>
>-	  <listitem><para><application>etherboot</application> uses
>-	      DHCP (by default) or BOOTP (needs a configuration option) to
>-	      find the kernel.  (PXE uses DHCP).</para>
>-	  </listitem>
>-	  <listitem><para>The kernel uses BOOTP to locate the NFS
>-	      root.</para>
>-	  </listitem>
>-	</itemizedlist>
>-
>-	<para>It is possible to configure a system to use only BOOTP.
>-	  The &man.bootpd.8; server program is included in the
>-	  base FreeBSD system.</para>
>-
>-	<para>However, DHCP has a number of advantages over BOOTP (nicer
>-	  configuration files, possibility of using PXE, plus many others
>-	  not directly related to diskless operation), and we shall describe
>-	  both a pure BOOTP, and a BOOTP+DHCP configuration, with an
>-	  emphasis on the latter, which will use the ISC DHCP software
>-	  package.</para>
>-
>-	<sect4>
>-	  <title>Configuration Using ISC DHCP</title>
>-	  <indexterm>
>-	    <primary>DHCP</primary>
>-	    <secondary>diskless operation</secondary>
>-	  </indexterm>
>-
>-	  <para>The <application>isc-dhcp</application> server can answer
>-	    both BOOTP and DHCP requests.</para>
>-
>-	  <para>As of release 4.4, <application>isc-dhcp
>-  	    3.0</application> is not part of the base
>-	    system.  You will first need to install the
>-	    <filename role="package">net/isc-dhcp3</filename> port or the
>-	    corresponding package.  Please refer to <xref linkend="ports">
>-	    for general information about ports and packages.</para>
>-
>-	  <para>Once <application>isc-dhcp</application> is installed, it
>-	    needs a configuration file to run, (normally named
>-	    <filename>/usr/local/etc/dhcpd.conf</filename>).  Here follows
>-	    a commented example:</para>
>-
>-          <programlisting>
>-          default-lease-time 600;
>-          max-lease-time 7200;
>-          authoritative;
>-
>-          option domain-name "example.com";
>-          option domain-name-servers 192.168.4.1;
>-          option routers 192.168.4.1;
>-
>-          subnet 192.168.4.0 netmask 255.255.255.0 {
>-            use-host-decl-names on; <co id="co-dhcp-host-name">
>-            option subnet-mask 255.255.255.0;
>-            option broadcast-address 192.168.4.255;
>-
>-            host margaux {
>-              hardware ethernet 01:23:45:67:89:ab;
>-              fixed-address margaux.example.com;
>-              next-server 192.168.4.4;<co id="co-dhcp-next-server">
>-              filename "/tftpboot/kernel.diskless";<co id="co-dhcp-filename">
>-              option root-path "192.168.4.4:/data/misc/diskless";<co id="co-dhcp-root-path">
>-            }
>-          }
>-          </programlisting>
>-
>-	  <calloutlist>
>-	    <callout arearefs="co-dhcp-host-name"><para>This option tells
>-		<command>dhcpd</command> to send the value in the
>-		<literal>host</literal> declarations as the hostname for the
>-		diskless host.  An alternate way would be to add an
>-		<literal>option host-name
>-		  <replaceable>margaux</replaceable></literal> inside the
>-		host declarations.</para>
>-	    </callout>
>-
>-	    <callout arearefs="co-dhcp-next-server"><para>The
>-		<literal>next-server</literal> directive designates
>-		the TFTP server (the default is to use the same host as the
>-		DHCP server).</para>
>-	    </callout>
>-
>-	    <callout arearefs="co-dhcp-filename"><para>The
>-		<literal>filename</literal> directive defines the file that
>-		<application>etherboot</application> will load as a
>-		kernel.
>-		<note><para>PXE appears to prefer a relative file
>-		    name, and it loads <command>pxeboot</command>, not the
>-		    kernel (<literal>option filename
>-		      "pxeboot"</literal>).</para>
>-		</note>
>-	      </para>
>-	    </callout>
>-
>-	    <callout arearefs="co-dhcp-root-path"><para>The
>-		<literal>root-path</literal> option defines the path to
>-		the root filesystem, in usual NFS notation.</para>
>-	    </callout>
>-	  </calloutlist>
>-
>-	</sect4>
>-	<sect4>
>-	  <title>Configuration Using BOOTP</title>
>-	  <indexterm>
>-	    <primary>BOOTP</primary>
>-	    <secondary>diskless operation</secondary>
>-	  </indexterm>
>-
>-	  <para>Here follows an equivalent <command>bootpd</command>
>-	    configuration.  This would be found in
>-	    <filename>/etc/bootptab</filename>.</para>
>-
>-	  <para>Please note that <application>etherboot</application>
>-	    must be compiled with the non-default option
>-	    <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP,
>-	    and that PXE <emphasis>needs</emphasis> DHCP.  The only
>-	    obvious advantage of <application>bootpd</application> is
>-	    that it exists in the base system.</para>
>-
>-          <programlisting>
>-          .def100:\
>-            :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
>-            :sm=255.255.255.0:\
>-            :ds=192.168.4.1:\
>-            :gw=192.168.4.1:\
>-            :hd="/tftpboot":\
>-            :bf="/kernel.diskless":\
>-            :rp="192.168.4.4:/data/misc/diskless":
>-
>-          margaux:ha=0123456789ab:tc=.def100
>-          </programlisting>
>-	</sect4>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Preparing a Boot Program with
>-	  <application>Etherboot</application></title>
>-
>-	<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.html">
>-	  extensive documentation</ulink> mainly intended for Linux
>-	  systems, but nonetheless containing useful information.  The
>-	  following will just outline how you would use
>-	  <application>etherboot</application> on a FreeBSD
>-	  system.</para>
>-
>-	<para>You must first install the <filename
>-	  role="package">net/etherboot</filename> package or port.
>-	  The <application>etherboot</application> port can normally
>-	  be found in <filename>/usr/ports/net/etherboot</filename>.
>-	  If the ports tree is installed on your system, just typing
>-	  <literal>make</literal> in this directory should take care
>-	  of everything.  Else refer to <xref linkend="ports"> for
>-	  information about ports and packages.</para>
>-
>-	<para>For our setup, we shall use a boot floppy.  For other methods
>-	  (PROM, or dos program), please refer to the
>-	  <application>etherboot</application> documentation.</para>
>-
>-	<para>To make a boot floppy, insert a floppy in the drive on the
>-	  machine where you installed <application>etherboot</application>,
>-	  then change your current directory to the <filename>src</filename>
>-	  directory in the <application>etherboot</application> tree and
>-	  type:</para>
>-
>-	<screen>
>-	  &prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput>
>-	</screen>
>-
>-	<para><replaceable>devicetype</replaceable> depends on the type of
>-	  the Ethernet card in the diskless workstation.  Refer to the
>-	  <filename>NIC</filename> file in the same directory to determine the
>-	  right <replaceable>devicetype</replaceable>.</para>
>-
>-      </sect3>
>-
>-
>-      <sect3>
>-	<title>Configuring the TFTP and NFS Servers</title>
>-
>-	<indexterm>
>-	  <primary>TFTP</primary>
>-	  <secondary>diskless operation</secondary>
>-	</indexterm>
>-	<indexterm>
>-	  <primary>NFS</primary>
>-	  <secondary>diskless operation</secondary>
>-	</indexterm>
>-
>-	<para>You need to enable <command>tftpd</command> on the TFTP
>-	  server:</para>
>-        <procedure>
>-          <step>
>-            <para>Create a directory from which <command>tftpd</command>
>-            will serve the files, i.e.: <filename>/tftpboot</filename></para>
>-          </step>
>-
>-          <step>
>-            <para>Add this line to your
>-	      <filename>/etc/inetd.conf</filename>:</para>
>-
>-	    <programlisting>tftp    dgram   udp     wait    root  /usr/libexec/tftpd    tftpd -s /tftpboot</programlisting>
>-
>-	    <note><para>It appears that at least some PXE versions want
>-		the TCP version of TFTP.  In this case, add a second line,
>-		replacing <literal>dgram udp</literal> with <literal>stream
>-		tcp</literal>.</para>
>-	    </note>
>-          </step>
>-	  <step>
>-	    <para>Tell <command>inetd</command> to reread its configuration
>-	      file:</para>
>-	    <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
>-	  </step>
>-        </procedure>
>-
>-	<para>You can place the <filename>tftpboot</filename>
>-	  directory anywhere on the server.  Make sure that the
>-	  location is set in both <filename>inetd.conf</filename> and
>-	  <filename>dhcpd.conf</filename>.</para>
>-
>-	<para>You also need to enable NFS and export the
>-	  appropriate filesystem on the NFS server.</para>
>-
>-        <procedure>
>-          <step>
>-            <para>Add this to <filename>/etc/rc.conf</filename>:</para>
>-	    <programlisting>nfs_server_enable="YES"</programlisting>
>-          </step>
>-
>-          <step>
>-            <para>Export the filesystem where the diskless root directory
>-	      is located by adding the following to
>-	      <filename>/etc/exports</filename> (adjust the volume mount
>-	      point and replace <replaceable>margaux</replaceable>
>-	      with the name of the diskless workstation):</para>
>-
>-	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux</replaceable></programlisting>
>-          </step>
>-	  <step>
>-	    <para>Tell <command>mountd</command> to reread its configuration
>-	      file.  If you actually needed to enable NFS in
>-	      <filename>/etc/rc.conf</filename>
>-	      at the first step, you probably want to reboot instead.</para>
>-	    <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
>-	  </step>
>-        </procedure>
>-
>-      </sect3>
>-
>-      <sect3>
>-	<title>Building a Diskless Kernel</title>
>-
>-	<indexterm>
>-	  <primary>diskless operation</primary>
>-	  <secondary>kernel configuration</secondary>
>-	</indexterm>
>-
>-	<para>Create a kernel configuration file for the diskless client
>-	  with the following options (in addition to the usual
>-	  ones):</para>
>-
>-	<programlisting>
>-          options     BOOTP          # Use BOOTP to obtain IP address/hostname
>-          options     BOOTP_NFSROOT  # NFS mount root filesystem using BOOTP info
>-          options     BOOTP_COMPAT   # Workaround for broken bootp daemons.
>-	</programlisting>
>-
>-	<para>You may also want to use <literal>BOOTP_NFSV3</literal> and
>-	  <literal>BOOTP_WIRED_TO</literal> (refer to <filename>LINT</filename>).</para>
>-
>-	<para>Build the kernel (See <xref linkend="kernelconfig">),
>-	  and copy it to the tftp directory, under the name listed
>-	  in <filename>dhcpd.conf</filename>.</para>
>-
>-
>-      </sect3>
>-
>-      <sect3>
>-	  <title>Preparing the Root Filesystem</title>
>-
>-	<indexterm>
>-	  <primary>root file system</primary>
>-	  <secondary>diskless operation</secondary>
>-	</indexterm>
>-
>-	<para>You need to create a root filesystem for the diskless
>-	  workstations, in the location listed as
>-	  <literal>root-path</literal> in
>-	  <filename>dhcpd.conf</filename>.</para>
>-
>-	<para>The easiest way to do this is to use the
>-	  <filename>/usr/share/examples/diskless/clone_root</filename>
>-	  shell script.  This script needs customization, at least to adjust
>-	  the place where the filesystem will be created (the
>-	  <literal>DEST</literal> variable).
>-
>-	<para>Refer to the comments at the top of the script for
>-	    instructions.  They explain how the base filesystem is built,
>-	    and how files may be selectively overridden by versions specific
>-	    to diskless operation, to a subnetwork, or to an individual
>-	    workstation.  They also give examples for the diskless
>-	    <filename>/etc/fstab</filename> and <filename>
>-	    /etc/rc.conf</filename> files.</para>
>-
>-	  <para>The <filename>README</filename> files in
>-	    <filename>/usr/share/examples/diskless</filename> contain a lot
>-	    of interesting background information, but, together with the
>-	    other examples in the <filename>diskless</filename> directory,
>-	    they actually document a configuration method which is distinct
>-	    from the one used by <filename>clone_root</filename> and
>-	    <filename>/etc/rc.diskless[12]</filename>, which is a little
>-	    confusing.  Use them for reference only, except if you prefer
>-	    the method that they describe, in which case you will need
>-	    customized <filename>rc</filename> scripts.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Configuring Swap</title>
>-
>-	<para>If needed, a swap file located on the server can be
>-	  accessed via NFS.  The exact <filename>bootptab</filename>
>-	  or <filename>dhcpd.conf</filename> options are not clearly
>-	  documented at this time.  The following configuration
>-	  suggestions have been reported to work in some installations
>-	  using isc-dhcp 3.0rc11.</para>
>-	<procedure>
>-	  <step><para>Add the following lines to
>-	  <filename>dhcpd.conf</filename>:</para>
>-	    <programlisting>
>-              # Global section
>-              option swap-path code 128 = string;
>-              option swap-size code 129 = integer 32;
>-
>-              host margaux {
>-                ... # Standard lines, see above
>-                option swap-path <replaceable>"192.168.4.4:/netswapvolume/netswap"</replaceable>;
>-                option swap-size <replaceable>64000</replaceable>;
>-              }
>-	    </programlisting>
>-	    <para>The idea is that, at least for a FreeBSD client,
>-	      DHCP/BOOTP option code 128 is the path to the NFS swap file,
>-	      and option code 129 is the swap size in kilobytes.  Older
>-	      versions of <command>dhcpd</command> allowed a syntax of
>-	      <literal>option option-128 "...</literal>, which does not
>-	      seem to work any more.</para>
>-	    <para><filename>/etc/bootptab</filename> would use the
>-	      following syntax instead:</para>
>-
>-	    <para><literal>T128="192.168.4.4:/netswapvolume/netswap":T129=64000
>-	      </literal></para>
>-	  </step>
>-
>-	  <step>
>-	    <para>On the NFS swap file server, create the swap
>-	    file(s)</para>
>-            <screen>
>-              &prompt.root; <userinput>mkdir <replaceable>/netswapvolume/netswap</replaceable></userinput>
>-              &prompt.root; <userinput>cd <replaceable>/netswapvolume/netswap</replaceable></userinput>
>-              &prompt.root; <userinput>dd if=/dev/zero bs=1024 count=<replaceable>64000</replaceable> of=swap.<replaceable>192.168.4.6</replaceable></userinput>
>-              &prompt.root; <userinput>chmod 0600 swap.<replaceable>192.168.4.6</replaceable></userinput>
>-            </screen>
>-	    <para><replaceable>192.168.4.6</replaceable> is the IP address
>-	      for the diskless client.</para>
>-	  </step>
>-
>-	  <step>
>-	    <para>On the NFS swap file server, add the following line to
>-	    <filename>/etc/exports</filename>:</para>
>-	    <programlisting>
>-	      <replaceable>/netswapvolume</replaceable>  -maproot=0:10 -alldirs <replaceable>margaux</replaceable>
>-	    </programlisting>
>-	    <para>Then tell <application>mountd</application> to reread the
>-		exports file, as above.</para>
>-	  </step>
>-	</procedure>
>-
>-      </sect3>
>-
>-      <sect3>
>-	<title>Miscellaneous Issues</title>
>-
>-
>-	<sect4>
>-	  <title>Running with a Read-only <filename>/usr</filename></title>
>-
>-	  <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 xdm configuration file, which puts
>-	    the error log on <filename>/usr</filename> by default.</para>
>-	</sect4>
>-	<sect4>
>-	  <title>Using a Non-FreeBSD Server</title>
>-
>-	  <para>When the server for the root filesystem is not running FreeBSD,
>-	    you will have to create the root filesystem on a
>-	    FreeBSD machine, then copy it to its destination, using
>-	    <command>tar</command> or <command>cpio</command>.</para>
>-	  <para>In this situation, there are sometimes
>-	    problems with the special files in <filename>/dev</filename>,
>-	    due to differing major/minor integer sizes.  A solution to this
>-	    problem is to export a directory from the non-FreeBSD server,
>-	    mount this directory onto a FreeBSD machine, and run
>-	    <command>MAKEDEV</command> on the FreeBSD machine
>-	    to create the correct device entries (FreeBSD 5.0 and later
>-	    use &man.devfs.5; to allocate device nodes transparently for
>-	    the user, running <command>MAKEDEV</command> on these
>-	    versions is useless).</para>
>-
>-	</sect4>
>-
>-      </sect3>
>-
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="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://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.  Starting with
>-	FreeBSD&nbsp;4.4, some active cards are supported where the firmware
>-	also supports other signaling protocols; this also includes the
>-	first supported Primary Rate (PRI) ISDN card.</para>
>-
>-      <para><application>Isdn4bsd</application> allows you to connect
>-	to other ISDN routers using either IP over raw HDLC or by using
>-	synchronous PPP: either by using kernel PPP with isppp, a
>-	modified sppp driver, or by using userland &man.ppp.8;.  By using
>-	userland &man.ppp.8;, channel bonding of two or more ISDN
>-	B-channels is possible.  A telephone answering machine
>-	application is also available as well as many utilities such as
>-	a software 300 Baud modem.</para>
>-
>-      <para>Some growing number of PC ISDN cards are supported under
>-	FreeBSD and the reports show that it is successfully used all
>-	over Europe and in many other parts of the world.</para>
>-
>-      <para>The passive ISDN cards supported are mostly the ones with
>-	the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
>-	but also ISDN cards with chips from Cologne Chip (ISA bus only),
>-	PCI cards with Winbond W6692 chips, some cards with the
>-	Tiger300/320/ISAC chipset combinations and some vendor specific
>-	chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
>-	AVM Fritz!Card PnP.</para>
>-
>-      <para>Currently the active supported ISDN cards are the AVM B1
>-	(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>
>-
>-      <para>For documentation on <application>isdn4bsd</application>,
>-	have a look at <filename>/usr/share/examples/isdn/</filename>
>-	directory on your FreeBSD system or at the <ulink
>-	  url="http://www.freebsd-support.de/i4b/">homepage of
>-	  isdn4bsd</ulink> which also has pointers to hints, erratas and
>-	much more documentation such as the <ulink
>-	  url="http://people.FreeBSD.org/~hm/">isdn4bsd
>-	  handbook</ulink>.</para>
>-
>-      <para>In case you are interested in adding support for a
>-	different ISDN protocol, a currently unsupported ISDN PC card or
>-	otherwise enhancing <application>isdn4bsd</application>, please
>-	get in touch with &a.hm;.</para>
>-
>-      <para>For questions regarding the installation, configuration
>-	and troubleshooting <application>isdn4bsd</application>, a
>-	&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 setup.  However, at the same time any problems you
>-	experienced with the PPP program and are going to persist.</para>
>-
>-      <para>If you want maximum stability, use the kernel <link
>-	  linkend="ppp">PPP</link> option, not the user-land <link
>-	  linkend="userppp">iijPPP</link>.</para>
>-
>-      <para>The following TA's are known to work with FreeBSD.</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>Motorola BitSurfer and Bitsurfer Pro</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Adtran</para>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <para>Most other TA's will probably work as well, TA vendors try to make
>-	sure their product can accept most of the standard modem AT command
>-	set.</para>
>-
>-      <para>The real problem with external TA's is that, like modems,
>-	you need a good serial card in your computer.</para>
>-
>-      <para>You should read the <ulink
>-	url="../../articles/serial-uart/index.html">FreeBSD Serial
>-	Hardware</ulink> tutorial for a detailed understanding of
>-	serial devices, and the differences between asynchronous and
>-	synchronous serial ports.</para>
>-
>-      <para>A TA running off a standard PC serial port (asynchronous) limits
>-	you to 115.2&nbsp;Kbs, even though you have a 128&nbsp;Kbs connection.
>-	To fully utilize the 128&nbsp;Kbs that ISDN is capable of,
>-	you must move the TA to a synchronous serial card.</para>
>-
>-      <para>Do not be fooled into buying an internal TA and thinking you have
>-	avoided the synchronous/asynchronous issue.  Internal TA's simply have
>-	a standard PC serial port chip built into them.  All this will do is
>-	save you having to buy another serial cable and find another empty
>-	electrical socket.</para>
>-
>-      <para>A synchronous card with a TA is at least as fast as a stand-alone
>-	router, and with a simple 386 FreeBSD box driving it, probably more
>-	flexible.</para>
>-
>-      <para>The choice of sync/TA v.s. stand-alone router is largely a
>-	religious issue.  There has been some discussion of this in
>-	the mailing lists.  I suggest you search the <ulink
>-	url="../../../../search/index.html">archives</ulink> for
>-	the complete discussion.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Stand-alone ISDN Bridges/Routers</title>
>-      <indexterm>
>-        <primary>ISDN</primary>
>-	<secondary>stand-alone bridges/routers</secondary>
>-      </indexterm>
>-      <para>ISDN bridges or routers are not at all specific to FreeBSD
>-	or any other operating system.  For a more complete
>-	description of routing and bridging technology, please refer
>-	to a Networking reference book.</para>
>-
>-      <para>In the context of this page, the terms router and bridge will
>-	be used interchangeably.</para>
>-
>-      <para>As the cost of low end ISDN routers/bridges comes down, it
>-	will likely become a more and more popular choice.  An ISDN
>-	router is a small box that plugs directly into your local
>-	Ethernet network, and manages its own connection to the other
>-	bridge/router.  It has built in software to communicate via
>-	PPP and other popular protocols.</para>
>-
>-      <para>A router will allow you much faster throughput than a
>-	standard TA, since it will be using a full synchronous ISDN
>-	connection.</para>
>-
>-      <para>The main problem with ISDN routers and bridges is that
>-	interoperability between manufacturers can still be a problem.
>-	If you are planning to connect to an Internet provider, you
>-	should discuss your needs with them.</para>
>-
>-      <para>If you are planning to connect two LAN segments together,
>-	such as your home LAN to the office LAN, this is the simplest
>-	lowest
>-	maintenance solution.  Since you are buying the equipment for
>-	both sides of the connection you can be assured that the link
>-	will work.</para>
>-
>-      <para>For example to connect a home computer or branch office
>-	network to a head office network the following setup could be
>-	used.</para>
>-
>-      <example>
>-	<title>Branch Office or Home Network</title>
>-
>-	<indexterm><primary>10 base 2</primary></indexterm>
>-	<para>Network uses a bus based topology with 10 base 2
>-	  Ethernet (<quote>thinnet</quote>).  Connect router to network cable with
>-	  AUI/10BT transceiver, if necessary.</para>
>-
>-        <mediaobject>
>-          <imageobject>
>-            <imagedata fileref="advanced-networking/isdn-bus">
>-          </imageobject>
>-
>-	  <textobject>
>-	    <literallayout class="monospaced">---Sun workstation
>-|
>----FreeBSD box
>-|
>----Windows 95 (Do not admit to owning it)
>-|
>-Stand-alone router
>-   |
>-ISDN BRI line</literallayout>
>-          </textobject>
>-
>-	  <textobject>
>-	    <phrase>10 Base 2 Ethernet</phrase>
>-	  </textobject>
>-	</mediaobject>
>-
>-	<para>If your home/branch office is only one computer you can use a
>-	  twisted pair crossover cable to connect to the stand-alone router
>-	  directly.</para>
>-      </example>
>-
>-      <example>
>-	<title>Head Office or Other LAN</title>
>-
>-	<indexterm><primary>10 base T</primary></indexterm>
>-	<para>Network uses a star topology with 10 base T Ethernet
>-  	  (<quote>Twisted Pair</quote>).</para>
>-
>-        <mediaobject>
>-          <imageobject>
>-            <imagedata fileref="advanced-networking/isdn-twisted-pair">
>-          </imageobject>
>-
>-	  <textobject>
>-	    <literallayout class="monospaced">    -------Novell Server
>-    | H |
>-    |   ---Sun
>-    |   |
>-    | U ---FreeBSD
>-    |   |
>-    |   ---Windows 95
>-    | B |
>-    |___---Stand-alone router
>-                |
>-        ISDN BRI line</literallayout>
>-	  </textobject>
>-
>-	  <textobject>
>-	    <phrase>ISDN Network Diagram</phrase>
>-	  </textobject>
>-	</mediaobject>
>-      </example>
>-
>-      <para>One large advantage of most routers/bridges is that they allow you
>-	to have 2 <emphasis>separate independent</emphasis> PPP connections to
>-	2 separate sites at the <emphasis>same</emphasis> time.  This is not
>-	supported on most TA's, except for specific (usually expensive) models
>-	that
>-	have two serial ports.  Do not confuse this with channel bonding, MPP,
>-	etc.</para>
>-
>-      <para>This can be a very useful feature if, for example, you
>-	have an dedicated ISDN connection at your office and would
>-	like to tap into it, but do not want to get another ISDN line
>-	at work.  A router at the office location can manage a
>-	dedicated B channel connection (64&nbsp;Kbps) to the Internet
>-	and use the other B channel for a separate data connection.
>-	The second B channel can be used for dial-in, dial-out or
>-	dynamically bonding (MPP, etc.) with the first B channel for
>-	more bandwidth.</para>
>-
>-      <indexterm><primary>IPX/SPX</primary></indexterm>
>-      <para>An Ethernet bridge will also allow you to transmit more than just
>-	IP traffic.  You can also send IPX/SPX or whatever other protocols you
>-	use.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="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>NIS/YP</title>
>-
>-    <sect2>
>-      <title>What Is It?</title>
>-      <indexterm><primary>NIS</primary></indexterm>
>-      <indexterm><primary>Solaris</primary></indexterm>
>-      <indexterm><primary>HP-UX</primary></indexterm>
>-      <indexterm><primary>AIX</primary></indexterm>
>-      <indexterm><primary>Linux</primary></indexterm>
>-      <indexterm><primary>NetBSD</primary></indexterm>
>-      <indexterm><primary>OpenBSD</primary></indexterm>
>-      <para>NIS, which stands for Network Information Services, was
>-        developed by Sun Microsystems to centralize administration of Unix
>-        (originally SunOS) systems.  It has now essentially become an
>-        industry standard; all major Unix systems (Solaris, HP-UX, AIX, Linux,
>-        NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para>
>-
>-      <indexterm><primary>yellow pages</primary><see>NIS</see></indexterm>
>-      <para>NIS was formerly known as Yellow Pages, but because of
>-	trademark issues, Sun changed the name.  The old term (and yp) is
>-	still often seen and used.</para>
>-
>-      <indexterm>
>-        <primary>NIS</primary>
>-        <secondary>domains</secondary>
>-      </indexterm>
>-      <para>It is a RPC-based client/server system that allows a group
>-	of machines within an NIS domain to share a common set of
>-	configuration files.  This permits a system administrator to set
>-	up NIS client systems with only minimal configuration data and
>-	add, remove or modify configuration data from a single
>-	location.</para>
>-
>-      <indexterm><primary>Windows NT</primary></indexterm>
>-      <para>It is similar to Windows NT's domain system; although the
>-        internal implementation of the two are not at all similar,
>-        the basic functionality can be compared.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Terms/Processes You Should Know</title>
>-
>-      <para>There are several terms and several important user processes
>-        that you will come across when
>-        attempting to implement NIS on FreeBSD, whether you are trying to
>-        create an NIS server or act as an NIS client:</para>
>-
>-      <indexterm>
>-	<primary><application>portmap</application></primary>
>-      </indexterm>
>-
>-      <informaltable>
>-	<tgroup cols="2">
>-	  <thead>
>-	    <row>
>-	      <entry>Term</entry>
>-	      <entry>Description</entry>
>-	    </row>
>-	  </thead>
>-	  <tbody>
>-	    <row>
>-	      <entry>NIS domainname</entry>
>-	      <entry>An NIS master server and all of its clients
>-		(including its slave servers) have a NIS
>-		domainname.  Similar to an NT domain name, the NIS
>-		domainname does not have anything to do with DNS.</entry>
>-	    </row>
>-	    <row>
>-	      <entry>portmap</entry>
>-	      <entry>Must be running in order to enable RPC (Remote
>-		Procedure Call, a network protocol used by NIS).  If
>-		<command>portmap</command> is not running, it will be
>-		impossible to run an NIS server, or to act as an NIS
>-		client.</entry>
>-	    </row>
>-	    <row>
>-	      <entry>ypbind</entry>
>-
>-	      <entry><quote>Binds</quote> an NIS client to its NIS
>-		server.  It will take the NIS domainname from the
>-		system, and using RPC, connect to the
>-		server.  <command>ypbind</command> is the core of
>-		client-server communication in an NIS environment; if
>-		<command>ypbind</command> dies on a client machine, it
>-		will not be able to access the NIS server.</entry>
>-	    </row>
>-	    <row>
>-	      <entry>ypserv</entry>
>-	      <entry>Should only be running on NIS servers; 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
>-		<command>ypbind</command> process on the client.
>-	      </entry>
>-	    </row>
>-	    <row>
>-	      <entry>rpc.yppasswdd</entry>
>-	      <entry>Another process that should only be running on
>-		NIS master servers; 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>
>-      
>-
>-    </sect2>
>-
>-    <sect2>
>-      <title>How Does It Work?</title>
>-
>-      <para>There are three types of hosts in an NIS environment: master
>-	servers, slave servers, and clients.  Servers act as a central
>-	repository for host configuration information.  Master servers
>-	hold the authoritative copy of this information, while slave
>-	servers mirror this information for redundancy.  Clients rely on
>-	the servers to provide this information to them.</para>
>-
>-      <para>Information in many files can be shared in this manner.  The
>-	<filename>master.passwd</filename>, <filename>group</filename>,
>-	and <filename>hosts</filename> files are commonly shared via NIS.
>-	Whenever a process on a client needs information that would
>-	normally be found in these files locally, it makes a query to the
>-	NIS server that it is bound to instead.</para>
>-
>-      <sect3>
>-        <title>Machine Types</title>
>-
>-        <itemizedlist>
>-	  <indexterm>
>-	    <primary>NIS</primary>
>-	    <secondary>master server</secondary>
>-	  </indexterm>
>-          <listitem>
>-            <para>A <emphasis>NIS master server</emphasis>.
>-              This server, analogous to a Windows
>-              NT primary domain controller, maintains the files used by all
>-              of the NIS clients.  The <filename>passwd</filename>,
>-              <filename>group</filename>, and other various files used by the
>-              NIS clients live on the master server.</para>
>-
>-            <note><para>It is possible for one machine to be an NIS
>-              master server for more than one NIS domain.  However, this will
>-              not be covered in this introduction, which assumes a relatively
>-              small-scale NIS environment.</para></note>
>-          </listitem>
>-	  <indexterm>
>-	    <primary>NIS</primary>
>-	    <secondary>slave server</secondary>
>-	  </indexterm>
>-          <listitem>
>-            <para><emphasis>NIS slave servers</emphasis>.
>-              Similar to NT's backup domain
>-              controllers, NIS slave servers maintain copies of the NIS
>-              master's data files.  NIS slave servers provide the redundancy,
>-              which is needed in important environments.  They also help
>-              to balance the load of the master server:  NIS Clients always
>-              attach to the NIS server whose response they get first, and
>-              this includes slave-server-replies.</para>
>-          </listitem>
>-	  <indexterm>
>-	    <primary>NIS</primary>
>-	    <secondary>client</secondary>
>-	  </indexterm>
>-          <listitem>
>-            <para><emphasis>NIS clients</emphasis>.  NIS clients, like most
>-              NT workstations, authenticate against the NIS server (or the NT
>-              domain controller in the NT Workstation case) to log on.</para>
>-          </listitem>
>-        </itemizedlist>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Using NIS/YP</title>
>-
>-      <para>This section will deal with setting up a sample NIS
>-        environment.</para>
>-
>-      <note><para>This section assumes that you are running FreeBSD&nbsp;3.3
>-        or later.  The instructions given here will
>-        <emphasis>probably</emphasis> work for any version of FreeBSD greater
>-        than 3.0, but there are no guarantees that this is
>-        true.</para></note>
>-
>-
>-      <sect3>
>-        <title>Planning</title>
>-
>-        <para>Let us assume that you are the administrator of a small
>-          university lab.  This lab, which consists of 15 FreeBSD machines,
>-          currently has no centralized point of administration;  each machine
>-          has its own <filename>/etc/passwd</filename> and
>-          <filename>/etc/master.passwd</filename>.  These files are kept in
>-          sync with each other only through manual intervention;
>-          currently, when you add a user to the lab, you must run
>-          <command>adduser</command> on all 15 machines.
>-          Clearly, this has to change, so you have decided to convert the
>-          lab to use NIS, using two of the machines as servers.</para>
>-
>-        <para>Therefore, the configuration of the lab now looks something
>-          like:</para>
>-
>-        <informaltable>
>-          <tgroup cols="3">
>-            <thead>
>-              <row>
>-                <entry>Machine name</entry>
>-                <entry>IP address</entry>
>-                <entry>Machine role</entry>
>-              </row>
>-            </thead>
>-            <tbody>
>-              <row>
>-                <entry><hostid>ellington</hostid></entry>
>-                <entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
>-                <entry>NIS master</entry>
>-              </row>
>-              <row>
>-                <entry><hostid>coltrane</hostid></entry>
>-                <entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
>-                <entry>NIS slave</entry>
>-              </row>
>-              <row>
>-                <entry><hostid>basie</hostid></entry>
>-                <entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
>-                <entry>Faculty workstation</entry>
>-              </row>
>-              <row>
>-                <entry><hostid>bird</hostid></entry>
>-                <entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
>-                <entry>Client machine</entry>
>-              </row>
>-              <row>
>-                <entry><hostid>cli[1-11]</hostid></entry>
>-                <entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
>-                <entry>Other client machines</entry>
>-              </row>
>-            </tbody>
>-          </tgroup>
>-        </informaltable>
>-
>-        <para>If you are setting up a NIS scheme for the first time, it
>-	  is a good idea to think through how you want to go about it.  No
>-	  matter what the size of your network, there are a few decisions
>-	  that need to be made.</para>
>-
>-        <sect4>
>-          <title>Choosing a NIS Domain Name</title>
>-
>-	  <indexterm>
>-	    <primary>NIS</primary>
>-	    <secondary>domainname</secondary>
>-	  </indexterm>
>-          <para>This might not be the <quote>domainname</quote> that you
>-	    are used to.  It is more accurately called the
>-	    <quote>NIS domainname</quote>.  When a client broadcasts its
>-	    requests for info, it includes the name of the NIS domain
>-	    that it is part of.  This is how multiple servers on one
>-	    network can tell which server should answer which request.
>-	    Think of the NIS domainname as the name for a group of hosts
>-	    that are related in some way.</para>
>-
>-	  <para>Some organizations choose to use their Internet
>-	    domainname for their NIS domainname.  This is not
>-	    recommended as it can cause confusion when trying to debug
>-	    network problems.  The NIS domainname should be unique
>-	    within your network and it is helpful if it describes the
>-	    group of machines it represents.  For example, the Art
>-	    department at Acme Inc. might be in the
>-	    <quote>acme-art</quote> NIS domain.  For this example,
>-	    assume you have chosen the name
>-	    <emphasis>test-domain</emphasis>.</para>
>-
>-	  <indexterm><primary>SunOS</primary></indexterm>
>-          <para>However, some operating systems (notably SunOS) use their
>-            NIS domain name as their Internet domain name.
>-            If one or more machines on your network have this restriction,
>-            you <emphasis>must</emphasis> use the Internet domain name as
>-            your NIS domain name.</para>
>-        </sect4>
>-
>-        <sect4>
>-          <title>Physical Server Requirements</title>
>-
>-	  <para>There are several things to keep in mind when choosing a
>-	    machine to use as a NIS server.  One of the unfortunate things
>-	    about NIS is the level of dependency the clients have on the
>-	    server.  If a client cannot contact the server for its NIS
>-	    domain, very often the machine becomes unusable.  The lack of
>-	    user and group information causes most systems to temporarily
>-	    freeze up.  With this in mind you should make sure to choose a
>-	    machine that will not be prone to being rebooted regularly, or
>-	    one that might be used for development.  The NIS server should
>-	    ideally be a stand alone machine whose sole purpose in life is
>-	    to be an NIS server.  If you have a network that is not very
>-	    heavily used, it is acceptable to put the NIS server on a
>-	    machine running other services, just keep in mind that if the
>-	    NIS server becomes unavailable, it will affect
>-	    <emphasis>all</emphasis> of your NIS clients adversely.</para>
>-        </sect4>
>-      </sect3>
>-
>-      <sect3>
>-        <title>NIS Servers</title>
>-
>-	<para> The canonical copies of all NIS information are stored on
>-	  a single machine called the NIS master server.  The databases
>-	  used to store the information are called NIS maps.  In FreeBSD,
>-	  these maps are stored in
>-	  <filename>/var/yp/[domainname]</filename> where
>-	  <filename>[domainname]</filename> is the name of the NIS domain
>-	  being served.  A single NIS server can support several domains
>-	  at once, therefore it is possible to have several such
>-	  directories, one for each supported domain.  Each domain will
>-	  have its own independent set of maps.</para>
>-
>-	<para>NIS master and slave servers handle all NIS requests with
>-	  the <command>ypserv</command> daemon.  <command>ypserv</command>
>-	  is responsible for receiving incoming requests from NIS clients,
>-	  translating the requested domain and map name to a path to the
>-	  corresponding database file and transmitting data from the
>-	  database back to the client.</para>
>-
>-        <sect4>
>-	  <title>Setting Up a NIS Master Server</title>
>-	  <indexterm>
>-	    <primary>NIS</primary>
>-	    <secondary>server configuration</secondary>
>-	  </indexterm>
>-	  <para>Setting up a master NIS server can be relatively straight
>-	    forward, depending on your needs.  FreeBSD comes with support
>-            for NIS out-of-the-box.  All you need is to add the following
>-            lines to <filename>/etc/rc.conf</filename>, and FreeBSD will
>-            do the rest for you.</para>
>-
>-          <procedure>
>-            <step>
>-              <para><programlisting>nisdomainname="test-domain"</programlisting>
>-                This line will set the NIS domainname to
>-                <emphasis>test-domain</emphasis>
>-                upon network setup (e.g. after reboot).</para>
>-            </step>
>-            <step>
>-              <para><programlisting>nis_server_enable="YES"</programlisting>
>-                This will tell FreeBSD to start up the NIS server processes
>-                when the networking is next brought up.</para>
>-            </step>
>-            <step>
>-              <para><programlisting>nis_yppasswdd_enable="YES"</programlisting>
>-                This will enable the <command>rpc.yppasswdd</command>
>-                daemon which, as mentioned above, will allow users to
>-                change their NIS password from a client machine.</para>
>-            </step>
>-          </procedure>
>-
>-          <note>
>-            <para>Depending on your NIS setup, you may need to add
>-              further entries.  See the <link
>-              linkend="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 <emphasis>test-domain</emphasis> has
>-            a slave server as well, you must edit
>-            <filename>/var/yp/Makefile</filename>:</para>
>-
>-          <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen>
>-
>-	  <para>You should comment out the line that says</para>
>-
>-	  <programlisting>NOPUSH = "True"</programlisting>
>-
>-	  <para>(if it is not commented out already).</para>
>-        </sect4>
>-
>-        <sect4>
>-	  <title>Setting up a NIS Slave Server</title>
>-	  <indexterm>
>-	    <primary>NIS</primary>
>-	    <secondary>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 root, and fix things.</para>
>-              </note>
>-            </step>
>-
>-	    <step>
>-	      <para>To import all possible group entries from the NIS
>-		server, add this line to your
>-		<filename>/etc/group</filename> file:</para>
>-
>-	      <programlisting>+:*::</programlisting>
>-	    </step>
>-	  </procedure>
>-
>-	  <para>After completing these steps, you should be able to run
>-	    <command>ypcat passwd</command> and see the NIS server's
>-	    passwd map.</para>
>-	</sect4>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2>
>-      <title>NIS Security</title>
>-
>-      <para>In general, any remote user can issue an RPC to
>-	&man.ypserv.8; and retrieve the contents of your NIS maps,
>-	provided the remote user knows your domainname.  To prevent
>-	such unauthorized transactions, &man.ypserv.8; supports a
>-	feature called securenets which can be used to restrict access
>-	to a given set of hosts.  At startup, &man.ypserv.8; will
>-	attempt to load the securenets information from a file called
>-	<filename>/var/yp/securenets</filename>.</para>
>-
>-      <note>
>-	<para>This path varies depending on the path specified with the
>-	  <option>-p</option> option.  This file contains entries that
>-	  consist of a network specification and a network mask separated
>-	  by white space.  Lines starting with <quote>#</quote> are
>-	  considered to be comments.  A sample securenets file might look
>-	  like this:</para>
>-      </note>
>-
>-      <programlisting># allow connections from local host -- mandatory
>-127.0.0.1     255.255.255.255
>-# allow connections from any host
>-# on the 192.168.128.0 network
>-192.168.128.0 255.255.255.0
>-# allow connections from any host
>-# between 10.0.0.0 to 10.0.15.255
>-# this includes the machines in the testlab
>-10.0.0.0      255.255.240.0</programlisting>
>-
>-      <para>If &man.ypserv.8; receives a request from an address that
>-	matches one of these rules, it will process the request
>-	normally.  If the address fails to match a rule, the request
>-	will be ignored and a warning message will be logged.  If the
>-	<filename>/var/yp/securenets</filename> file does not exist,
>-	<command>ypserv</command> will allow connections from any
>-	host.</para>
>-
>-      <para>The <command>ypserv</command> program also has support for Wietse
>-	Venema's
>-	<application>tcpwrapper</application> package.  This allows the
>-	administrator to use the <application>tcpwrapper</application> configuration
>-	files for access control instead of
>-	<filename>/var/yp/securenets</filename>.</para>
>-
>-      <note>
>-        <para>While both of these access control mechanisms provide some
>-          security, they, like the privileged port test, are
>-          vulnerable to <quote>IP spoofing</quote> attacks.  All
>-          NIS-related traffic should be blocked at your firewall.</para>
>-
>-        <para>Servers using <filename>/var/yp/securenets</filename>
>-          may fail to serve legitimate NIS clients with archaic TCP/IP
>-          implementations.  Some of these implementations set all
>-          host bits to zero when doing broadcasts and/or fail to
>-          observe the subnet mask when calculating the broadcast
>-          address.  While some of these problems can be fixed by
>-          changing the client configuration, other problems may force
>-          the retirement of the client systems in question or the
>-          abandonment of <filename>/var/yp/securenets</filename>.</para>
>-
>-        <para>Using <filename>/var/yp/securenets</filename> on a
>-          server with such an archaic implementation of TCP/IP is a
>-          really bad idea and will lead to loss of NIS functionality
>-          for large parts of your network.</para>
>-
>-	<indexterm><primary>tcpwrapper</primary></indexterm>
>-        <para>The use of the <application>tcpwrapper</application>
>-          package increases the latency of your NIS server.  The
>-          additional delay may be long enough to cause timeouts in
>-          client programs, especially in busy networks or with slow
>-          NIS servers.  If one or more of your client systems
>-          suffers from these symptoms, you should convert the client
>-          systems in question into NIS slave servers and force them
>-          to bind to themselves.</para>
>-      </note>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Barring Some Users from Logging On</title>
>-
>-      <para>In our lab, there is a machine <hostid>basie</hostid> that is
>-        supposed to be a faculty only workstation.  We do not want to take this
>-         machine out of the NIS domain, yet the <filename>passwd</filename>
>-       file on the master NIS server contains accounts for both faculty and
>-        students.  What can we do?</para>
>-
>-      <para>There is a way to bar specific users from logging on to a
>-        machine, even if they are present in the NIS database.  To do this,
>-        all you must do is add
>-        <emphasis>-<replaceable>username</replaceable></emphasis> to the end of
>-        the <filename>/etc/master.passwd</filename> file on the client
>-        machine, where <replaceable>username</replaceable> is the username of
>-        the user you wish to bar from logging in.  This should preferably be
>-        done using <command>vipw</command>, since <command>vipw</command>
>-        will sanity check your changes to
>-        <filename>/etc/master.passwd</filename>, as well as
>-        automatically rebuild the password database when you
>-        finish editing.  For example, if we wanted to bar user
>-        <emphasis>bill</emphasis> from logging on to <hostid>basie</hostid>
>-        we would:</para>
>-
>-        <screen>basie&prompt.root; <userinput>vipw</userinput>
>-<userinput>[add -bill to the end, exit]</userinput>
>-vipw: rebuilding the database...
>-vipw: done
>-
>-basie&prompt.root; <userinput>cat /etc/master.passwd</userinput>
>-
>-root:[password]:0:0::0:0:The super-user:/root:/bin/csh
>-toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
>-daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
>-operator:*:2:5::0:0:System &:/:/sbin/nologin
>-bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
>-tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
>-kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
>-games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
>-news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
>-man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
>-bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
>-uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
>-xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
>-pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
>-nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
>-+:::::::::
>--bill
>-
>-basie&prompt.root;</screen>
>-    </sect2>
>-
>-    <sect2 id="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>
>-        <tgroup cols="2">
>-          <thead>
>-            <row>
>-              <entry>User Name(s)</entry>
>-              <entry>Description</entry>
>-            </row>
>-          </thead>
>-
>-          <tbody>
>-            <row>
>-              <entry>alpha, beta</entry>
>-              <entry>Normal employees of the IT department</entry>
>-            </row>
>-
>-            <row>
>-              <entry>charlie, delta</entry>
>-              <entry>The new apprentices of the IT department</entry>
>-            </row>
>-
>-            <row>
>-              <entry>echo, foxtrott, golf, ...</entry>
>-              <entry>Ordinary employees</entry>
>-            </row>
>-
>-            <row>
>-              <entry>able, baker, ...</entry>
>-              <entry>The current interns</entry>
>-            </row>
>-          </tbody>
>-        </tgroup>
>-      </informaltable>
>-
>-      <informaltable>
>-        <tgroup cols="2">
>-          <thead>
>-            <row>
>-              <entry>Machine Name(s)</entry>
>-              <entry>Description</entry>
>-            </row>
>-          </thead>
>-
>-          <tbody>
>-            <row>
>-              
>-              <entry>war, death, famine, pollution</entry>
>-              <entry>Your most important servers.  Only the IT
>-                employees are allowed to log onto these
>-                machines.</entry>
>-            </row>
>-            <row>
>-              
>-              <entry>pride, greed, envy, wrath, lust, sloth</entry>
>-              <entry>Less important servers.  All members of the IT
>-                department are allowed to login onto these machines.</entry>
>-            </row>
>-
>-            <row>
>-              <entry>one, two, three, four, ...</entry>
>-              <entry>Ordinary workstations.  Only the
>-                <emphasis>real</emphasis> employees are allowed to use
>-                these machines.</entry>
>-            </row>
>-
>-            <row>
>-              <entry>trashcan</entry>
>-              <entry>A very old machine without any critical data.
>-                Even the intern is allowed to use this box.</entry>
>-            </row>
>-          </tbody>
>-        </tgroup>
>-      </informaltable>
>-
>-      <para>If you tried to implement these restrictions by separately
>-        blocking each user, you would have to add one
>-        -<replaceable>user</replaceable> line to each system's
>-	<filename>passwd</filename>
>-        for each user who is not allowed to login onto that system.
>-        If you forget just one entry, you could be in trouble.  It may
>-        be feasible to do this correctly during the initial setup,
>-        however you <emphasis>will</emphasis> eventually forget to add
>-        the lines for new users during day-to-day operations.  After
>-        all, Murphy was an optimist.</para>
>-
>-      <para>Handling this situation with netgroups offers several
>-        advantages.  Each user need not be handled separately;
>-        you assign a user to one or more netgroups and allow or forbid
>-        logins for all members of the netgroup.  If you add a new
>-        machine, you will only have to define login restrictions for
>-        netgroups.  If a new user is added, you will only have to add
>-        the user to one or more netgroups.  Those changes are
>-        independent of each other; no more <quote>for each combination
>-        of user and machine do...</quote> If your NIS setup is planned
>-        carefully, you will only have to modify exactly one central
>-        configuration file to grant or deny access to machines.</para>
>-
>-      <para>The first step is the initialization of the NIS map
>-        netgroup.  FreeBSD's &man.ypinit.8; does not create this map by
>-        default, but its NIS implementation will support it once it has
>-        been created.  To create an empty map, simply type</para>
>-
>-      <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>
>-
>-      <para>and start adding content.  For our example, we need at
>-         least four netgroups: IT employees, IT apprentices, normal
>-         employees and interns.</para>
>-
>-      <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
>-IT_APP  (,charlie,test-domain)  (,delta,test-domain)
>-USERS   (,echo,test-domain)     (,foxtrott,test-domain) \
>-        (,golf,test-domain)
>-INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>
>-
>-      <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
>-        are the names of the netgroups.  Each bracketed group adds
>-        one or more user accounts to it.  The three fields inside a
>-        group are:</para>
>-
>-      <orderedlist>
>-        <listitem>
>-          <para>The name of the host(s) where the following items are
>-            valid.  If you do not specify a hostname, the entry is
>-            valid on all hosts.  If you do specify a hostname, you
>-            will enter a realm of darkness, horror and utter confusion.</para>
>-        </listitem>
>-
>-        <listitem>
>-          <para>The name of the account that belongs to this
>-            netgroup.</para>
>-        </listitem>
>-
>-        <listitem>
>-          <para>The NIS domain for the account.  You can import
>-            accounts from other NIS domains into your netgroup if you
>-            are one of the unlucky fellows with more than one NIS
>-            domain.</para>
>-        </listitem>
>-      </orderedlist>
>-
>-      <para>Each of these fields can contain wildcards.  See
>-        &man.netgroup.5; for details.</para>
>-
>-      <note>
>-        <indexterm><primary>netgroups</primary></indexterm>
>-        <para>Netgroup names longer than 8 characters should not be
>-          used, especially if you have machines running other
>-          operating systems within your NIS domain.  The names are
>-          case sensitive; using capital letters for your netgroup
>-          names is an easy way to distinguish between user, machine
>-          and netgroup names.</para>
>-
>-        <para>Some NIS clients (other than FreeBSD) cannot handle
>-          netgroups with a large number of entries.  For example, some
>-          older versions of SunOS start to cause trouble if a netgroup
>-          contains more than 15 <emphasis>entries</emphasis>.  You can
>-          circumvent this limit by creating several sub-netgroups with
>-          15 users or less and a real netgroup that consists of the
>-          sub-netgroups:</para>
>-
>-        <programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
>-BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
>-BIGGRP3  (,joe31,domain)  (,joe32,domain)
>-BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>
>-
>-        <para>You can repeat this process if you need more than 225
>-          users within a single netgroup.</para>
>-      </note>
>-
>-      <para>Activating and distributing your new NIS map is
>-        easy:</para>
>-
>-      <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
>-ellington&prompt.root; <userinput>make</userinput></screen>
>-
>-      <para>This will generate the three NIS maps
>-        <filename>netgroup</filename>,
>-        <filename>netgroup.byhost</filename> and
>-        <filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
>-        check if your new NIS maps are available:</para>
>-
>-      <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
>-ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
>-ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>
>-
>-      <para>The output of the first command should resemble the
>-        contents of <filename>/var/yp/netgroup</filename>.  The second
>-        command will not produce output if you have not specified
>-        host-specific netgroups.  The third command can be used to
>-        get the list of netgroups for a user.</para>
>-
>-      <para>The client setup is quite simple.  To configure the server
>-        <replaceable>war</replaceable>, you only have to start
>-        &man.vipw.8; and replace the line</para>
>-
>-      <programlisting>+:::::::::</programlisting>
>-
>-      <para>with</para>
>-
>-      <programlisting>+@IT_EMP:::::::::</programlisting>
>-
>-      <para>Now, only the data for the users defined in the netgroup
>-        <replaceable>IT_EMP</replaceable> is imported into
>-        <replaceable>war</replaceable>'s password database and only
>-        these users are allowed to login.</para>
>-
>-      <para>Unfortunately, this limitation also applies to the ~
>-	function of the shell and all routines converting between user
>-	names and numerical user IDs.  In other words,
>-	<command>cd ~<replaceable>user</replaceable></command> will not work,
>-	<command>ls -l</command> will show the numerical id instead of
>-	the username and <command>find . -user joe -print</command> will
>-	fail with <errorname>No such user</errorname>.  To fix this, you will
>-	have to import all user entries <emphasis>without allowing them
>-	to login onto your servers</emphasis>.</para>
>-
>-      <para>This can be achieved by adding another line to
>-        <filename>/etc/master.passwd</filename>.  This line should
>-        contain:</para>
>-
>-      <para><literal>+:::::::::/sbin/nologin</literal>, meaning
>-        <quote>Import all entries but replace the shell with
>-        <filename>/sbin/nologin</filename> in the imported
>-        entries</quote>.  You can replace any field
>-        in the passwd entry by placing a default value in your
>-        <filename>/etc/master.passwd</filename>.</para>
>-
>-      
>-      <warning>
>-        <para>Make sure that the line
>-        <literal>+:::::::::/sbin/nologin</literal> is placed after
>-        <literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
>-        accounts imported from NIS will have /sbin/nologin as their
>-        login shell.</para>
>-      </warning>
>-
>-      <para>After this change, you will only have to change one NIS
>-        map if a new employee joins the IT department.  You could use
>-        a similar approach for the less important servers by replacing
>-        the old <literal>+:::::::::</literal> in their local version
>-        of <filename>/etc/master.passwd</filename> with something like
>-        this:</para>
>-
>-      <programlisting>+@IT_EMP:::::::::
>-+@IT_APP:::::::::
>-+:::::::::/sbin/nologin</programlisting>
>-
>-      <para>The corresponding lines for the normal workstations
>-        could be:</para>
>-
>-      <programlisting>+@IT_EMP:::::::::
>-+@USERS:::::::::
>-+:::::::::/sbin/nologin</programlisting>
>-
>-      <para>And everything would be fine until there is a policy
>-        change a few weeks later:  The IT department starts hiring
>-        interns.  The IT interns are allowed to use the normal
>-        workstations and the less important servers; and the IT
>-        apprentices are allowed to login onto the main servers.  You
>-        add a new netgroup IT_INTERN, add the new IT interns to this
>-        netgroup and start to change the config on each and every
>-        machine...  As the old saying goes:  <quote>Errors in
>-        centralized planning lead to global mess</quote>.</para>
>-
>-      <para>NIS' ability to create netgroups from other netgroups can
>-        be used to prevent situations like these.  One possibility
>-        is the creation of role-based netgroups.  For example, you
>-        could create a netgroup called
>-        <replaceable>BIGSRV</replaceable> to define the login
>-        restrictions for the important servers, another netgroup
>-        called <replaceable>SMALLSRV</replaceable> for the less
>-        important servers and a third netgroup called
>-        <replaceable>USERBOX</replaceable> for the normal
>-        workstations.  Each of these netgroups contains the netgroups
>-        that are allowed to login onto these machines.  The new
>-        entries for your NIS map netgroup should look like this:</para>
>-
>-      <programlisting>BIGSRV    IT_EMP  IT_APP
>-SMALLSRV  IT_EMP  IT_APP  ITINTERN
>-USERBOX   IT_EMP  ITINTERN USERS</programlisting>
>-
>-      <para>This method of defining login restrictions works
>-        reasonably well if you can define groups of machines with
>-        identical restrictions.  Unfortunately, this is the exception
>-        and not the rule.  Most of the time, you will need the ability
>-        to define login restrictions on a per-machine basis.</para>
>-
>-      <para>Machine-specific netgroup definitions are the other
>-        possibility to deal with the policy change outlined above.  In
>-        this scenario, the <filename>/etc/master.passwd</filename> of
>-        each box contains two lines starting with <quote>+</quote>.
>-        The first of them adds a netgroup with the accounts allowed to
>-        login onto this machine, the second one adds all other
>-        accounts with <filename>/sbin/nologin</filename> as shell.  It
>-        is a good idea to use the ALL-CAPS version of the machine name
>-        as the name of the netgroup.  In other words, the lines should
>-        look like this:</para>
>-
>-      <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
>-+:::::::::/sbin/nologin</programlisting>
>-
>-      <para>Once you have completed this task for all your machines,
>-        you will not have to modify the local versions of
>-        <filename>/etc/master.passwd</filename> ever again.  All
>-        further changes can be handled by modifying the NIS map.  Here
>-        is an example of a possible netgroup map for this
>-        scenario with some additional goodies.</para>
>-
>-      <programlisting># Define groups of users first
>-IT_EMP    (,alpha,test-domain)    (,beta,test-domain)
>-IT_APP    (,charlie,test-domain)  (,delta,test-domain)
>-DEPT1     (,echo,test-domain)     (,foxtrott,test-domain)
>-DEPT2     (,golf,test-domain)     (,hotel,test-domain)
>-DEPT3     (,india,test-domain)    (,juliet,test-domain)
>-ITINTERN  (,kilo,test-domain)     (,lima,test-domain)
>-D_INTERNS (,able,test-domain)     (,baker,test-domain)
>-#
>-# Now, define some groups based on roles
>-USERS     DEPT1   DEPT2     DEPT3
>-BIGSRV    IT_EMP  IT_APP
>-SMALLSRV  IT_EMP  IT_APP    ITINTERN
>-USERBOX   IT_EMP  ITINTERN  USERS
>-#
>-# And a groups for a special tasks
>-# Allow echo and golf to access our anti-virus-machine
>-SECURITY  IT_EMP  (,echo,test-domain)  (,golf,test-domain)
>-#
>-# machine-based netgroups
>-# Our main servers
>-WAR       BIGSRV
>-FAMINE    BIGSRV
>-# User india needs access to this server
>-POLLUTION  BIGSRV  (,india,test-domain)
>-#
>-# This one is really important and needs more access restrictions
>-DEATH     IT_EMP
>-#
>-# The anti-virus-machine mentioned above
>-ONE       SECURITY
>-#
>-# Restrict a machine to a single user
>-TWO       (,hotel,test-domain)
>-# [...more groups to follow]</programlisting>
>-
>-      <para>If you are using some kind of database to manage your user
>-        accounts, you should be able to create the first part of the
>-        map with your database's report tools.  This way, new users
>-        will automatically have access to the boxes.</para>
>-
>-      <para>One last word of caution: It may not always be advisable
>-        to use machine-based netgroups.  If you are deploying a couple of
>-        dozen or even hundreds of identical machines for student labs,
>-        you should use role-based netgroups instead of machine-based
>-        netgroups to keep the size of the NIS map within reasonable
>-        limits.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Important Things to Remember</title>
>-
>-      <para>There are still a couple of things that you will need to do
>-        differently now that you are in an NIS environment.</para>
>-
>-      <itemizedlist>
>-        <listitem>
>-          <para>Every time you wish to add a user to the lab, you
>-            must add it to the master NIS server <emphasis>only</emphasis>,
>-            and <emphasis>you must remember to rebuild the NIS
>-            maps</emphasis>.  If you forget to do this, the new user will
>-            not be able to login anywhere except on the NIS master.
>-            For example, if we needed to add a new user
>-            <quote>jsmith</quote> to the lab, we would:</para>
>-
>-          <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
>-&prompt.root; <userinput>cd /var/yp</userinput>
>-&prompt.root; <userinput>make test-domain</userinput></screen>
>-
>-          <para>You could also run <command>adduser jsmith</command> instead
>-            of <command>pw useradd jsmith</command>.</para>
>-        </listitem>
>-        <listitem>
>-          <para><emphasis>Keep the administration accounts out of the NIS
>-            maps</emphasis>.  You do not want to be propagating administrative
>-            accounts and passwords to machines that will have users that
>-            should not have access to those accounts.</para>
>-        </listitem>
>-        <listitem>
>-          <para><emphasis>Keep the NIS master and slave
>-            secure, and minimize their downtime</emphasis>.
>-            If somebody either hacks or simply turns off
>-            these machines, they have effectively rendered many people without
>-            the ability to login to the lab.</para>
>-
>-          <para>This is the chief weakness of any centralized administration
>-            system, and it is probably the most important weakness.  If you do
>-            not protect your NIS servers, you will have a lot of angry
>-            users!</para>
>-        </listitem>
>-      </itemizedlist>
>-    </sect2>
>-
>-    <sect2>
>-      <title>NIS v1 Compatibility</title>
>-
>-      <para> FreeBSD's <application>ypserv</application> has some support
>-	for serving NIS v1 clients.  FreeBSD's NIS implementation only
>-	uses the NIS v2 protocol, however other implementations include
>-	support for the v1 protocol for backwards compatibility with older
>-	systems.  The <application>ypbind</application> daemons supplied
>-	with these systems will try to establish a binding to an NIS v1
>-	server even though they may never actually need it (and they may
>-	persist in broadcasting in search of one even after they receive a
>-	response from a v2 server).  Note that while support for normal
>-	client calls is provided, this version of ypserv does not handle
>-	v1 map transfer requests; consequently, it cannot be used as a
>-	master or slave in conjunction with older NIS servers that only
>-	support the v1 protocol.  Fortunately, there probably are not any
>-	such servers still in use today.</para>
>-    </sect2>
>-
>-    <sect2 id="network-nis-server-is-client">
>-      <title>NIS Servers That Are Also NIS Clients</title>
>-
>-      <para> Care must be taken when running ypserv in a multi-server
>-	domain where the server machines are also NIS clients.  It is
>-	generally a good idea to force the servers to bind to themselves
>-	rather than allowing them to broadcast bind requests and possibly
>-	become bound to each other.  Strange failure modes can result if
>-	one server goes down and others are dependent upon it.
>-	Eventually all the clients will time out and attempt to bind to
>-	other servers, but the delay involved can be considerable and the
>-	failure mode is still present since the servers might bind to each
>-	other all over again.</para>
>-
>-      <para>You can force a host to bind to a particular server by running
>-	<command>ypbind</command> with the <option>-S</option>
>-	flag.  If you do not want to do this manually each time you
>-        reboot your NIS server, you can add the following lines to
>-        your <filename>/etc/rc.conf</filename>:</para>
>-
>-      <programlisting>nis_client_enable="YES"	# run client stuff as well
>-nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting>
>-
>-      <para>See &man.ypbind.8; for further information.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>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 their 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>DHCP</title>
>-
>-    <sect2>
>-      <title>What Is DHCP?</title>
>-      <indexterm>
>-        <primary>Dynamic Host Configuration Protocol</primary>
>-        <see>DHCP</see>
>-      </indexterm>
>-      <indexterm>
>-        <primary>Internet Software Consortium (ISC)</primary>
>-      </indexterm>
>-
>-      <para>DHCP, the Dynamic Host Configuration Protocol, describes
>-        the means by which a system can connect to a network and obtain the
>-        necessary information for communication upon that network.  FreeBSD
>-        uses the ISC (Internet Software Consortium) DHCP implementation, so
>-        all implementation-specific information here is for use with the ISC
>-        distribution.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>What This Section Covers</title>
>-
>-      <para>This section describes both the client-side and server-side
>-        components of the ISC DHCP system.  The client-side program,
>-        <command>dhclient</command>, comes integrated within FreeBSD, and
>-        the server-side portion is available from the
>-        <filename role="package">net/isc-dhcp3</filename> port.  The
>-        &man.dhclient.8;, &man.dhcp-options.5;, and &man.dhclient.conf.5;
>-        manual pages, in addition to the references below, are useful
>-        resources.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>How It Works</title>
>-      <indexterm><primary>UDP</primary></indexterm>
>-      <para>When <command>dhclient</command>, the DHCP client, is
>-	executed on the client machine, it begins broadcasting
>-	requests for configuration information.  By default, these
>-	requests are on UDP port 68.  The server replies on UDP 67,
>-	giving the client an IP address and other relevant network
>-	information such as netmask, router, and DNS servers.  All of
>-	this information comes in the form of a DHCP
>-	<quote>lease</quote> and is only valid for a certain time
>-	(configured by the DHCP server maintainer).  In this manner,
>-	stale IP addresses for clients no longer connected to the
>-	network can be automatically reclaimed.</para>
>-
>-      <para>DHCP clients can obtain a great deal of information from
>-        the server.  An exhaustive list may be found in
>-        &man.dhcp-options.5;.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>FreeBSD Integration</title>
>-
>-      <para>FreeBSD fully integrates the ISC DHCP client,
>-        <command>dhclient</command>.  DHCP client support is provided
>-        within both the installer and the base system, obviating the need
>-        for detailed knowledge of network configurations on any network
>-        that runs a DHCP server.  <command>dhclient</command> has been
>-        included in all FreeBSD distributions since 3.2.</para>
>-        <indexterm>
>-          <primary><application>sysinstall</application></primary>
>-        </indexterm>
>-
>-        <para>DHCP is supported by
>-          <application>sysinstall</application>.  When configuring a
>-          network interface within sysinstall, the first question
>-          asked is, <quote>Do you want to try DHCP configuration of
>-          this interface?</quote> Answering affirmatively will execute
>-          <command>dhclient</command>, and if successful, will fill in
>-          the network configuration information automatically.</para>
>-
>-        <para>There are two things you must do to have your system use
>-	  DHCP upon startup:</para>
>-        <indexterm>
>-          <primary>DHCP</primary>
>-          <secondary>requirements</secondary>
>-        </indexterm>
>-	<itemizedlist>
>-	  <listitem>
>-            <para>Make sure that the <devicename>bpf</devicename>
>-	      device is compiled into your kernel.  To do this, add
>-	      <literal>pseudo-device bpf</literal> to your kernel
>-	      configuration file, and rebuild the kernel.  For more
>-	      information about building kernels, see <xref
>-	      linkend="kernelconfig">.</para>
>-	    <para>The <devicename>bpf</devicename> device is already
>-	      part of the <filename>GENERIC</filename> kernel that is
>-	      supplied with FreeBSD, so if you do not have a custom
>-	      kernel, you should not need to create one in order to get
>-	      DHCP working.</para>
>-	    <note>
>-	      <para>For those who are particularly security conscious,
>-	        you should be warned that <devicename>bpf</devicename>
>-		is also the device that allows packet sniffers to work
>-		correctly (although they still have to be run as
>-		<username>root</username>).  <devicename>bpf</devicename>
>-		<emphasis>is</emphasis> required to use DHCP, but if
>-		you are very sensitive about security, you probably
>-		should not add <devicename>bpf</devicename> to your
>-		kernel in the expectation that at some point in the
>-		future you will be using DHCP.</para>
>-	    </note>
>-	  </listitem>
>-          <listitem>
>-            <para>Edit your <filename>/etc/rc.conf</filename> to
>-	      include the following:</para>
>-
>-            <programlisting>ifconfig_fxp0="DHCP"</programlisting>
>-
>-            <note>
>-              <para>Be sure to replace <literal>fxp0</literal> with the
>-                designation for the interface that you wish to dynamically
>-                 configure, 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, <command>dhcpd</command>, is included
>-          as part of the <filename
>-          role="package">net/isc-dhcp3</filename> port in the ports
>-          collection.  This port contains the full ISC DHCP
>-          distribution, consisting of client, server, relay agent and
>-          documentation.
>-          </para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Files</title>
>-      <indexterm>
>-        <primary>DHCP</primary>
>-        <secondary>configuration files</secondary>
>-      </indexterm>
>-      <itemizedlist>
>-        <listitem><para><filename>/etc/dhclient.conf</filename></para>
>-          <para><command>dhclient</command> requires a configuration file,
>-            <filename>/etc/dhclient.conf</filename>.  Typically the file
>-            contains only comments, the defaults being reasonably sane.  This
>-            configuration file is described by the &man.dhclient.conf.5;
>-            manual page.</para>
>-        </listitem>
>-
>-        <listitem><para><filename>/sbin/dhclient</filename></para>
>-          <para><command>dhclient</command> is statically linked and
>-            resides in <filename>/sbin</filename>.  The &man.dhclient.8;
>-            manual page gives more information about
>-            <command>dhclient</command>.</para>
>-        </listitem>
>-
>-        <listitem><para><filename>/sbin/dhclient-script</filename></para>
>-          <para><command>dhclient-script</command> is the FreeBSD-specific
>-            DHCP client configuration script.  It is described in
>-            &man.dhclient-script.8;, but should not need any user
>-            modification to function properly.</para>
>-        </listitem>
>-
>-        <listitem><para><filename>/var/db/dhclient.leases</filename></para>
>-          <para>The DHCP client keeps a database of valid leases in this
>-            file, which is written as a log.  &man.dhclient.leases.5;
>-            gives a slightly longer description.</para>
>-        </listitem>
>-      </itemizedlist>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Further Reading</title>
>-
>-      <para>The DHCP protocol is fully described in
>-        <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
>-        An informational resource has also been set up at
>-        <ulink url="http://www.dhcp.org/">dhcp.org</ulink>.</para>
>-    </sect2>
>-
>-    <sect2 id="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
>-	    suite.</para>
>-
>-	  <para>The server portion of the suite is not provided as part of
>-	    FreeBSD, and so you will need to install the
>-	    <filename role="package">net/isc-dhcp3</filename>
>-	    port to provide this service.  See <xref linkend="ports"> for
>-	    more information on using the ports collection.</para>
>-	</sect3>
>-
>-	<sect3>
>-	  <title>DHCP Server Installation</title>
>-	  <indexterm>
>-	    <primary>DHCP</primary>
>-	    <secondary>installation</secondary>
>-	  </indexterm>
>-	  <para>In order to configure your FreeBSD system as a DHCP server,
>-	    you will need to ensure that the &man.bpf.4;
>-	    device is compiled into your kernel.  To do this, add
>-	    <literal>pseudo-device bpf</literal> to your kernel
>-	    configuration file, and rebuild the kernel.  For more
>-	    information about building kernels, see <xref
>-	    linkend="kernelconfig">.</para>
>-
>-	  <para>The <devicename>bpf</devicename> device is already
>-	    part of the <filename>GENERIC</filename> kernel that is
>-	    supplied with FreeBSD, so you do not need to create a custom
>-	    kernel in order to get DHCP working.</para>
>-
>-	    <note>
>-	      <para>Those who are particularly security conscious
>-	        should note that <devicename>bpf</devicename>
>-		is also the device that allows packet sniffers to work
>-		correctly (although such programs still need privileged
>-		access).  <devicename>bpf</devicename>
>-		<emphasis>is</emphasis> required to use DHCP, but if
>-		you are very sensitive about security, you probably
>-		should not include <devicename>bpf</devicename> in your
>-		kernel purely because you expect to use DHCP at some
>-		point in the future.</para>
>-	    </note>
>-
>-	  <para>The next thing that you will need to do is edit the sample
>-	    <filename>dhcpd.conf</filename> which was installed by the
>-	    <filename role="package">net/isc-dhcp3</filename> port.
>-	    By default, this will be
>-	    <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and you
>-	    should copy this to
>-	    <filename>/usr/local/etc/dhcpd.conf</filename> before proceeding
>-	    to make changes.</para>
>-	</sect3>
>-
>-	<sect3>
>-	  <title>Configuring the DHCP Server</title>
>-	  <indexterm>
>-	    <primary>DHCP</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 a hostname is OK here, since the DHCP
>-		server will resolve the hostname itself before returning the
>-		lease information.</para>
>-	    </callout>
>-	  </calloutlist>
>-
>-	  <para>Once you have finished writing your
>-	    <filename>dhcpd.conf</filename>, you can proceed to start the
>-	    server by issuing the following command:</para>
>-
>-	  <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd.sh start</userinput></screen>
>-
>-	  <para>Should you need to make changes to the configuration of your
>-	    server in the future, it is important to note that sending a
>-	    <literal>SIGHUP</literal> signal to
>-	    <application>dhcpd</application> does <emphasis>not</emphasis>
>-	    result in the configuration being reloaded, as it does with most
>-	    daemons.  You will need to send a <literal>SIGTERM</literal>
>-	    signal to stop the process, and then restart it using the command
>-	    above.</para>
>-	</sect3>
>-
>-	<sect3>
>-	  <title>Files</title>
>-	  <indexterm>
>-	    <primary>DHCP</primary>
>-	    <secondary>configuration files</secondary>
>-	  </indexterm>
>-	  <itemizedlist>
>-	    <listitem><para><filename>/usr/local/sbin/dhcpd</filename></para>
>-	      <para><application>dhcpd</application> is statically linked and
>-		resides in <filename>/usr/local/sbin</filename>.  The
>-		dhcpd(8) manual page installed with the
>-		port gives more information about
>-		<application>dhcpd</application>.</para>
>-	    </listitem>
>-
>-	    <listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
>-	      <para><application>dhcpd</application> requires a configuration
>-		file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
>-		will start providing service to clients.  This file needs to
>-		contain all the information that should be provided to clients
>-		that are being serviced, along with information regarding the
>-		operation of the server.  This configuration file is described
>-		by the dhcpd.conf(5) manual page installed
>-		by the port.</para>
>-	    </listitem>
>-
>-	    <listitem><para><filename>/var/db/dhcpd.leases</filename></para>
>-	      <para>The DHCP server keeps a database of leases it has issued
>-		in this file, which is written as a log.  The manual page
>-		dhcpd.leases(5), installed by the port
>-		gives a slightly longer description.</para>
>-	    </listitem>
>-
>-	    <listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
>-	      <para><application>dhcrelay</application> is used in advanced
>-		environments where one DHCP server forwards a request from a
>-		client to another DHCP server on a separate network.  The
>-		dhcrelay(8) manual page provided with the
>-		port contains more detail.</para>
>-	    </listitem>
>-	  </itemizedlist>
>-	</sect3>
>-
>-      </sect2>
>-
>-  </sect1>
>-
>-  <sect1 id="network-dns">
>-    <sect1info>
>-      <authorgroup>
>-        <author>
>-          <firstname>Chern</firstname>
>-          <surname>Lee</surname>
>-          <contrib>Contributed by </contrib>
>-        </author>
>-      </authorgroup>
>-    </sect1info>
>-    <title>DNS</title>
>-
>-    <sect2>
>-      <title>Overview</title>
>-      <indexterm><primary>BIND</primary></indexterm>
>-
>-      <para>FreeBSD utilizes, by default, a version of BIND (Berkeley
>-        Internet Name Domain), which is the most common implementation of the
>-        DNS protocol.  DNS is the protocol through which names are mapped to
>-        IP addresses, and vice versa.  For example, a query for
>-	<hostid>www.FreeBSD.org</hostid>
>-        will receive a reply with the IP address of The FreeBSD Project's
>-        web server, whereas, a query for <hostid>ftp.FreeBSD.org</hostid>
>-	will return the IP
>-	address of the corresponding FTP machine.  Likewise, the opposite can
>-        happen.  A query for an IP address can resolve its hostname.  It is
>-	not necessary to run a name server to perform DNS lookups on a system.
>-      </para>
>-
>-      <indexterm><primary>DNS</primary></indexterm>
>-      <para>DNS is coordinated across the Internet through a somewhat
>-        complex system of authoritative root name servers, and other
>-        smaller-scale name servers who host and cache individual domain
>-        information.
>-      </para>
>-
>-      <para>
>-        This document refers to BIND 8.x, as it is the stable version
>-	used in FreeBSD.  BIND 9.x in FreeBSD can be installed through
>-	the <filename role="package">net/bind9</filename> port.
>-      </para>
>-
>-      <para>
>-        RFC1034 and RFC1035 dictate the DNS protocol.
>-      </para>
>-
>-      <para>
>-        Currently, BIND is maintained by the <ulink
>-        url="http://www.isc.org/">
>-        Internet Software Consortium (www.isc.org)</ulink>
>-      </para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Terminology</title>
>-
>-      <para>To understand this document, some terms related to DNS must be
>-	understood.</para>
>-
>-      <informaltable frame="none">
>-	<tgroup cols="2">
>-	  <thead>
>-	    <row>
>-	      <entry>Term</entry>
>-	      <entry>Definition</entry>
>-	    </row>
>-	  </thead>
>-
>-	  <tbody>
>-	    <row>
>-	      <entry>forward DNS</entry>
>-	      <entry>mapping of hostnames to IP addresses</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>origin</entry>
>-	      <entry>refers to the domain covered for the particular zone
>-		file</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>named, bind, name server</entry>
>-	      <entry>common names for the BIND name server package within
>-		FreeBSD</entry>
>-	    </row>
>-
>-	    <indexterm><primary>resolver</primary></indexterm>
>-	    <row>
>-	      <entry>resolver</entry>
>-	      <entry>a system process through which a
>-		machine queries a name server for zone information</entry>
>-	    </row>
>-
>-	    <indexterm><primary>reverse DNS</primary></indexterm>
>-	    <row>
>-	      <entry>reverse DNS</entry>
>-	      <entry>the opposite of forward DNS, mapping of IP addresses to
>-		hostnames</entry>
>-	    </row>
>-
>-	    <indexterm><primary>root zone</primary></indexterm>
>-	    <row>
>-	      <entry>root zone</entry>
>-
>-	      <entry>literally, a <quote>.</quote>, refers to the
>-		root, or beginning zone.  All zones fall under this, as
>-		do all files in fall under the root directory.  It is
>-		the beginning of the Internet zone hierarchy.</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry>zone</entry>
>-	      <entry>Each individual domain, subdomain, or area dictated by
>-		DNS</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </informaltable>
>-
>-      <indexterm>
>-	<primary>zones</primary>
>-	<secondary>examples</secondary>
>-      </indexterm>
>-
>-      <para>Examples of zones:
>-      </para>
>-      <itemizedlist>
>-        <listitem>
>-          <para>. is the root zone</para>
>-        </listitem>
>-        <listitem>
>-          <para><hostid>org.</hostid> is a zone under the root zone</para>
>-        </listitem>
>-        <listitem>
>-          <para><hostid>example.org</hostid> is a zone under the
>-          org. zone</para>
>-        </listitem>
>-        <listitem>
>-          <para><hostid>foo.example.org.</hostid> is a subdomain, a
>-            zone under the <hostid>example.org.</hostid> zone</para>
>-        </listitem>
>-        <listitem>
>-          <para>
>-            <hostid>1.2.3.in-addr.arpa</hostid> is a zone referencing
>-	    all IP addresses which fall under the 3.2.1.* IP space.
>-          </para>
>-        </listitem>
>-      </itemizedlist>
>-
>-      <para>As one can see, the more specific part of a hostname appears to
>-        its left.  For example, <hostid>example.org.</hostid> is more
>-        specific than <hostid>org.</hostid>, as <hostid>org.</hostid> is
>-        more specific than the root zone.  The layout of each part of
>-        a hostname is much like a filesystem: the <filename>/dev</filename>
>-        directory falls within the root, and so on.</para>
>-
>-
>-    </sect2>
>-
>-    <sect2>
>-      <title>Reasons to Run a Name Server</title>
>-
>-      <para>Name servers usually come in two forms: an authoritative
>-	name server, and a caching name server.</para>
>-
>-      <para>An authoritative name server is needed when:</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>one wants to serve DNS information to the
>-	    world, replying authoritatively to queries.</para>
>-	</listitem>
>-	<listitem>
>-	  <para>a domain, such as <hostid>example.org</hostid>, is
>-	    registered and IP addresses need to be assigned to hostnames
>-	    under it.</para>
>-	</listitem>
>-	<listitem>
>-	  <para>an IP address block requires reverse DNS entries (IP to
>-	    hostname).</para>
>-	</listitem>
>-	<listitem>
>-	  <para>a backup name server, called a slave, must reply to queries
>-	    when the primary is down or inaccessible.</para>
>-	  </listitem>
>-      </itemizedlist>
>-
>-      <para>A caching name server is needed when:</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>a local DNS server may cache and respond more quickly
>-	    than querying an outside name server.</para>
>-	</listitem>
>-	<listitem>
>-	  <para>a reduction in overall network traffic is desired (DNS
>-	    traffic has been measured to account for 5% or more of total
>-	    Internet traffic).</para>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <para>When one queries for <hostid>www.FreeBSD.org</hostid>, the
>-	resolver usually queries the uplink ISP's name server, and retrieves
>-	the reply.  With a local, caching DNS server, the query only has to
>-	be made once to the outside world by the caching DNS server.  Every
>-	additional query will not have to look to the outside of the local
>-	network, since the information is cached locally.</para>
>-
>-    </sect2>
>-
>-    <sect2>
>-      <title>How It Works</title>
>-      <para>In FreeBSD, the BIND daemon is called
>-	<application>named</application> for obvious reasons.</para>
>-
>-      <informaltable frame="none">
>-	<tgroup cols="2">
>-	  <thead>
>-	    <row>
>-	      <entry>File</entry>
>-	      <entry>Description</entry>
>-	    </row>
>-	  </thead>
>-
>-	  <tbody>
>-	    <row>
>-	      <entry><application>named</application></entry>
>-	      <entry>the BIND daemon</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><command>ndc</command></entry>
>-	      <entry>name daemon control program</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>/etc/namedb</filename></entry>
>-	      <entry>directory where BIND zone information resides</entry>
>-	    </row>
>-
>-	    <row>
>-	      <entry><filename>/etc/namedb/named.conf</filename></entry>
>-	      <entry>daemon configuration file</entry>
>-	    </row>
>-	  </tbody>
>-	</tgroup>
>-      </informaltable>
>-
>-      <para>
>-        Zone files are usually contained within the
>-        <filename>/etc/namedb</filename>
>-        directory, and contain the DNS zone information
>-	served by the name server.
>-      </para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Starting BIND</title>
>-      <indexterm>
>-        <primary>BIND</primary>
>-	<secondary>starting</secondary>
>-      </indexterm>
>-      <para>
>-        Since BIND is installed by default, configuring it all is
>-        relatively simple.
>-      </para>
>-      <para>
>-        To ensure the named daemon is started at boot, put the following
>-         modifications in <filename>/etc/rc.conf</filename>:
>-      </para>
>-      <programlisting>named_enable="YES"</programlisting>
>-      <para>To start the daemon manually (after configuring it)</para>
>-      <screen>&prompt.root; <userinput>ndc start</userinput></screen>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Configuration Files</title>
>-      <indexterm>
>-        <primary>BIND</primary>
>-	<secondary>configuration files</secondary>
>-      </indexterm>
>-      <sect3>
>-        <title>Using <command>make-localhost</command></title>
>-        <para>Be sure to:
>-        </para>
>-        <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
>-&prompt.root; <userinput>sh make-localhost</userinput></screen>
>-        <para>to properly create the local reverse DNS zone file in
>-          <filename>/etc/namedb/localhost.rev</filename>.
>-        </para>
>-      </sect3>
>-
>-      <sect3>
>-        <title><filename>/etc/namedb/named.conf</filename></title>
>-
>-        <programlisting>// &dollar;FreeBSD$
>-//
>-// Refer to the named(8) manual page for details.  If you are ever going
>-// to setup a primary server, make sure you've understood the hairy
>-// details of how DNS is working.  Even with simple mistakes, you can
>-// break connectivity for affected parties, or cause huge amount of
>-// useless Internet traffic.
>-
>-options {
>-        directory "/etc/namedb";
>-
>-// In addition to the "forwarders" clause, you can force your name
>-// server to never initiate queries of its own, but always ask its
>-// forwarders only, by enabling the following line:
>-//
>-//      forward only;
>-
>-// If you've got a DNS server around at your upstream provider, enter
>-// its IP address here, and enable the line below.  This will make you
>-// benefit from its cache, thus reduce overall DNS traffic in the
>-Internet.
>-/*
>-        forwarders {
>-                127.0.0.1;
>-        };
>-*/</programlisting>
>-
>-        <para>
>-	  Just as the comment says, to benefit from an uplink's cache,
>-          <literal>forwarders</literal> can be enabled here.  Under normal
>-          circumstances, a name server will recursively query the Internet
>-          looking at certain name servers until it finds the answer it is
>-          looking for.  Having this enabled will have it query the uplink's
>-          name server (or name server provided) first, taking advantage of
>-          its cache.  If the uplink name server in question is a heavily
>-          trafficked, fast name server, enabling this may be worthwhile.
>-        </para>
>-
>-	<warning><para><hostid role="ipaddr">127.0.0.1</hostid>
>-            will <emphasis>not</emphasis> work here.
>-            Change this IP address to a name server at your uplink.</para>
>-        </warning>
>-
>-        <programlisting>        /*
>-         * If there is a firewall between you and name servers you want
>-         * to talk to, you might need to uncomment the query-source
>-         * directive below.  Previous versions of BIND always asked
>-         * questions using port 53, but BIND 8.1 uses an unprivileged
>-         * port by default.
>-         */
>-        // query-source address * port 53;
>-
>-        /*
>-         * If running in a sandbox, you may have to specify a different
>-         * location for the dumpfile.
>-         */
>-        // dump-file "s/named_dump.db";
>-};
>-
>-// Note: the following will be supported in a future release.
>-/*
>-host { any; } {
>-        topology {
>-                127.0.0.0/8;
>-        };
>-};
>-*/
>-
>-// Setting up secondaries is way easier and the rough picture for this
>-// is explained below.
>-//
>-// If you enable a local name server, don't forget to enter 127.0.0.1
>-// into your /etc/resolv.conf so this server will be queried first.
>-// Also, make sure to enable it in /etc/rc.conf.
>-
>-zone "." {
>-        type hint;
>-        file "named.root";
>-};
>-
>-zone "0.0.127.IN-ADDR.ARPA" {
>-        type master;
>-        file "localhost.rev";
>-};
>-
>-zone
>-"0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
>-        type master;
>-        file "localhost.rev";
>-};
>-
>-// NB: Do not use the IP addresses below, they are faked, and only
>-// serve demonstration/documentation purposes!
>-//
>-// Example secondary config entries.  It can be convenient to become
>-// a secondary at least for the zone where your own domain is in.  Ask
>-// your network administrator for the IP address of the responsible
>-// primary.
>-//
>-// Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
>-// (This is the first bytes of the respective IP address, in reverse
>-// order, with ".IN-ADDR.ARPA" appended.)
>-//
>-// Before starting to setup a primary zone, better make sure you fully
>-// understand how DNS and BIND works, however.  There are sometimes
>-// unobvious pitfalls.  Setting up a secondary is comparably simpler.
>-//
>-// NB: Don't blindly enable the examples below. :-)  Use actual names
>-// and addresses instead.
>-//
>-// NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
>-// The directory containing the secondary zones must be write accessible
>-// to bind.  The following sequence is suggested:
>-//
>-//      mkdir /etc/namedb/s
>-//      chown bind:bind /etc/namedb/s
>-//      chmod 750 /etc/namedb/s</programlisting>
>-
>-	<para>For more information on running BIND in a sandbox, see
>-	  <link linkend="network-named-sandbox">Running named in a sandbox</link>.
>-	</para>
>-
>-	<programlisting>/*
>-zone "example.com" {
>-        type slave;
>-        file "s/example.com.bak";
>-        masters {
>-                192.168.1.1;
>-        };
>-};
>-
>-zone "0.168.192.in-addr.arpa" {
>-        type slave;
>-        file "s/0.168.192.in-addr.arpa.bak";
>-        masters {
>-                192.168.1.1;
>-        };
>-};
>-*/</programlisting>
>-        <para>In <filename>named.conf</filename>, these are examples of slave
>-	  entries for a forward and reverse zone.</para>
>-
>-        <para>For each new zone served, a new zone entry must be added to
>-	  <filename>named.conf</filename></para>
>-
>-        <para>For example, the simplest zone entry for
>-	  <hostid role="domainname">example.org</hostid> can look like:</para>
>-
>-        <programlisting>zone "example.org" {
>-	type master;
>-	file "example.org";
>-};</programlisting>
>-
>-	<para>The zone is a master, as indicated by the <option>type</option>
>-	  statement, holding its zone information in
>-	  <filename>/etc/namedb/example.org</filename> indicated by
>-	  the <option>file</option> statement.</para>
>-
>-        <programlisting>zone "example.org" {
>-	type slave;
>-	file "example.org";
>-};</programlisting>
>-
>-        <para>In the slave case, the zone information is transferred from
>-	  the master name server for the particular zone, and saved in the
>-	  file specified.  If and when the master server dies or is
>-	  unreachable, the slave name server will have the transferred
>-	  zone information and will be able to serve it.</para>
>-      </sect3>
>-
>-      <sect3>
>-        <title>Zone Files</title>
>-        <para>
>-          An example master zone file for <hostid>example.org</hostid>
>-	  (existing within <filename>/etc/namedb/example.org</filename>)
>-	  is as follows:
>-        </para>
>-
>-        <programlisting>$TTL 3600
>-
>-example.org. IN SOA ns1.example.org. admin.example.org. (
>-                        5               ; Serial
>-                        10800           ; Refresh
>-                        3600            ; Retry
>-                        604800          ; Expire
>-                        86400 )         ; Minimum TTL
>-
>-; DNS Servers
>-@       IN NS           ns1.example.org.
>-@       IN NS           ns2.example.org.
>-
>-; Machine Names
>-localhost       IN A    127.0.0.1
>-ns1             IN A    3.2.1.2
>-ns2             IN A    3.2.1.3
>-mail            IN A    3.2.1.10
>-@               IN A    3.2.1.30
>-
>-; Aliases
>-www             IN CNAME        @
>-
>-; MX Record
>-@               IN MX   10      mail.example.org.</programlisting>
>-
>-        <para>
>-          Note that every hostname ending in a <quote>.</quote> is an
>-          exact hostname, whereas everything without a trailing
>-          <quote>.</quote> is referenced to the origin.  For example,
>-          <literal>www</literal> is translated into <literal>www +
>-	    origin</literal>.  In our fictitious zone file, our origin
>-          is <hostid>example.org.</hostid>, so
>-          <literal>www</literal> would translate to
>-          <hostid>www.example.org.</hostid>
>-        </para>
>-
>-        <para>
>-          The format of a zone file follows:
>-        </para>
>-        <programlisting>recordname      IN recordtype   value</programlisting>
>-
>-	<indexterm>
>-	  <primary>DNS</primary>
>-	  <secondary>records</secondary>
>-	</indexterm>
>-        <para>
>-          The most commonly used DNS records:
>-        </para>
>-
>-	<variablelist>
>-	  <varlistentry>
>-	    <term>SOA</term>
>-
>-	    <listitem><para>start of zone authority</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term>NS</term>
>-
>-	    <listitem><para>an authoritative name server</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term>A</term>
>-
>-	    <listitem><para>A host address</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term>CNAME</term>
>-
>-	    <listitem><para>the canonical name for an alias</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term>MX</term>
>-
>-	    <listitem><para>mail exchanger</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term>PTR</term>
>-
>-	    <listitem><para>a domain name pointer (used in reverse DNS)
>-	      </para></listitem>
>-	  </varlistentry>
>-	</variablelist>
>-
>-        <programlisting>
>-example.org. IN SOA ns1.example.org. admin.example.org. (
>-                        5               ; Serial
>-                        10800           ; Refresh after 3 hours
>-                        3600            ; Retry after 1 hour
>-                        604800          ; Expire after 1 week
>-                        86400 )         ; Minimum TTL of 1 day</programlisting>
>-
>-
>-
>-	<variablelist>
>-	  <varlistentry>
>-	    <term><hostid>example.org.</hostid></term>
>-
>-	    <listitem><para>the domain name, also the origin for this
>-		zone file.</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term><hostid>ns1.example.org.</hostid></term>
>-
>-	    <listitem><para>the primary/authoritative name server for this
>-		zone</para></listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term><literal>admin.example.org.</literal></term>
>-
>-	    <listitem><para>the responsible person for this zone,
>-		email address with @
>-          replaced.  (<email>admin@example.org</email> becomes
>-		<literal>admin.example.org</literal>)</para>
>-	    </listitem>
>-	  </varlistentry>
>-
>-	  <varlistentry>
>-	    <term><literal>5</literal></term>
>-
>-	      <listitem><para>the serial number of the file.  this
>-		  must be incremented each time the zone file is modified.
>-		  Nowadays, many admins prefer a
>-		  <literal>yyyymmddrr</literal> format for the serial
>-		  number.  2001041002 would mean last modified 04/10/2001,
>-		  the latter 02 being the second time the zone file has
>-		  been modified this day.  The serial number is important
>-		  as it alerts slave name servers for a zone when it is
>-		  updated.</para>
>-	      </listitem>
>-	  </varlistentry>
>-	</variablelist>
>-
>-        <programlisting>
>-@       IN NS           ns1.example.org.</programlisting>
>-
>-        <para>
>-          This is an <varname>NS</varname> entry.  Every name server that is going to reply
>-          authoritatively for the zone must have one of these entries.
>-	  The <literal>@</literal> as seen here could have been
>-	  <hostid role="domainname">example.org.</hostid>
>-	  The <literal>@</literal> translates to the origin.
>-        </para>
>-
>-        <programlisting>
>-localhost       IN A    127.0.0.1
>-ns1             IN A    3.2.1.2
>-ns2             IN A    3.2.1.3
>-mail            IN A    3.2.1.10
>-@               IN A    3.2.1.30</programlisting>
>-
>-        <para>
>-          The A record indicates machine names.  As seen above,
>-          <hostid>ns1.example.org</hostid> would resolve to
>-          <hostid role="ipaddr">3.2.1.2</hostid>.  Again,
>-          the origin symbol, <literal>@</literal>, is
>-          used here, thus meaning <hostid>example.org</hostid>
>-          would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
>-        </para>
>-
>-        <programlisting>
>-www             IN CNAME        @</programlisting>
>-
>-        <para>
>-          The canonical name record is usually used for giving aliases
>-          to a machine.  In the example, <hostid>www</hostid> is
>-          aliased to the machine addressed to the origin, or
>-          <hostid>example.org</hostid>
>-          (<hostid role="ipaddr">3.2.1.30</hostid>).
>-          <varname>CNAME</varname>s can be used to provide alias
>-          hostnames, or round robin one hostname among multiple
>-          machines.
>-        </para>
>-
>-        <programlisting>
>-@               IN MX   10      mail.example.org.</programlisting>
>-
>-        <para>
>-          The <varname>MX</varname> record indicates which mail
>-          servers are responsible for handling incoming mail for the
>-          zone.  <hostid role="fqdn">mail.example.org</hostid> is the
>-          hostname of the mail server, and 10 being the priority of
>-          that mail server.
>-        </para>
>-
>-        <para>
>-          One can have several mail servers, with priorities of 3, 2,
>-          1.  A mail server attempting to deliver to <hostid
>-          role="domainname">example.org</hostid> would first try the
>-          highest priority MX, then the second highest, etc, until the
>-          mail can be properly delivered.
>-        </para>
>-
>-        <para>
>-          For in-addr.arpa zone files (reverse DNS), the same format is
>-          used, except with <varname>PTR</varname> entries instead of
>-	  <varname>A</varname> or <varname>CNAME</varname>.
>-        </para>
>-
>-        <programlisting>$TTL 3600
>-
>-1.2.3.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
>-                        5               ; Serial
>-                        10800           ; Refresh
>-                        3600            ; Retry
>-                        604800          ; Expire
>-                        3600 )          ; Minimum
>-
>-@       IN NS   ns1.example.org.
>-@       IN NS   ns2.example.org.
>-
>-2       IN PTR  ns1.example.org.
>-3       IN PTR  ns2.example.org.
>-10      IN PTR  mail.example.org.
>-30      IN PTR  example.org.</programlisting>
>-        <para>
>-         This file gives the proper IP address to hostname mappings of our above
>-         fictitious domain.
>-        </para>
>-      </sect3>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Caching Name Server</title>
>-      <indexterm>
>-        <primary>BIND</primary>
>-        <secondary>caching name server</secondary>
>-      </indexterm>
>-      <para>
>-        A caching name server is a name server that is not
>-        authoritative for any zones.  It simply asks queries of its own,
>-        and remembers them for later use.  To set one up, just configure
>-        the name server as usual, omitting any inclusions of zones.
>-      </para>
>-    </sect2>
>-
>-    <sect2 id="network-named-sandbox">
>-      <title>Running <application>named</application> in a Sandbox</title>
>-      <indexterm>
>-        <primary>BIND</primary>
>-        <secondary>running in a sandbox</secondary>
>-      </indexterm>
>-
>-      <indexterm>
>-        <primary><command>chroot</command></primary>
>-      </indexterm>
>-      <para>For added security you may want to run &man.named.8; as an
>-	unprivileged user, and configure it to &man.chroot.8; into a
>-	sandbox directory.  This makes everything outside of the sandbox
>-	inaccessible to the <application>named</application> daemon.  Should
>-	<application>named</application> be compromised, this will help to
>-	reduce the damage that can be caused.  By default, FreeBSD has a user
>-	and a group called <groupname>bind</groupname>, intended for this
>-	use.</para>
>-
>-      <note><para>Various people would recommend that instead of configuring
>-	<application>named</application> to <command>chroot</command>, you
>-	should run <application>named</application> inside a &man.jail.8;.
>-	This section does not attempt to cover this situation.</para>
>-      </note>
>-
>-      <para>Since <application>named</application> will not be able to
>-	access anything outside of the sandbox (such as shared
>-	libraries, log sockets, and so on), there are a number of steps
>-	that need to be followed in order to allow
>-	<application>named</application> to function correctly.  In the
>-	following checklist, it is assumed that the path to the sandbox
>-	is <filename>/etc/namedb</filename> and that you have made no
>-	prior modifications to the contents of this directory.  Perform
>-	the following steps as <username>root</username>.</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>Create all directories that <application>named</application>
>-	    expects to see:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
>-&prompt.root; <userinput>mkdir -p bin dev etc var/tmp var/run master slave</userinput>
>-&prompt.root; <userinput>chown bind:bind slave var/*</userinput><co id="chown-slave"></screen>
>-
>-
>-
>-	  <calloutlist>
>-	    <callout arearefs="chown-slave">
>-	      <para><application>named</application> only needs write access to
>-		these directories, so that is all we give it.</para>
>-	    </callout>
>-	  </calloutlist>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Rearrange and create basic zone and configuration files:</para>
>-	  <screen>&prompt.root; <userinput>cp /etc/localtime etc</userinput><co id="localtime">
>-&prompt.root; <userinput>mv named.conf etc && ln -sf etc/named.conf</userinput>
>-&prompt.root; <userinput>mv named.root master</userinput>
>-
>-&prompt.root; <userinput>sh make-localhost && mv localhost.rev localhost-v6.rev master</userinput>
>-&prompt.root; <userinput>cat > master/named.localhost
>-$ORIGIN localhost.
>-$TTL 6h
>-@	IN	SOA	localhost. postmaster.localhost. (
>-			1	; serial
>-			3600	; refresh
>-			1800	; retry
>-			604800	; expiration
>-			3600 )	; minimum
>-	IN	NS	localhost.
>-	IN	A		127.0.0.1
>-^D</userinput></screen>
>-
>-	  <calloutlist>
>-	    <callout arearefs="localtime">
>-	      <para>This allows <application>named</application> to log the
>-		correct time to &man.syslogd.8;</para>
>-	    </callout>
>-	  </calloutlist>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Build a statically linked copy of
>-	    <application>named-xfer</application>, and copy it into the sandbox:</para>
>-
>-	      <screen>&prompt.root; <userinput>cd /usr/src/lib/libisc</userinput>
>-&prompt.root; <userinput>make cleandir && make cleandir && make depend && make all</userinput>
>-&prompt.root; <userinput>cd /usr/src/lib/libbind</userinput>
>-&prompt.root; <userinput>make cleandir && make cleandir && make depend && make all</userinput>
>-&prompt.root; <userinput>cd /usr/src/libexec/named-xfer</userinput>
>-&prompt.root; <userinput>make cleandir && make cleandir && make depend && make NOSHARED=yes all</userinput>
>-&prompt.root; <userinput>cp named-xfer /etc/namedb/bin && chmod 555 /etc/namedb/bin/named-xfer</userinput><co id="clean-cruft"></screen>
>-
>-	  <para>After your statically linked
>-	    <command>named-xfer</command> is installed some cleaning up
>-	    is required, to avoid leaving stale copies of libraries or
>-	    programs in your source tree:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /usr/src/lib/libisc</userinput>
>-&prompt.root; <userinput>make cleandir</userinput>
>-&prompt.root; <userinput>cd /usr/src/lib/libbind</userinput>
>-&prompt.root; <userinput>make cleandir</userinput>
>-&prompt.root; <userinput>cd /usr/src/libexec/named-xfer</userinput>
>-&prompt.root; <userinput>make cleandir</userinput></screen>
>-
>-         <calloutlist>
>-           <callout arearefs="clean-cruft">
>-             <para>This step has been reported to fail occasionally.  If this
>-               happens to you, then issue the command:</para>
>-
>-             <screen>&prompt.root; <userinput>cd /usr/src && make cleandir && make cleandir</userinput></screen>
>-
>-	     <para>and delete your <filename>/usr/obj</filename> tree:</para>
>-
>-	     <screen>&prompt.root; <userinput>rm -fr /usr/obj && mkdir /usr/obj</userinput></screen>
>-
>-             <para>This will clean out any <quote>cruft</quote> from your
>-               source tree, and retrying the steps above should then work.</para>
>-           </callout>
>-         </calloutlist>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Make a <devicename>dev/null</devicename> that
>-	    <application>named</application> can see and write to:</para>
>-
>-	  <screen>&prompt.root; <userinput>cd /etc/namedb/dev && mknod null c 2 2</userinput>
>-&prompt.root; <userinput>chmod 666 null</userinput></screen>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Symlink <filename> /var/run/ndc</filename> to
>-	    <filename>/etc/namedb/var/run/ndc</filename>:</para>
>-
>-	  <screen>&prompt.root; <userinput>ln -sf /etc/namedb/var/run/ndc /var/run/ndc</userinput></screen>
>-
>-	  <note>
>-	    <para>This simply avoids having to specify the
>-	      <option>-c</option> option to &man.ndc.8; every time you
>-	      run it.  Since the contents of /var/run are deleted on boot,
>-	      if this is something that you find useful you
>-	      may wish to add this command to root's crontab, making use
>-	      of the <option>@reboot</option> option.  See
>-	      &man.crontab.5; for more information regarding
>-	      this.</para>
>-	  </note>
>-
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Configure &man.syslogd.8; to create an extra
>-	    <devicename>log</devicename> socket that
>-	    <application>named</application> can write to.  To do this,
>-	    add <literal>-l /etc/namedb/dev/log</literal> to the
>-	    <varname>syslogd_flags</varname> variable in
>-	    <filename>/etc/rc.conf</filename>.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Arrange to have <application>named</application> start
>-	    and <command>chroot</command> itself to the sandbox by
>-	    adding the following to
>-	    <filename>/etc/rc.conf</filename>:</para>
>-
>-	  <programlisting>named_enable="YES"
>-named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"</programlisting>
>-
>-	  <note>
>-	    <para>Note that the configuration file
>-	    <replaceable>/etc/named.conf</replaceable> is denoted by a full
>-	    pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
>-	    the line above, the file referred to is actually
>-	    <filename>/etc/namedb/etc/named.conf</filename>.</para>
>-	  </note>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <para>The next step is to edit
>-	<filename>/etc/namedb/etc/named.conf</filename> so that
>-	<application>named</application> knows which zones to load and
>-	where to find them on the disk.  There follows a commented
>-	example (anything not specifically commented here is no
>-	different from the setup for a DNS server not running in a
>-	sandbox):</para>
>-
>-	<programlisting>options {
>-        directory "/";<co id="directory">
>-        named-xfer "/bin/named-xfer";<co id="named-xfer">
>-        version "";		// Don't reveal BIND version
>-        query-source address * port 53;
>-};
>-// ndc control socket
>-controls {
>-        unix "/var/run/ndc" perm 0600 owner 0 group 0;
>-};
>-// Zones follow:
>-zone "localhost" IN {
>-        type master;
>-        file "master/named.localhost";<co id="master">
>-        allow-transfer { localhost; };
>-        notify no;
>-};
>-zone "0.0.127.in-addr.arpa" IN {
>-        type master;
>-        file "master/localhost.rev";
>-        allow-transfer { localhost; };
>-        notify no;
>-};
>-zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.int" {
>-	type master;
>-	file "master/localhost-v6.rev";
>-	allow-transfer { localhost; };
>-	notify no;
>-};
>-zone "." IN {
>-        type hint;
>-        file "master/named.root";
>-};
>-zone "private.example.net" in {
>-        type master;
>-        file "master/private.example.net.db";
>-	allow-transfer { 192.168.10.0/24; };
>-};
>-zone "10.168.192.in-addr.arpa" in {
>-        type slave;
>-        masters { 192.168.10.2; };
>-        file "slave/192.168.10.db";<co id="slave">
>-};</programlisting>
>-
>-      <calloutlist>
>-	<callout arearefs="directory">
>-	  <para>The
>-	    <literal>directory</literal> statement is specified as
>-	    <filename>/</filename>, since all files that
>-	    <application>named</application> needs are within this
>-	    directory (recall that this is equivalent to a
>-	    <quote>normal</quote> user's
>-	    <filename>/etc/namedb</filename>.</para>
>-	</callout>
>-
>-	<callout arearefs="named-xfer">
>-	  <para>Specifies the full path
>-	    to the <command>named-xfer</command> binary (from
>-	    <application>named</application>'s frame of reference).  This
>-	    is necessary since <application>named</application> is
>-	    compiled to look for <command>named-xfer</command> in
>-	    <filename>/usr/libexec</filename> by default.</para>
>-	</callout>
>-	<callout arearefs="master"><para>Specifies the filename (relative
>-	  to the <literal>directory</literal> statement above) where
>-	  <application>named</application> can find the zonefile for this
>-	  zone.</para>
>-	</callout>
>-	<callout arearefs="slave"><para>Specifies the filename
>-	    (relative to the <literal>directory</literal> statement above)
>-	    where <application>named</application> should write a copy of
>-	    the zonefile for this zone after successfully transferring it
>-	    from the master server.  This is why we needed to change the
>-	    ownership of the directory <filename>slave</filename> to
>-	    <groupname>bind</groupname> in the setup stages above.</para>
>-	</callout>
>-      </calloutlist>
>-
>-      <para>After completing the steps above, either reboot your
>-	server or restart &man.syslogd.8; and start &man.named.8;, making
>-	sure to use the new options specified in
>-	<varname>syslogd_flags</varname> and
>-	<varname>named_flags</varname>.  You should now be running a
>-	sandboxed copy of <application>named</application>!</para>
>-
>-    </sect2>
>-
>-    <sect2>
>-      <title>Security</title>
>-
>-      <para>Although BIND is the most common implementation of DNS,
>-        there is always the issue of security.  Possible and
>-        exploitable security holes are sometimes found.
>-      </para>
>-
>-      <para>
>-        It is a good idea to subscribe to <ulink
>-        url="http://www.cert.org/">CERT</ulink> and
>-        <ulink url="../handbook/eresources.html#ERESOURCES-MAIL">freebsd-security-notifications</ulink>
>-        to stay up to date with the current Internet and FreeBSD security
>-        issues.
>-      </para>
>-
>-      <tip><para>If a problem arises, keeping sources up to date and having a
>-        fresh build of named would not hurt.</para></tip>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Further Reading</title>
>-      <para>
>-        BIND/named manual pages: &man.ndc.8; &man.named.8; &man.named.conf.5;
>-      </para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para><ulink
>-	      url="http://www.isc.org/products/BIND/">Official ISC Bind
>-	      Page</ulink></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><ulink
>-	  url="http://www.nominum.com/getOpenSourceResource.php?id=6">
>-	  BIND FAQ</ulink></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><ulink url="http://www.oreilly.com/catalog/dns4/">O'Reilly
>-         DNS and BIND 4th Edition</ulink></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><ulink
>-	      url="ftp://ftp.isi.edu/in-notes/rfc1034.txt">RFC1034
>-	      - Domain Names - Concepts and Facilities</ulink></para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para><ulink
>-	      url="ftp://ftp.isi.edu/in-notes/rfc1035.txt">RFC1035
>-	      - Domain Names - Implementation and Specification</ulink></para>
>-	</listitem>
>-      </itemizedlist>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="network-ntp">
>-    <sect1info>
>-      <authorgroup>
>-	<author>
>-	  <firstname>Tom</firstname>
>-	  <surname>Hukins</surname>
>-	  <contrib>Contributed by </contrib>
>-	</author>
>-      </authorgroup>
>-    </sect1info>
>-    <title>NTP</title>
>-
>-    <indexterm><primary>NTP</primary></indexterm>
>-
>-    <sect2>
>-      <title>Overview</title>
>-
>-      <para>Over time, a computer's clock is prone to drift.  As time
>-	passes, the computer's clock becomes less accurate.  NTP
>-	(Network Time Protocol) is one way to ensure your clock is
>-	right.</para>
>-
>-      <para>Many Internet services rely on, or greatly benefit from,
>-	computers' clocks being accurate.  For example, a Web server
>-	may receive requests to send a file if it has modified since a
>-	certain time.  Services such as &man.cron.8; run commands at a
>-	given time.  If the clock is inaccurate, these commands may
>-	not run when expected.</para>
>-
>-      <indexterm>
>-	<primary>NTP</primary>
>-	<secondary>ntpd</secondary>
>-      </indexterm>
>-      <para>FreeBSD ships with the &man.ntpd.8; NTP server which can
>-	be used to query other NTP servers to set the clock on your
>-	machine or provide time services to others.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Choosing Appropriate NTP Servers</title>
>-
>-      <indexterm>
>-	<primary>NTP</primary>
>-	<secondary>choosing servers</secondary>
>-      </indexterm>
>-
>-      <para>In order to synchronize your clock, you will need to find
>-	one or more NTP servers to use.  Your network administrator or
>-	ISP may have setup an NTP server for this purpose&mdash;check
>-	their documentation to see if this is the case.  There is a
>-	<ulink
>-	url="http://www.eecis.udel.edu/~mills/ntp/servers.html">list of
>-	publicly accessible NTP servers</ulink> which you can use to
>-	find an NTP server near to you.  Make sure you are aware of
>-	the policy for any servers you choose, and ask for permission
>-	if required.</para>
>-
>-      <para>Choosing several unconnected NTP servers is a good idea in
>-	case one of the servers you are using becomes unreachable or
>-	its clock is unreliable.  &man.ntpd.8; uses the responses it
>-	receives from other servers intelligently&mdash;it will favor
>-	unreliable servers less than reliable ones.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Configuring Your Machine</title>
>-
>-      <indexterm>
>-	<primary>NTP</primary>
>-	<secondary>configuration</secondary>
>-      </indexterm>
>-
>-      <sect3>
>-	<title>Basic Configuration</title>
>-	<indexterm><primary>ntpdate</primary></indexterm>
>-
>-	<para>If you only wish to synchronize your clock when the
>-	  machine boots up, you can use &man.ntpdate.8;.  This may be
>-	  appropriate for some desktop machines which are frequently
>-	  rebooted and only require infrequent synchronization, but
>-	  most machines should run &man.ntpd.8;.</para>
>-
>-	<para>Using &man.ntpdate.8; at boot time is also a good idea
>-	  for machines that run &man.ntpd.8;.  &man.ntpd.8; changes the
>-	  clock gradually, whereas &man.ntpdate.8; sets the clock, no
>-	  matter how great the difference between a machine's current
>-	  clock setting and the correct time.</para>
>-
>-	<para>To enable &man.ntpdate.8; at boot time, add
>-	  <programlisting>ntpdate_enable="YES"</programlisting> to
>-	  <filename>/etc/rc.conf</filename>.  You will also need to
>-	  specify all servers you wish to synchronize with and any
>-	  flags to be passed to &man.ntpdate.8; in
>-	  <varname>ntpdate_flags</varname>.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<indexterm>
>-	  <primary>NTP</primary>
>-	  <secondary>ntp.conf</secondary>
>-	</indexterm>
>-
>-	<title>General Configuration</title>
>-
>-	<para>NTP is configured by the
>-	  <filename>/etc/ntp.conf</filename> file in the format
>-	  described in &man.ntp.conf.5;.  Here is a simple
>-	  example:</para>
>-
>-	<programlisting>server ntplocal.example.com prefer
>-server timeserver.example.org
>-server ntp2a.example.net
>-
>-driftfile /var/db/ntp.drift</programlisting>
>-
>-	<para>The <literal>server</literal> option specifies which
>-	  servers are to be used, with one server listed on each line.
>-	  If a server is specified with the <literal>prefer</literal>
>-	  argument, as with <hostid
>-	  role="fqdn">ntplocal.example.com</hostid>, that server is
>-	  preferred over other servers.  A response from a preferred
>-	  server will be discarded if it differs significantly from
>-	  other servers' responses, otherwise it will be used without
>-	  any consideration to other responses.  The
>-	  <literal>prefer</literal> argument is normally used for NTP
>-	  servers that are known to be highly accurate, such as those
>-	  with special time monitoring hardware.</para>
>-
>-	<para>The <literal>driftfile</literal> option specifies which
>-	  file is used to store the system clock's frequency offset.
>-	  &man.ntpd.8; uses this to automatically compensate for the
>-	  clock's natural drift, allowing it to maintain a reasonably
>-	  correct setting even if it is cut off from all external time
>-	  sources for a period of time.</para>
>-
>-	<para>The <literal>driftfile</literal> option specifies which
>-	  file is used to store information about previous responses
>-	  from the NTP servers you are using.  This file contains
>-	  internal information for NTP.  It should not be modified by
>-	  any other process.</para>
>-      </sect3>
>-
>-      <sect3>
>-	<title>Controlling Access to Your Server</title>
>-
>-	<para>By default, your NTP server will be accessible to all
>-	  hosts on the Internet.  The <literal>restrict</literal>
>-	  option in &man.ntp.conf.5; allows you to control which
>-	  machines can access your server.</para>
>-
>-	<para>If you want to deny all machines from accessing your NTP
>-	  server, add the 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 notrust 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 <programlisting>xntpd_enable="YES"</programlisting> to
>-	<filename>/etc/rc.conf</filename>.  If you wish to pass
>-	additional flags to &man.ntpd.8; edit the
>-	<varname>xntpd_flags</varname> parameter in
>-	<filename>/etc/rc.conf</filename>.</para>
>-
>-      <para>To start the server without rebooting your machine, run
>-	<command>ntpd</command> being sure to specify any additional
>-	parameters from <varname>xntpd_flags</varname> in
>-	<filename>/etc/rc.conf</filename>.  For example:</para>
>-      <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Using &man.ntpd.8; with a Temporary Internet
>-	Connection</title>
>-
>-      <para><command>ntpd</command> does not need a permanent
>-	connection to the Internet to function properly.  However, if
>-	you have a temporary connection that is configured to dial out
>-	on demand, it is a good idea to prevent NTP traffic from
>-	triggering a dial out or keeping the connection alive.  If you
>-	are using user PPP, you can use <literal>filter</literal>
>-	directives in <filename>/etc/ppp/ppp.conf</filename>.  For
>-	example:</para>
>-
>-      <programlisting> set filter dial 0 deny udp src eq 123
>- # Prevent NTP traffic from initiating dial out
>- set filter dial 1 permit 0 0
>- set filter alive 0 deny udp src eq 123
>- # Prevent incoming NTP traffic from keeping the connection open
>- set filter alive 1 deny udp dst eq 123
>- # Prevent outgoing NTP traffic from keeping the connection open
>- set filter alive 2 permit 0/0 0/0</programlisting>
>-
>-      <para>For more details see the <literal>PACKET
>-	FILTERING</literal> section in &man.ppp.8; and the examples in
>-	<filename>/usr/share/examples/ppp/</filename>.</para>
>-
>-      <note>
>-	<para>Some Internet access providers block low-numbered ports,
>-	  preventing NTP from functioning since replies never
>-	  reach your machine.</para>
>-      </note>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Further Information</title>
>-
>-      <para>Documentation for the NTP server can be found in
>-	<filename>/usr/share/doc/ntp/</filename> in HTML
>-	format.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="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.  natd does this by changing
>-        the source IP address and port such that when data is received back,
>-        it is able to determine the original location of the data and forward
>-        it back to its original requester.</para>
>-      <indexterm><primary>Internet connection sharing</primary></indexterm>
>-      <indexterm><primary>IP masquerading</primary></indexterm>
>-      <para>The most common use of NAT is to perform what is commonly known as
>-        Internet Connection Sharing.</para>
>-    </sect2>
>-
>-    <sect2 id="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--one for connecting
>-        to the Internet router, the other connecting to a LAN.  All the
>-        machines on the LAN are connected through a hub or switch.</para>
>-
>-      <mediaobject>
>-        <imageobject>
>-          <imagedata fileref="advanced-networking/natd">
>-        </imageobject>
>-
>-	<textobject>
>-	  <literallayout class="monospaced">  _______       __________       ________
>- |       |     |          |     |        |
>- |  Hub  |-----| Client B |-----| Router |----- Internet
>- |_______|     |__________|     |________|
>-     |
>- ____|_____
>-|          |
>-| Client A |
>-|__________|</literallayout>
>-        </textobject>
>-
>-	<textobject>
>-	  <phrase>Network Layout</phrase>
>-	</textobject>
>-      </mediaobject>
>-
>-      <para>A setup like this is commonly used to share an Internet
>-        connection.  One of the <acronym>LAN</acronym> machines is
>-        connected to the Internet.  The rest of the machines access
>-        the Internet through that <quote>gateway</quote>
>-        machine.</para>
>-    </sect2>
>-
>-    <sect2 id="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"
>-firewall_enable="YES"
>-firewall_type="OPEN"
>-natd_enable="YES"
>-natd_interface="<replaceable>fxp0</replaceable>"
>-natd_flags=""</programlisting>
>-
>-      <informaltable frame="none">
>-        <tgroup cols="2">
>-          <tbody>
>-            <row>
>-              <entry>gateway_enable="YES"</entry>
>-              <entry>Sets up the machine to act as a gateway.  Running
>-                <command>sysctl net.inet.ip.forwarding=1</command>
>-                would have the same effect.</entry>
>-            </row>
>-            <row><entry>firewall_enable="YES"</entry>
>-             <entry>Enables the firewall rules in
>-               <filename>/etc/rc.firewall</filename> at boot.</entry>
>-            </row>
>-            <row><entry>firewall_type="OPEN"</entry>
>-              <entry>This specifies a predefined firewall ruleset that
>-                allows anything in.  See
>-                <filename>/etc/rc.firewall</filename> for additional
>-                types.</entry>
>-            </row>
>-            <row>
>-              <entry>natd_interface="fxp0"</entry>
>-              <entry>Indicates which interface to forward packets through
>-                (the interface connected to the Internet).</entry>
>-            </row>
>-            <row>
>-              <entry>natd_flags=""</entry>
>-              <entry>Any additional configuration options passed to
>-                &man.natd.8; on boot.</entry>
>-            </row>
>-          </tbody>
>-        </tgroup>
>-      </informaltable>
>-
>-      <para>Having the previous options defined in
>-        <filename>/etc/rc.conf</filename> would run
>-        <command>natd -interface fxp0</command> at boot.  This can also
>-        be run manually.</para>
>-
>-      <para>Each machine and interface behind the LAN should be
>-        assigned IP address numbers in the private network space as
>-        defined by <ulink
>-        url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink>
>-        and have a default gateway of the natd machine's internal IP
>-        address.</para>
>-
>-      <para>For example, client <hostid>a</hostid> and
>-        <hostid>b</hostid> behind the LAN have IP addresses of <hostid
>-        role="ipaddr">192.168.0.2</hostid> and <hostid
>-        role="ipaddr">192.168.0.3</hostid>, while the natd machine's
>-        LAN interface has an IP address of <hostid
>-        role="ipaddr">192.168.0.1</hostid>.  Client <hostid>a</hostid>
>-        and <hostid>b</hostid>'s default gateway must be set to that
>-        of the natd machine, <hostid
>-        role="ipaddr">192.168.0.1</hostid>.  The natd machine's
>-        external, or Internet interface does not require any special
>-        modification for natd to work.</para>
>-    </sect2>
>-
>-    <sect2 id="network-natdport-redirection">
>-      <title>Port Redirection</title>
>-
>-      <para>The drawback with natd is that the LAN clients are not accessible
>-        from the Internet.  Clients on the LAN can make outgoing connections to
>-        the world but cannot receive incoming ones.  This presents a problem
>-        if trying to run Internet services on one of the LAN client machines.
>-        A simple way around this is to redirect selected Internet ports on the
>-        natd machine to a LAN client.
>-      </para>
>-
>-      <para>For example, an IRC server runs on Client A, and a web server runs
>-        on Client B.  For this to work properly, connections received on ports
>-        6667 (IRC) and 80 (web) must be redirected to the respective machines.
>-      </para>
>-
>-      <para>The <command>-redirect_port</command> must be passed to
>-        &man.natd.8; with the proper options.  The syntax is as follows:</para>
>-      <para><programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
>-                 [aliasIP:]aliasPORT[-aliasPORT]
>-                 [remoteIP[:remotePORT[-remotePORT]]]</programlisting></para>
>-
>-      <para>In the above example, the argument should be:
>-        <programlisting>    -redirect_port tcp 192.168.0.2:6667 6667
>-    -redirect_port tcp 192.168.0.3:80 80</programlisting>
>-        This will redirect the proper <emphasis>tcp</emphasis> ports to the
>-        LAN client machines.
>-      </para>
>-
>-      <para>The -redirect_port argument can be used to indicate port
>-        ranges over individual ports.  For example, <replaceable>tcp
>-        192.168.0.2:2000-3000 2000-3000</replaceable> would redirect
>-        all connections received on ports 2000 to 3000 to ports 2000
>-        to 3000 on Client A.</para>
>-
>-      <para>These options can be used when directly running
>-        &man.natd.8; or placed within the
>-        <programlisting>natd_flags=""</programlisting> option in
>-        <filename>/etc/rc.conf</filename>.</para>
>-
>-      <para>For further configuration options, consult &man.natd.8;</para>
>-    </sect2>
>-
>-    <sect2 id="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 natd gateway
>-        machine.  <hostid role="ipaddr">128.1.1.1</hostid> can be used
>-        as the natd gateway machine's external IP address, while
>-        <hostid role="ipaddr">128.1.1.2</hostid> and
>-        <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to LAN
>-        clients A and B.</para>
>-
>-      <para>The -redirect_address syntax is as follows:</para>
>-      <para><option> -redirect_address localIP publicIP</option>
>-      </para>
>-
>-      <informaltable frame="none">
>-        <tgroup cols="2">
>-          <tbody>
>-            <row>
>-              <entry>localIP</entry>
>-              <entry>The internal IP address of the LAN client.</entry>
>-            </row>
>-            <row>
>-              <entry>publicIP</entry>
>-              <entry>The external IP address corresponding to the LAN client.</entry>
>-            </row>
>-          </tbody>
>-        </tgroup>
>-      </informaltable>
>-
>-      <para>In the example, this argument would read:</para>
>-      <para><option>    -redirect_address 192.168.0.2 128.1.1.2
>-    -redirect_address 192.168.0.3 128.1.1.3</option></para>
>-
>-      <para>Like -redirect_port, these arguments are also placed within
>-        natd_flags of <filename>/etc/rc.conf</filename>.  With address
>-        redirection, there is no need for port redirection since all data
>-        received on a particular IP address is redirected.</para>
>-
>-      <para>The external IP addresses on the natd machine must be active and aliased
>-        to the external interface.  Look at &man.rc.conf.5; to do so.</para>
>-
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="network-inetd">
>-    <sect1info>
>-      <authorgroup>
>-        <author>
>-          <firstname>Chern</firstname>
>-          <surname>Lee</surname>
>-          <contrib>Contributed by </contrib>
>-        </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 referred to as the <quote>Internet
>-	  Super-Server</quote> because it manages connections for several
>-	daemons.  Programs that provide network service are commonly
>-	known as daemons.  <application>inetd</application> serves as a
>-	managing server for other daemons.  When a connection is
>-	received by <application>inetd</application>, it determines
>-	which daemon the connection is destined for, spawns the
>-	particular daemon and delegates the socket to it.  Running one
>-	instance of <application>inetd</application> reduces the overall
>-	system load as compared to running each daemon individually in
>-	stand-alone mode.</para>
>-
>-      <para>Primarily, <application>inetd</application> is used to
>-	spawn other daemons, but several trivial protocols are handled
>-	directly, such as <application>chargen</application>,
>-	<application>auth</application>, and
>-	<application>daytime</application>.</para>
>-
>-      <para>This section will cover the basics in configuring
>-	<application>inetd</application> through its command-line
>-	options and its configuration file,
>-	<filename>/etc/inetd.conf</filename>.</para>
>-    </sect2>
>-
>-    <sect2 id="network-inetd-settings">
>-      <title>Settings</title>
>-
>-      <para><application>inetd</application> is initialized through
>-	the <filename>/etc/rc.conf</filename> system.  The
>-	<literal>inetd_enable</literal> option is set to
>-	<quote>NO</quote> by default, but is often times turned on by
>-	<application>sysinstall</application> with the medium security
>-	profile.  Placing:
>-	<programlisting>inetd_enable="YES"</programlisting> or
>-	<programlisting>inetd_enable="NO"</programlisting> into
>-	<filename>/etc/rc.conf</filename> can enable or disable
>-	<application>inetd</application> starting at boot time.</para>
>-
>-      <para>Additionally, different command-line options can be passed
>-	to <application>inetd</application> via the
>-	<literal>inetd_flags</literal> option.</para>
>-    </sect2>
>-
>-    <sect2 id="network-inetd-cmdline">
>-      <title>Command-Line Options</title>
>-
>-      <para><application>inetd</application> synopsis:</para>
>-
>-      <para><option>     inetd [-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
>-           [-p filename] [-R rate] [configuration file]</option></para>
>-
>-      <variablelist>
>-	<varlistentry>
>-	  <term>-d</term>
>-
>-	  <listitem>
>-	    <para>Turn on debugging.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-l</term>
>-
>-	  <listitem>
>-	    <para>Turn on logging of successful connections.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-w</term>
>-
>-	  <listitem>
>-	    <para>Turn on TCP Wrapping for external services (on by
>-	      default).</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-W</term>
>-
>-	  <listitem>
>-	    <para>Turn on TCP Wrapping for internal services which are
>-	      built into <application>inetd</application> (on by
>-	      default).</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-c maximum</term>
>-
>-	  <listitem>
>-	    <para>Specify the default maximum number of simultaneous
>-	      invocations of each service; the default is unlimited.
>-	      May be overridden on a per-service basis with the
>-	      <option>max-child</option> parameter.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-C rate</term>
>-
>-	  <listitem>
>-	    <para>Specify the default maximum number of times a
>-	      service can be invoked from a single IP address in one
>-	      minute; the default is unlimited.  May be overridden on a
>-	      per-service basis with the
>-	      <option>max-connections-per-ip-per-minute</option>
>-	      parameter.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-R rate</term>
>-
>-	  <listitem>
>-	    <para>Specify the maximum number of times a service can be
>-	      invoked in one minute; the default is 256.  A rate of 0
>-	      allows an unlimited number of invocations.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-a</term>
>-
>-	  <listitem>
>-	    <para>Specify one specific IP address to bind to.
>-	      Alternatively, a hostname can be specified, in which case
>-	      the IPv4 or IPv6 address which corresponds to that
>-	      hostname is used.  Usually a hostname is specified when
>-	      <application>inetd</application> is run inside a
>-	      &man.jail.8;, in which case the hostname corresponds to
>-	      the &man.jail.8; environment.</para>
>-
>-	    <para>When hostname specification is used and both IPv4
>-	      and IPv6 bindings are desired, one entry with the
>-	      appropriate protocol type for each binding is required for
>-	      each service in <filename>/etc/inetd.conf</filename>.  For
>-	      example, a TCP-based service would need two entries, one
>-	      using <quote>tcp4</quote> for the protocol and the other using
>-	      <quote>tcp6</quote>.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>-p</term>
>-
>-	  <listitem>
>-	    <para>Specify an alternate file in which to store the
>-	      process ID.</para>
>-	  </listitem>
>-	</varlistentry>
>-      </variablelist>
>-
>-      <para>These options can be passed to
>-	<application>inetd</application> using the
>-	<literal>inetd_flags</literal> option in
>-	<filename>/etc/rc.conf</filename>.  By default,
>-	<literal>inetd_flags</literal> is set to <quote>-wW</quote>,
>-	which turns on TCP wrapping for
>-	<application>inetd</application>'s internal and external
>-	services.  For novice users, these parameters usually do not need
>-	to be modified or even entered in
>-	<filename>/etc/rc.conf</filename>.</para>
>-
>-      <note>
>-	<para>An external service is a daemon outside of
>-	  <application>inetd</application>, which is invoked when a
>-	  connection is received for it.  On the other hand, an internal
>-	  service is one that <application>inetd</application> has the
>-	  facility of offering within itself.</para>
>-      </note>
>-
>-    </sect2>
>-
>-    <sect2 id="network-inetd-conf">
>-      <title><filename>inetd.conf</filename></title>
>-
>-      <para>Configuration of <application>inetd</application> is
>-	controlled through the <filename>/etc/inetd.conf</filename>
>-	file.</para>
>-
>-      <para>When a modification is made to
>-	<filename>/etc/inetd.conf</filename>,
>-	<application>inetd</application> can be forced to re-read its
>-	configuration file by sending a HangUP signal to the
>-	<application>inetd</application> process as shown:</para>
>-
>-      <example id="network-inetd-hangup">
>-	<title>Sending <application>inetd</application> a HangUP Signal</title>
>-
>-	<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
>-      </example>
>-
>-      <para>Each line of the configuration file specifies an
>-	individual daemon.  Comments in the file are preceded by a
>-	<quote>#</quote>.  The format of
>-	<filename>/etc/inetd.conf</filename> is as follows:</para>
>-
>-      <programlisting>service-name
>-socket-type
>-protocol
>-{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
>-user[:group][/login-class]
>-server-program
>-server-program-arguments</programlisting>
>-
>-      <para>An example entry for the <application>ftpd</application> daemon
>-	using IPv4:</para>
>-
>-      <programlisting>ftp     stream  tcp     nowait  root    /usr/libexec/ftpd       ftpd -l</programlisting>
>-
>-      <variablelist>
>-	<varlistentry>
>-	  <term>service-name</term>
>-
>-	  <listitem>
>-	    <para>This is the service name of the particular daemon.
>-	      It must correspond to a service listed in
>-	      <filename>/etc/services</filename>.  This determines which
>-	      port <application>inetd</application> must listen to.  If
>-	      a new service is being created, it must be placed in
>-	      <filename>/etc/services</filename>
>-	      first.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>socket-type</term>
>-
>-	  <listitem>
>-	    <para>Either <literal>stream</literal>,
>-	      <literal>dgram</literal>, <literal>raw</literal>, or
>-	      <literal>seqpacket</literal>.  <literal>stream</literal>
>-	      must be used for connection-based, TCP daemons, while
>-	      <literal>dgram</literal> is used for daemons utilizing the
>-	      UDP transport protocol.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>protocol</term>
>-
>-	  <listitem>
>-	    <para>One of the following:</para>
>-
>-	    <informaltable>
>-	      <tgroup cols="2">
>-		<thead>
>-		  <row>
>-		    <entry>Protocol</entry>
>-		    <entry>Explanation</entry>
>-		  </row>
>-		</thead>
>-		<tbody>
>-		  <row>
>-		    <entry>tcp, tcp4</entry>
>-		    <entry>TCP IPv4</entry>
>-		  </row>
>-		  <row>
>-		    <entry>udp, udp4</entry>
>-		    <entry>UDP IPv4</entry>
>-		  </row>
>-		  <row>
>-		    <entry>tcp6</entry>
>-		    <entry>TCP IPv6</entry>
>-		  </row>
>-		  <row>
>-		    <entry>udp6</entry>
>-		    <entry>UDP IPv6</entry>
>-		  </row>
>-		  <row>
>-		    <entry>tcp46</entry>
>-		    <entry>Both TCP IPv4 and v6</entry>
>-		  </row>
>-		  <row>
>-		    <entry>udp46</entry>
>-		    <entry>Both UDP IPv4 and v6</entry>
>-		  </row>
>-		</tbody>
>-	      </tgroup>
>-	    </informaltable>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]</term>
>-
>-	  <listitem>
>-	    <para><option>wait|nowait</option> indicates whether the
>-	      daemon invoked from <application>inetd</application> is
>-	      able to handle its own socket or not.
>-	      <option>dgram</option> socket types must use the wait
>-	      option, while stream socket daemons, which are usually
>-	      multi-threaded, should use <option>nowait</option>.
>-	      <option>wait</option> usually hands off multiple sockets
>-	      to a single daemon, while <option>nowait</option> spawns a
>-	      child daemon for each new socket.</para>
>-
>-	    <para>The maximum number of child daemons
>-	      <application>inetd</application> may spawn can be set using
>-	      the <option>max-child</option> option.  If a limit of ten
>-	      instances of a particular daemon is needed, a
>-	      <literal>/10</literal> would be placed after
>-	      <option>nowait</option>.</para>
>-
>-	    <para>In addition to <option>max-child</option>, another
>-	      option limiting the maximum connections from a single
>-	      place to a particular daemon can be enabled.
>-	      <option>max-connections-per-ip-per-minute</option> does
>-	      just this.  A value of ten here would limit any particular
>-	      IP address connecting to a particular service to ten
>-	      attempts per minute.  This is useful to prevent
>-	      intentional or unintentional resource consumption and
>-	      Denial of Service (DoS) attacks to a machine.</para>
>-
>-	    <para>In this field, <option>wait</option> or
>-	      <option>nowait</option> is mandatory.
>-	      <option>max-child</option> and
>-	      <option>max-connections-per-ip-per-minute</option> are
>-	      optional.</para>
>-
>-	    <para>A stream-type multi-threaded daemon without any
>-	      <option>max-child</option> or
>-	      <option>max-connections-per-ip-per-minute</option> limits
>-	      would simply be: <literal>nowait</literal></para>
>-
>-	    <para>The same daemon with a maximum limit of ten daemons
>-	      would read: <literal>nowait/10</literal></para>
>-
>-	    <para>Additionally, the same setup with a limit of twenty
>-	      connections per IP address per minute and a maximum
>-	      total limit of ten child daemons would read:
>-	      <literal>nowait/10/20</literal></para>
>-
>-	    <para>These options are all utilized by the default
>-	      settings of the <application>fingerd</application> daemon,
>-	      as seen here:</para>
>-
>-	    <programlisting>finger stream  tcp     nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>user</term>
>-
>-	  <listitem>
>-	    <para>The user is the username that the particular daemon
>-	      should run as.  Most commonly, daemons run as the
>-	      <username>root</username> user.  For security purposes, it is
>-	      common to find some servers running as the
>-	      <username>daemon</username> user, or the least privileged
>-	      <username>nobody</username> user.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>server-program</term>
>-
>-	  <listitem>
>-	    <para>The full path of the daemon to be executed when a
>-	      connection is received.  If the daemon is a service
>-	      provided by <application>inetd</application> internally,
>-	      then <option>internal</option> should be
>-	      used.</para>
>-	  </listitem>
>-	</varlistentry>
>-
>-	<varlistentry>
>-	  <term>server-program-arguments</term>
>-
>-	  <listitem>
>-	    <para>This works in conjunction with
>-	      <option>server-program</option> by specifying the
>-	      arguments, starting with argv[0], passed to the daemon on
>-	      invocation.  If <application>mydaemon -d</application> is
>-	      the command line, <literal>mydaemon -d</literal> would be
>-	      the value of <option>server program arguments</option>.
>-	      Again, if the daemon is an internal service, use
>-	      <option>internal</option> here.</para>
>-	  </listitem>
>-	</varlistentry>
>-      </variablelist>
>-    </sect2>
>-
>-    <sect2 id="network-inetd-security">
>-      <title>Security</title>
>-
>-      <para>Depending on the security profile chosen at install, many
>-	of <application>inetd</application>'s daemons may be enabled by
>-	default.  If there is no apparent need for a particular daemon,
>-	disable it!  Place a <quote>#</quote> in front of the daemon in
>-	question, and send a <link linkend="network-inetd-hangup">hangup signal
>-	  to inetd</link>.
>-	Some daemons, such as <application>fingerd</application>, may
>-	not be desired at all because they provide an attacker with too
>-	much information.</para>
>-
>-      <para>Some daemons are not security-conscious and have long, or
>-	non-existent timeouts for connection attempts.  This allows an
>-	attacker to slowly send connections to a particular daemon, thus
>-	saturating available resources.  It may be a good idea to place
>-	<option>ip-per-minute</option> and <option>max-child</option>
>-	limitations on certain daemons.</para>
>-
>-      <para>By default, TCP wrapping is turned on.  Consult the
>-	&man.hosts.access.5; manual page for more information on placing
>-	TCP restrictions on various <application>inetd</application>
>-	invoked daemons.</para>
>-    </sect2>
>-
>-    <sect2 id="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
>-	(ident, identd) network services, and is configurable to a certain
>-	degree.</para>
>-
>-      <para>Consult the &man.inetd.8; manual page for more in-depth
>-	information.</para>
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="network-plip">
>-    <title>Parallel Line IP (PLIP)</title>
>-
>-    <indexterm><primary>PLIP</primary></indexterm>
>-    <indexterm><primary>Parallel Line IP</primary></indexterm>
>-
>-    <para>PLIP lets us run TCP/IP between parallel ports.  It is
>-      useful on machines without network cards, or to install on
>-      laptops.  In this section, we will discuss:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Creating a parallel (laplink) cable.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Connecting two computers with PLIP.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <sect2 id="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>
>-	<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>Get a laplink cable.</para>
>-
>-      <para>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 at 0x378-0x37f irq 7 on isa
>-lpt0: Interrupt-driven
>-lp0: TCP/IP capable interface</screen>
>-
>-      <para>Plug in the laplink cable into the parallel interface on
>-	both computers.</para>
>-
>-      <para>Configure the network interface parameters for <devicename>lp0</devicename> on both
>-	sites as <username>root</username>.  For example, if you want connect
>-	the host <hostid>host1</hostid> with <hostid>host2</hostid>:</para>
>-
>-      <programlisting>                 host1 &lt;-----&gt; host2
>-IP Address    10.0.0.1      10.0.0.2</programlisting>
>-
>-      <para>Configure the interface on <hostid>host1</hostid> by doing:</para>
>-
>-      <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.1 10.0.0.2</userinput></screen>
>-
>-      <para>Configure the interface on host2 by doing:</para>
>-
>-      <screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.2 10.0.0.1</userinput></screen>
>-
>-
>-      <para>You now should have a working connection.  Please read the
>-        manual pages &man.lp.4; and &man.lpt.4; for more details.</para>
>-
>-      <para>You should also add both hosts to
>-	<filename>/etc/hosts</filename>:</para>
>-
>-      <programlisting>127.0.0.1               localhost.my.domain localhost
>-10.0.0.1                host1.my.domain host1
>-10.0.0.2                host2.my.domain</programlisting>
>-
>-      <para>To confirm the connection works, go to each host and ping
>-	the other.  For example, on <hostid>host1</hostid>:</para>
>-
>-          <screen>&prompt.root; <userinput>ifconfig lp0</userinput>
>-lp0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>-        inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
>-&prompt.root; <userinput>netstat -r</userinput>
>-Routing tables
>-
>-Internet:
>-Destination        Gateway          Flags     Refs     Use      Netif Expire
>-host2              host1              UH          4   127592       lp0
>-&prompt.root; <userinput>ping -c 4 host2</userinput>
>-PING host2 (10.0.0.2): 56 data bytes
>-64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
>-64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
>-64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
>-64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
>-
>---- host2 ping statistics ---
>-4 packets transmitted, 4 packets received, 0% packet loss
>-round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>
>-
>-    </sect2>
>-  </sect1>
>-
>-  <sect1 id="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>
>-    </sect1info>
>-
>-    <title>IPv6</title>
>-    <para>IPv6 (also know as IPng <quote>IP next generation</quote>) is
>-      the new version of the well known IP protocol (also know as
>-      <acronym>IPv4</acronym>).  Like the other current *BSD systems,
>-      FreeBSD includes the <acronym>KAME</acronym> IPv6 reference implementation.
>-      So your FreeBSD system comes with all you will need to experiment with IPv6.
>-      This section focuses on getting IPv6 configured and running.</para>
>-
>-    <para>In the early 1990s, people became aware of the rapidly
>-      diminishing address space of IPv4.  Given the expansion rate of the
>-      Internet there were two major concerns:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Running out of addresses.  Today this is not so much of a concern
>-	  anymore since private address spaces
>-	  (<hostid role="ipaddr">10.0.0.0/8</hostid>,
>-	  <hostid role="ipaddr">192.168.0.0/24</hostid>,
>-	  etc.) and Network Address Translation (<acronym>NAT</acronym>) are
>-	  being employed.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Router table entries were getting too large.  This is
>-	  still a concern today.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>IPv6 deals with these and many other issues:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>128 bit address space.  In other words theoretically there are
>-	  340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
>-	  available.  This means there are approximately
>-	  6.67 * 10^27 IPv6 addresses per square meter on our planet.</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Routers will only store network aggregation addresses in their routing
>-	  tables thus reducing the average space of a routing table to 8192
>-	  entries.</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <para>There are also lots of other useful features of IPv6 such as:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>Address autoconfiguration (RFC2462)</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Anycast addresses (<quote>one-out-of many</quote>)</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Mandatory multicast addresses</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>IPsec (IP security)</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Simplified header structure</para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>Mobile <acronym>IP</acronym></para>
>-      </listitem>
>-
>-      <listitem>
>-	<para>IPv4-to-IPv6 transition mechanisms</para>
>-      </listitem>
>-    </itemizedlist>
>-
>-
>-    <para>For more information see:</para>
>-
>-    <itemizedlist>
>-      <listitem>
>-	<para>IPv6 overview at <ulink url="http://www.sun.com">Sun.com</ulink></para>
>-      </listitem>
>-
>-      <listitem>
>-	<para><ulink url="http://www.ipv6.org">IPv6.org</ulink></para>
>-      </listitem>
>-
>-      <listitem>
>-	<para><ulink url="http://www.kame.net">KAME.net</ulink></para>
>-      </listitem>
>-
>-      <listitem>
>-	<para><ulink url="http://www.6bone.net">6bone.net</ulink></para>
>-      </listitem>
>-    </itemizedlist>
>-
>-    <sect2>
>-      <title>Background on IPv6 Addresses</title>
>-      <para>There are different types of IPv6 addresses: Unicast, Anycast and
>-	Multicast.<para>
>-
>-      <para>Unicast addresses are the well known addresses.  A packet sent
>-	to a unicast address arrives exactly at the interface belonging to
>-	the address.</para>
>-
>-      <para>Anycast addresses are syntactically indistinguishable from unicast
>-	addresses but they address a group of interfaces.  The packet destined for
>-	an anycast address will arrive at the nearest (in router metric)
>-	interface.  Anycast addresses may only be used by routers.</para>
>-
>-      <para>Multicast addresses identify a group of interfaces.  A packet destined
>-	for a multicast address will arrive at all interfaces belonging to the
>-	multicast group.</para>
>-
>-	<note><para>The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
>-	  by multicast addresses in IPv6.</para></note>
>-
>-      <para>Reserved IPv6 addresses:</para>
>-
>-<screen>ipv6-address 	prefixlength(Bits)	description	Notes
>-
>-	::			128 Bits			unspecified cf. 0.0.0.0 in IPv4 address
>-	::1			128 Bits			loopback address cf. 127.0.0.1 in IPv4
>-	::00:xx:xx:xx:xx	96 Bits				embedded IPv4	The lower 32 bits are the
>-								address	IPv4 address. Also called
>-								<quote>IPv4 compatible IPv6
>-								address</quote>
>-	::ff:xx:xx:xx:xx	96 Bits		IPv4 mapped     The lower 32 bits are the
>-						IPv6 address	IPv4 address. For hosts
>-								which do not support IPv6
>-	fe80:: - feb::		10 Bits		link-local	cf. loopback address in
>-						IPv4
>-	fec0:: - fef::		10 Bits		site-local
>-	ff::			8 Bits		multicast
>-	001 (base 2)		3 Bits		global unicast	All global unicast
>-								addresses are assigned from
>-								this pool. The first 3 Bits
>-								are <quote>001</quote>.</screen>
>-
>-    </sect2>
>-
>-    <sect2>
>-      <title>Reading IPv6 Addresses</title>
>-      <para>The canonical form is represented as: x:x:x:x:x:x:x:x, each
>-	<quote>x</quote> being a 16 Bit hex value.  For example
>-	<hostid role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></para>
>-
>-      <para>Often an address will have long substrings of all zeros
>-	therefore each such substring can be abbreviated by <quote>::</quote>.
>-	For example <hostid role="ip6addr">fe80::1</hostid>
>-	corresponds to the canonical form
>-	<hostid role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid></para>
>-
>-      <para>A third form is to write the last 32 Bit part in the
>-	well known (decimal) IPv4 style with dots <quote>.</quote>
>-	as separators.  For example
>-	<hostid role="ip6addr">2002::10.0.0.1</hostid>
>-	corresponds to the (hexadecimal) canonical representation
>-	<hostid role="ip6addr">2002:0000:0000:0000:0000:0000: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 includes the
>-	scrambled Ethernet MAC as part of the auto configuration.</para>
>-
>-      <para>For further information on the structure of IPv6 addresses
>-	see RFC2373.</para>
>-    </sect2>
>-
>-    <sect2>
>-      <title>Getting Connected</title>
>-
>-      <para>Currently there are four ways to connect to other IPv6 hosts and networks:</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>Join the experimental 6bone</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Getting an IPv6 network from your upstream provider.  Talk to your
>-	    Internet provider for instructions.</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Tunnel via 6-to-4</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>Use the freenet6 port if you are on a dial-up connection.</para>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <para>Here we will talk on how to connect to the 6bone since it currently seems
>-	to be the most popular way.</para>
>-
>-      <para>First take a look at the 6bone site and find a 6bone connection nearest to
>-	you.  Write to the responsible person and with a little bit of luck you
>-	will be given instructions on how to set up your connection.  Usually this
>-	involves setting up a GRE (gif) tunnel.</para>
>-
>-      <para>Here is a typical example on setting up a &man.gif.4; tunnel:</para>
>-
>-      <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput>
>-&prompt.root; <userinput>ifconfig gif0</userinput>
>-gif0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1280
>-&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>MY_IPv4_ADDR</replaceable>  <replaceable>HIS_IPv4_ADDR</replaceable></userinput>
>-&prompt.root; <userinput>ifconfig gif0 inet6 alias <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable></userinput></screen>
>-
>-      <para>Replace the capitalized words by the information you received from the
>-	upstream 6bone node.</para>
>-
>-      <para>This establishes the tunnel.  Check if the tunnel is working by &man.ping6.8;
>-	'ing ff02::1%gif0.  You should receive two ping replies.</para>
>-
>-	<note><para>In case you are intrigued by the address ff02:1%gif0, this is a
>-	  multicast address.  %gif0 states that the multicast address at network
>-	  interface gif0 is to be used.  Since we <command>ping</command> a multicast address the
>-	  other endpoint of the tunnel should reply as well).</para></note>
>-
>-      <para>By now setting up a route to your 6bone uplink should be rather
>-	straightforward:</para>
>-
>-      <screen>&prompt.root; <userinput>route add -inet6 default -interface gif0</userinput>
>-&prompt.root; <userinput>ping6 -n <replaceable>MY_UPLINK</replaceable></userinput></screen>
>-
>-      <screen>&prompt.root; <userinput>traceroute6 www.jp.FreeBSD.org</userinput>
>-(3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
>-     1  atnet-meta6  14.147 ms  15.499 ms  24.319 ms
>-     2  6bone-gw2-ATNET-NT.ipv6.tilab.com  103.408 ms  95.072 ms *
>-     3  3ffe:1831:0:ffff::4  138.645 ms  134.437 ms  144.257 ms
>-     4  3ffe:1810:0:6:290:27ff:fe79:7677  282.975 ms  278.666 ms  292.811 ms
>-     5  3ffe:1800:0:ff00::4  400.131 ms  396.324 ms  394.769 ms
>-     6  3ffe:1800:0:3:290:27ff:fe14:cdee  394.712 ms  397.19 ms  394.102 ms</screen>
>-
>-      <para>This output will differ from machine to machine.  By now you should be
>-	able to reach the IPv6 site <ulink url="http://www.kame.net">www.kame.net</ulink>
>-	and see the dancing tortoise - that is if you have a IPv6 enabled browser such as
>-	<filename role="package">mozilla</filename>.</para>
>-
>-    </sect2>
>-
>-    <sect2>
>-      <title>DNS in the IPv6 World</title>
>-      <para>There are two new types of DNS records for IPv6:</para>
>-
>-      <itemizedlist>
>-	<listitem>
>-	  <para>AAAA records,</para>
>-	</listitem>
>-
>-	<listitem>
>-	  <para>A6 records</para>
>-	</listitem>
>-      </itemizedlist>
>-
>-      <para>Using AAAA records is straightforward.  Assign your hostname to the new
>-	IPv6 address you just got by adding:</para>
>-
>-      <programlisting>MYHOSTNAME           AAAA    MYIPv6ADDR</programlisting>
>-
>-      <para>To your primary zone DNS file.  In case you do not serve your own
>-	<acronym>DNS</acronym> zones ask your <acronym>DNS</acronym> provider.
>-	Current versions of <application>bind</application> (version 8.3 and 9)
>-	support AAAA records.</para>
>-    </sect2>
>-  </sect1>
>-</chapter>
>-
>-
>-

Actions: View | Diff

Attachments on bug 55883: 34384