<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="advanced-networking">
  <title>Advanced Networking</title>

  <sect1 id="advanced-networking-synopsis">
    <title>Synopsis</title>

    <para>This chapter will cover some of the more frequently used network
      services on &unix; systems.  We will cover how to define, set up, 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 set up IEEE 802.11 and &bluetooth; devices.</para>
      </listitem>

      <listitem>
	<para>How to make FreeBSD act as a bridge.</para>
      </listitem>

      <listitem>
	<para>How to set up a network filesystem.</para>
      </listitem>

      <listitem>
	<para>How to set up network booting on a diskless machine.</para>
      </listitem>

      <listitem>
	<para>How to set up a network information server for sharing user
	  accounts.</para>
      </listitem>

      <listitem>
	<para>How to set up automatic network settings using DHCP.</para>
      </listitem>

      <listitem>
	<para>How to set up a domain name server.</para>
      </listitem>

      <listitem>
	<para>How to synchronize the time and date, and set up a
	  time server, with the NTP protocol.</para>
      </listitem>

      <listitem>
	<para>How to set up network address translation.</para>
      </listitem>

      <listitem>
	<para>How to manage the <application>inetd</application> daemon.</para>
      </listitem>

      <listitem>
	<para>How to connect two computers via PLIP.</para>
      </listitem>

      <listitem>
	<para>How to set up IPv6 on a FreeBSD machine.</para>
      </listitem>

      <listitem>
	<para>How to configure ATM under &os;&nbsp;5.X.</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 <hostid role="ipaddr">224</hostid>) deals
	with multicasting, which will be covered in another section.</para>

      <para>Finally, various attributes of each route can be seen in
	the <literal>Flags</literal> column.  Below is a short table
	of some of these flags and their meanings:</para>

      <informaltable frame="none">
	<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>

      <mediaobject>
	<imageobject>
	  <imagedata fileref="advanced-networking/net-routing">
	</imageobject>

	<textobject>
	  <literallayout class="monospaced">
[Local2]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
      </literallayout>
	</textobject>
      </mediaobject>

      <para>The hosts <hostid>Local1</hostid> and
	<hostid>Local2</hostid> are at your site.
	<hostid>Local1</hostid> is connected to an ISP via a dial up
	PPP connection.  This PPP server computer is connected through
	a local area network to another gateway computer through an
	external interface to the ISPs Internet feed.</para>

      <para>The default routes for each of your machines will be:</para>

      <informaltable frame="none">
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Host</entry>
	      <entry>Default Gateway</entry>
	      <entry>Interface</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>Local2</entry>
	      <entry>Local1</entry>
	      <entry>Ethernet</entry>
	    </row>

	    <row>
	      <entry>Local1</entry>
	      <entry>T1-GW</entry>
	      <entry>PPP</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>A common question is <quote>Why (or how) would we set
	the <hostid>T1-GW</hostid> to be the default gateway for
	<hostid>Local1</hostid>, rather than the ISP server it is
	connected to?</quote>.</para>

      <para>Remember, since the PPP interface is using an address on the ISP's
	local network for your side of the connection, routes for any other
	machines on the ISP's local network will be automatically generated.
	Hence, you will already know how to reach the <hostid>T1-GW</hostid>
	machine, so there is no need for the intermediate step
	of sending traffic to the ISP server.</para>

      <para>It is common to use the address <hostid
	  role="ipaddr">X.X.X.1</hostid> as the gateway address for your local
	network.  So (using the same example), if your local class-C address
	space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
	using <hostid role="ipaddr">10.9.9</hostid> then the default routes
	would be:</para>

      <informaltable frame="none">
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Host</entry>
	      <entry>Default Route</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>Local2 (10.20.30.2)</entry>
	      <entry>Local1 (10.20.30.1)</entry>
	    </row>
	    <row>
	      <entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
	      <entry>T1-GW (10.9.9.1)</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>You can easily define the default route via the
	<filename>/etc/rc.conf</filename> file.  In our example, on the
	<hostid>Local2</hostid> machine, we added the following line
	in <filename>/etc/rc.conf</filename>:</para>

      <programlisting>defaultrouter="10.20.30.1"</programlisting>

      <para>It is also possible to do it directly from the command
	line with the &man.route.8; command:</para>

      <screen>&prompt.root; <userinput>route add default 10.20.30.1</userinput></screen>

      <para>For more informations on manual manipulation of network
	routing tables, consult &man.route.8; manual page.</para>
    </sect2>

    <sect2>
      <title>Dual Homed Hosts</title>
      <indexterm><primary>dual homed hosts</primary></indexterm>
      <para>There is one other type of configuration that we should cover, and
	that is a host that sits on two different networks.  Technically, any
	machine functioning as a gateway (in the example above, using a PPP
	connection) counts as a dual-homed host.  But the term is really only
	used to refer to a machine that sits on two local-area
	networks.</para>

      <para>In one case, the machine has two Ethernet cards, each
	having an address on the separate subnets.  Alternately, the
	machine may only have one Ethernet card, and be using
	&man.ifconfig.8; aliasing.  The former is used if two
	physically separate Ethernet networks are in use, the latter
	if there is one physical network segment, but two logically
	separate subnets.</para>

      <para>Either way, routing tables are set up so that each subnet knows
	that this machine is the defined gateway (inbound route) to the other
	subnet.  This configuration, with the machine acting as a router
	between the two subnets, is often used when we need to implement
	packet filtering or firewall security in either or both
	directions.</para>

      <para>If you want this machine to actually forward packets
        between the two interfaces, you need to tell FreeBSD to enable
        this ability.  See the next section for more details on how
	to do this.</para>
    </sect2>

    <sect2 id="network-dedicated-router">
      <title>Building a Router</title>

      <indexterm><primary>router</primary></indexterm>

      <para>A network router is simply a system that forwards packets
	from one interface to another.  Internet standards and good
	engineering practice prevent the FreeBSD Project from enabling
	this by default in FreeBSD.  You can enable this feature by
	changing the following variable to <literal>YES</literal> in
	&man.rc.conf.5;:</para>

      <programlisting>gateway_enable=YES          # Set to YES if this host will be a gateway</programlisting>

      <para>This option will set the &man.sysctl.8; variable
	<varname>net.inet.ip.forwarding</varname> to
	<literal>1</literal>.  If you should need to stop routing
	temporarily, you can reset this to <literal>0</literal> temporarily.</para>

      <para>Your new router will need routes to know where to send the
	traffic.  If your network is simple enough you can use static
	routes.  FreeBSD also comes with the standard BSD routing
	daemon &man.routed.8;, which speaks RIP (both version 1 and
	version 2) and IRDP.  Support for BGP v4, OSPF v2, and other
	sophisticated routing protocols is available with the
	<filename role="package">net/zebra</filename> package.
	Commercial products such as <application>&gated;</application> are also available for more
	complex network routing solutions.</para>

<indexterm><primary>BGP</primary></indexterm>
<indexterm><primary>RIP</primary></indexterm>
<indexterm><primary>OSPF</primary></indexterm>

      <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>
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Al</firstname>
	    <surname>Hoang</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <!-- Feb 2004 -->
      <title>Setting Up Static Routes</title>

      <sect3>
	<title>Manual Configuration</title>

	<para>Let us assume we have a network as follows:</para>

	<literallayout class="monospaced">
    INTERNET
      | (10.0.0.1/24) Default Router to Internet
      |
      |Interface xl0
      |10.0.0.10/24
   +------+
   |      | RouterA
   |      | (FreeBSD gateway)
   +------+
      | Interface xl1
      | 192.168.1.1/24
      |
  +--------------------------------+
   Internal Net 1      | 192.168.1.2/24
                       |
                   +------+
                   |      | RouterB
                   |      |
                   +------+
                       | 192.168.2.1/24
                       |
                     Internal Net 2
	</literallayout>

	<para>In this scenario, <hostid>RouterA</hostid> is our &os;
	  machine that is acting as a router to the rest of the
	  Internet.  It has a default route set to <hostid
	  role="ipaddr">10.0.0.1</hostid> which allows it to connect
	  with the outside world.  We will assume that
	  <hostid>RouterB</hostid> is already configured properly and
	  knows how to get wherever it needs to go.  (This is simple
	  in this picture.  Just add a default route on
	  <hostid>RouterB</hostid> using <hostid
	  role="ipaddr">192.168.1.1</hostid> as the gateway.)</para>

	<para>If we look at the routing table for
	  <hostid>RouterA</hostid> we would see something like the
	  following:</para>

	<screen>&prompt.user; <userinput>netstat -nr</userinput>
Routing tables

Internet:
Destination        Gateway            Flags    Refs      Use  Netif  Expire
default            10.0.0.1           UGS         0    49378    xl0
127.0.0.1          127.0.0.1          UH          0        6    lo0
10.0.0/24          link#1             UC          0        0    xl0
192.168.1/24       link#2             UC          0        0    xl1</screen>

	<para>With the current routing table  <hostid>RouterA</hostid>
	  will not be able to reach our Internal Net 2.  It does not
	  have a route for <hostid
	  role="ipaddr">192.168.2.0/24</hostid>.  One way to alleviate
	  this is to manually add the route.  The following command
	  would add the Internal Net 2 network to
	  <hostid>RouterA</hostid>'s routing table using <hostid
	  role="ipaddr">192.168.1.2</hostid> as the next hop:</para>

	<screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>

	<para>Now <hostid>RouterA</hostid> can reach any hosts on the
	  <hostid role="ipaddr">192.168.2.0/24</hostid>
	  network.</para>
      </sect3>

      <sect3>
	<title>Persistent Configuration</title>

	<para>The above example is perfect for configuring a static
	  route on a running system.  However, one problem is that the
	  routing information will not persist if you reboot your &os;
	  machine.  The way to handle the addition of a static route
	  is to put it in your <filename>/etc/rc.conf</filename>
	  file:</para>

	<programlisting># Add Internal Net 2 as a static route
static_routes="internalnet2"
route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting>

	<para>The <literal>static_routes</literal> configuration
	  variable is a list of strings seperated by a space.  Each
	  string references to a route name.  In our above example we
	  only have one string in <literal>static_routes</literal>.
	  This string is <replaceable>internalnet2</replaceable>.  We
	  then add a configuration variable called
	  <literal>route_<replaceable>internalnet2</replaceable></literal>
	  where we put all of the configuration parameters we would
	  give to the &man.route.8; command.  For our example above we
	  would have used the command:</para>

	  <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>

	  <para>so we need <literal>"-net 192.168.2.0/24 192.168.1.2"</literal>.</para>

	<para>As said above, we can have more than one string in
	  <literal>static_routes</literal>.  This allows us to
	  create multiple static routes.  The following lines shows
	  an example of adding static routes for the <hostid
	  role="ipaddr">192.168.0.0/24</hostid> and <hostid
	  role="ipaddr">192.168.1.0/24</hostid> networks on an imaginary
	  router:</para>

        <programlisting>static_routes="net1 net2"
route_net1="-net 192.168.0.0/24 192.168.0.1"
route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
      </sect3>
    </sect2>

    <sect2>
      <title>Routing Propagation</title>
      <indexterm><primary>routing propagation</primary></indexterm>
      <para>We have already talked about how we define our routes to the
	outside world, but not about how the outside world finds us.</para>

      <para>We already know that routing tables can be set up so that all
	traffic for a particular address space (in our examples, a class-C
	subnet) can be sent to a particular host on that network, which will
	forward the packets inbound.</para>

      <para>When you get an address space assigned to your site, your service
	provider will set up their routing tables so that all traffic for your
	subnet will be sent down your PPP link to your site.  But how do sites
	across the country know to send to your ISP?</para>

      <para>There is a system (much like the distributed DNS information) that
	keeps track of all assigned address-spaces, and defines their point of
	connection to the Internet Backbone.  The <quote>Backbone</quote> are
	the main trunk lines that carry Internet traffic across the country,
	and around the world.  Each backbone machine has a copy of a master
	set of tables, which direct traffic for a particular network to a
	specific backbone carrier, and from there down the chain of service
	providers until it reaches your network.</para>

      <para>It is the task of your service provider to advertise to the
	backbone sites that they are the point of connection (and thus the
	path inward) for your site.  This is known as route
	propagation.</para>
    </sect2>

    <sect2>
      <title>Troubleshooting</title>
      <indexterm>
        <primary><command>traceroute</command></primary>
      </indexterm>
      <para>Sometimes, there is a problem with routing propagation, and some
	sites are unable to connect to you.  Perhaps the most useful command
	for trying to figure out where routing is breaking down is the
	  &man.traceroute.8; command.  It is equally useful if you cannot seem
	to make a connection to a remote machine (i.e. &man.ping.8;
	fails).</para>

      <para>The &man.traceroute.8; command is run with the name of the remote
	host you are trying to connect to.  It will show the gateway hosts
	along the path of the attempt, eventually either reaching the target
	host, or terminating because of a lack of connection.</para>

      <para>For more information, see the manual page for
	  &man.traceroute.8;.</para>
    </sect2>

    <sect2>
      <title>Multicast Routing</title>
      <indexterm>
	<primary>multicast</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 manual page for
	&man.mrouted.8;.</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.
          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 this 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>On &os;&nbsp;5.2-RELEASE and later, you have to use
	  instead the following options:</para>

	<screen>&prompt.root; <userinput>sysctl net.link.ether.bridge.enable=1</userinput>
&prompt.root; <userinput>sysctl net.link.ether.bridge.config="wi0,xl0"</userinput>
&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>

         <para>Now it is time for the wireless card setup.
         The following command will set the card into an access point:</para>

         <screen>
&prompt.root; <userinput>ifconfig wi0 ssid <replaceable>my_net</replaceable> channel 11 media DS/11Mbps mediaopt hostap up stationname "<replaceable>FreeBSD AP</replaceable>"</userinput>
         </screen>

         <para>The &man.ifconfig.8; line brings the
	  <devicename>wi0</devicename> interface up, sets its SSID to
	  <replaceable>my_net</replaceable>, and sets the station name to
	  <replaceable>FreeBSD AP</replaceable>.  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; manual 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 is 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
        <replaceable>my_net</replaceable>, and encryption turned off.</para>

       <note><para>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, why it is important to do so,
        and why some encryption technologies still do not completely
        protect you.</para></note>

       <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 can set the card to the correct settings for our
       network:</para>

       <screen>&prompt.root; <userinput>ifconfig wi0 inet <replaceable>192.168.0.20</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>my_net</replaceable></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 <literal>associated</literal>, then you may be out of
       range of the access point, 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 <replaceable>my_net</replaceable> wepmode on wepkey <replaceable>0x1234567890</replaceable> 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 <replaceable>192.168.0.20</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>my_net</replaceable> wepmode on wepkey <replaceable>0x1234567890</replaceable></userinput></screen>

      <para>Note that you should replace the <replaceable>0x1234567890</replaceable> 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 data over a wireless network.  You can
       read more about &man.ipsec.4; security and how to implement it
       in the <link linkend="ipsec">IPsec</link> section of this
       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 this
      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 <command>wicontrol</command>, <command>ancontrol</command> and <command>raycontrol</command> Utilities</title>

    <para>These are the tools you can 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 <command>ifconfig</command> Command</title>
    <indexterm><primary>ifconfig</primary></indexterm>

    <para>The &man.ifconfig.8; command 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-bluetooth">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Pav</firstname>
          <surname>Lucistnik</surname>
          <contrib>Written by </contrib>
          <affiliation>
            <address><email>pav@oook.cz</email></address>
          </affiliation>
        </author>
      </authorgroup>
    </sect1info>
    <title>Bluetooth</title>

    <indexterm><primary>Bluetooth</primary></indexterm>
    <sect2>
      <title>Introduction</title>
      <para>Bluetooth is a wireless technology for creating personal networks
        operating in the 2.4 GHz unlicensed band, with a range of 10 meters.
        Networks are usually formed ad-hoc from portable devices such as
        cellular phones, handhelds and laptops. Unlike the other popular
        wireless technology, Wi-Fi, Bluetooth offers higher level service
        profiles, e.g. FTP-like file servers, file pushing, voice transport,
        serial line emulation, and more.</para>

      <para>The Bluetooth stack in &os; is implemented using the Netgraph
        framework (see &man.netgraph.4;). A broad variety of Bluetooth USB
        dongles is supported by the &man.ng.ubt.4; driver. The Broadcom BCM2033
        chip based Bluetooth devices are supported via the &man.ubtbcmfw.4; and
        &man.ng.ubt.4; drivers. The 3Com Bluetooth PC Card 3CRWB60-A is
        supported by the &man.ng.bt3c.4; driver. Serial and UART based
        Bluetooth devices are supported via &man.sio.4;, &man.ng.h4.4;
        and &man.hcseriald.8;. This chapter describes the use of the USB
        Bluetooth dongle. Bluetooth support is available in &os; 5.0 and newer
        systems.</para>
    </sect2>

    <sect2>
      <title>Plugging in the Device</title>
      <para>By default Bluetooth device drivers are available as kernel modules.
        Before attaching a device, you will need to load the driver into the
        kernel.</para>

      <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>

      <para>If the Bluetooth device is present in the system during system
        startup, load the module from
        <filename>/boot/loader.conf</filename>.</para>

      <programlisting>ng_ubt_load="YES"</programlisting>

      <para>Plug in your USB dongle. The output similar to the following will
        appear on the console (or in syslog).</para>

      <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
      wMaxPacketSize=49, nframes=6, buffer size=294</screen>

      <para>Copy
        <filename>/usr/share/examples/netgraph/bluetooth/rc.bluetooth</filename>
        into some convenient place, like <filename>/etc/rc.bluetooth</filename>.
        This script is used to start and stop the Bluetooth stack. It is a good
        idea to stop the stack before unplugging the device, but it is not
        (usually) fatal. When starting the stack, you will receive output similar
        to the following:</para>

      <screen>&prompt.root; <userinput>/etc/rc.bluetooth start ubt0</userinput>
BD_ADDR: 00:02:72:00:d4:1a
Features: 0xff 0xff 0xf 00 00 00 00 00
&lt;3-Slot&gt; &lt;5-Slot&gt; &lt;Encryption&gt; &lt;Slot offset&gt;
&lt;Timing accuracy&gt; &lt;Switch&gt; &lt;Hold mode&gt; &lt;Sniff mode&gt;
&lt;Park mode&gt; &lt;RSSI&gt; &lt;Channel quality&gt; &lt;SCO link&gt;
&lt;HV2 packets&gt; &lt;HV3 packets&gt; &lt;u-law log&gt; &lt;A-law log&gt; &lt;CVSD&gt;
&lt;Paging scheme&gt; &lt;Power control&gt; &lt;Transparent SCO data&gt;
Max. ACL packet size: 192 bytes
Number of ACL packets: 8
Max. SCO packet size: 64 bytes
Number of SCO packets: 8</screen>

    </sect2>

    <indexterm><primary>HCI</primary></indexterm>
    <sect2>
      <title>Host Controller Interface (HCI)</title>

      <para>Host Controller Interface (HCI) provides a command interface to the
        baseband controller and link manager, and access to hardware status and
        control registers. This interface provides a uniform method of accessing
        the Bluetooth baseband capabilities. HCI layer on the Host exchanges
        data and commands with the HCI firmware on the Bluetooth hardware.
        The Host Controller Transport Layer (i.e. physical bus) driver provides
        both HCI layers with the ability to exchange information with each
        other.</para>

      <para>A single Netgraph node of type <emphasis>hci</emphasis> is
        created for a single Bluetooth device. The HCI node is normally
        connected to the Bluetooth device driver node (downstream) and
        the L2CAP node (upstream). All HCI operations must be performed
        on the HCI node and not on the device driver node. Default name
        for the HCI node is <quote>devicehci</quote>.
        For more details refer to the &man.ng.hci.4; man page.</para>

      <para>One of the most common tasks is discovery of Bluetooth devices in
        RF proximity. This operation is called <emphasis>inquiry</emphasis>.
        Inquiry and other HCI realated operations are done with the
        &man.hccontrol.8; utility. The example below shows how to find out
        which Bluetooth devices are in range. You should receive the list of
        devices in a few seconds. Note that a remote device will only answer
        the inquiry if it put into <emphasis>discoverable</emphasis>
        mode.</para>

      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
Inquiry result, num_responses=1
Inquiry result #0
       BD_ADDR: 00:80:37:29:19:a4
       Page Scan Rep. Mode: 0x1
       Page Scan Period Mode: 00
       Page Scan Mode: 00
       Class: 52:02:04
       Clock offset: 0x78ef
Inquiry complete. Status: No error [00]</screen>

      <para><literal>BD_ADDR</literal> is unique address of a Bluetooth
        device, similar to MAC addresses of a network card. This address
        is needed for further communication with a device. It is possible
        to assign human readable name to a BD_ADDR.
        The <filename>/etc/bluetooth/hosts</filename> file contains information
        regarding the known Bluetooth hosts. The following example shows how
        to obtain human readable name that was assigned to the remote
        device.</para>

      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput>
BD_ADDR: 00:80:37:29:19:a4
Name: Pav's T39</screen>

      <para>If you perform an inquiry on a remote Bluetooth device, it will
        find your computer as <quote>your.host.name (ubt0)</quote>. The name
        assigned to the local device can be changed at any time.</para>

      <para>The Bluetooth system provides a point-to-point connection (only two
        Bluetooth units involved), or a point-to-multipoint connection. In the
        point-to-multipoint connection the connection is shared among several
        Bluetooth devices. The following example shows how to obtain the list
        of active baseband connections for the local device.</para>

      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
Remote BD_ADDR    Handle Type Mode Role Encrypt Pending Queue State
00:80:37:29:19:a4     41  ACL    0 MAST    NONE       0     0 OPEN</screen>

      <para>A <emphasis>connection handle</emphasis> is useful when termination
        of the baseband connection is required. Note, that it is normally not
        required to do it by hand. The stack will automatically terminate
        inactive baseband connections.</para>

      <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput>
Connection handle: 41
Reason: Connection terminated by local host [0x16]</screen>

      <para>Refer to <command>hccontrol help</command> for a complete listing
        of available HCI commands. Most of the HCI commands do not require
        superuser privileges.</para>

    </sect2>

    <indexterm><primary>L2CAP</primary></indexterm>
    <sect2>
      <title>Logical Link Control and Adaptation Protocol (L2CAP)</title>

      <para>Logical Link Control and Adaptation Protocol (L2CAP) provides
        connection-oriented and connectionless data services to upper layer
        protocols with protocol multiplexing capability and segmentation and
        reassembly operation. L2CAP permits higher level protocols and
        applications to transmit and receive L2CAP data packets up to 64
        kilobytes in length.</para>

      <para>L2CAP is based around the concept of <emphasis>channels</emphasis>.
        Channel is a logical connection on top of baseband connection. Each
        channel is bound to a single protocol in a many-to-one fashion. Multiple
        channels can be bound to the same protocol, but a channel cannot be
        bound to multiple protocols. Each L2CAP packet received on a channel is
        directed to the appropriate higher level protocol. Multiple channels
        can share the same baseband connection.</para>

      <para>A single Netgraph node of type <emphasis>l2cap</emphasis> is
        created for a single Bluetooth device. The L2CAP node is normally
        connected to the Bluetooth HCI node (downstream) and Bluetooth sockets
        nodes (upstream). Default name for the L2CAP node is
        <quote>devicel2cap</quote>. For more details refer to the
        &man.ng.l2cap.4; man page.</para>

      <para>A useful command is &man.l2ping.8;, which can be used to ping
        other devices. Some Bluetooth implementations might not return all of
        the data sent to them, so <emphasis>0 bytes</emphasis> in the following
        example is normal.</para>

      <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>

      <para>The &man.l2control.8; utility is used to perform various operations
        on L2CAP nodes. This example shows how to obtain the list of logical
        connections (channels) and the list of baseband connections for the
        local device.</para>

      <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
L2CAP channels:
Remote BD_ADDR     SCID/ DCID   PSM  IMTU/ OMTU State
00:07:e0:00:0b:ca    66/   64     3   132/  672 OPEN
&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput>
L2CAP connections:
Remote BD_ADDR    Handle Flags Pending State
00:07:e0:00:0b:ca     41 O           0 OPEN</screen>

      <para>Another diagnostic tool is &man.btsockstat.1;. It does a job
        similar to as &man.netstat.1; does, but for Bluetooth network-related
        data structures. The example below shows the same logical connection as
        &man.l2control.8; above.</para>

      <screen>&prompt.user; <userinput>btsockstat</userinput>
Active L2CAP sockets
PCB      Recv-Q Send-Q Local address/PSM       Foreign address   CID   State
c2afe900      0      0 00:02:72:00:d4:1a/3     00:07:e0:00:0b:ca 66    OPEN
Active RFCOMM sessions
L2PCB    PCB      Flag MTU   Out-Q DLCs State
c2afe900 c2b53380 1    127   0     Yes  OPEN
Active RFCOMM sockets
PCB      Recv-Q Send-Q Local address     Foreign address   Chan DLCI State
c2e8bc80      0    250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3    6    OPEN</screen>

    </sect2>

    <indexterm><primary>RFCOMM</primary></indexterm>
    <sect2>
      <title>RFCOMM Protocol</title>

      <para>The RFCOMM protocol provides emulation of serial ports over the
        L2CAP protocol. The protocol is based on the ETSI standard TS 07.10.
        RFCOMM is a simple transport protocol, with additional provisions for
        emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The
        RFCOMM protocol supports up to 60 simultaneous connections (RFCOMM
        channels) between two Bluetooth devices.</para>

      <para>For the purposes of RFCOMM, a complete communication path involves
        two applications running on different devices (the communication
        endpoints) with a communication segment between them. RFCOMM is intended
        to cover applications that make use of the serial ports of the devices
        in which they reside. The communication segment is a Bluetooth link from
        one device to another (direct connect).</para>

      <para>RFCOMM is only concerned with the connection between the devices in
        the direct connect case, or between the device and a modem in the
        network case. RFCOMM can support other configurations, such as modules
        that communicate via Bluetooth wireless technology on one side and
        provide a wired interface on the other side.</para>

      <para>In &os; the RFCOMM protocol is implemented at the Bluetooth sockets
        layer.</para>
    </sect2>

    <indexterm><primary>pairing</primary></indexterm>
    <sect2>
      <title>Pairing of Devices</title>

      <para>By default, Bluetooth communication is not authenticated, and any
        device can talk to any other device. A Bluetooth device (for example,
        cellular phone) may choose to require authentication to provide a
        particular service (for example, Dial-Up service). Bluetooth
        authentication is normally done with <emphasis>PIN codes</emphasis>.
        A PIN code is an ASCII string up to 16 characters in length. User is
        required to enter the same PIN code on both devices. Once user has
        entered the PIN code, both devices will generate a
        <emphasis>link key</emphasis>. After that the link key can be stored
        either in the devices themselves or in a persistent storage. Next time
        both devices will use previously generated link key. The described
        above procedure is called <emphasis>pairing</emphasis>. Note that if
        the link key is lost by any device then pairing must be repeated.</para>

      <para>The &man.hcsecd.8; daemon is responsible for handling of all
        Bluetooth authentication requests. The default configuration file is
        <filename>/etc/bluetooth/hcsecd.conf</filename>. An example section for
        a cellular phone with the PIN code arbitrarily set to
        <quote>1234</quote> is shown below.</para>

      <programlisting>device {
        bdaddr  00:80:37:29:19:a4;
        name    "Pav's T39";
        key     nokey;
        pin     "1234";
      }</programlisting>

      <para>There is no limitation on PIN codes (except length). Some devices
        (for example Bluetooth headsets) may have a fixed PIN code built in.
        The <option>-d</option> switch forces the &man.hcsecd.8; daemon to stay
        in the foreground, so it is easy to see what is happening. Set the
        remote device to receive pairing and initiate the Bluetooth connection
        to the remote device. The remote device should say that pairing was
        accepted, and request the PIN code. Enter the same PIN code as you
        have in <filename>hcsecd.conf</filename>. Now your PC and the remote
        device are paired. Alternatively, you can initiate pairing on the remote
        device. Below in the sample <command>hcsecd</command> output.</para>

<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting>

    </sect2>

    <indexterm><primary>SDP</primary></indexterm>
    <sect2>
      <title>Service Discovery Protocol (SDP)</title>
      <para>The Service Discovery Protocol (SDP) provides the means for client
        applications to discover the existence of services provided by server
        applications as well as the attributes of those services. The attributes
        of a service include the type or class of service offered and the
        mechanism or protocol information needed to utilize the service.</para>

      <para>SDP involves communication between a SDP server and a SDP client.
        The server maintains a list of service records that describe the
        characteristics of services associated with the server. Each service
        record contains information about a single service. A client may 
        retrieve information from a service record maintained by the SDP server
        by issuing a SDP request. If the client, or an application associated
        with the client, decides to use a service, it must open a separate
        connection to the service provider in order to utilize the service.
        SDP provides a mechanism for discovering services and their attributes,
        but it does not provide a mechanism for utilizing those services.</para>

      <para>Normally, a SDP client searches for services based on some desired
        characteristics of the services. However, there are times when it is
        desirable to discover which types of services are described by an SDP
        server's service records without any a priori information about the
        services. This process of looking for any offered services is called
        <emphasis>browsing</emphasis>.</para>
 
      <para>The Bluetooth SDP server &man.sdpd.8; and command line client
        &man.sdpcontrol.8; are included in the standard &os; installation.
        The following example shows how to perform a SDP browse query.</para>

      <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput>
Record Handle: 00000000
Service Class ID List:
        Service Discovery Server (0x1000)
Protocol Descriptor List:
        L2CAP (0x0100)
                Protocol specific parameter #1: u/int/uuid16 1
                Protocol specific parameter #2: u/int/uuid16 1

Record Handle: 0x00000001
Service Class ID List:
        Browse Group Descriptor (0x1001)

Record Handle: 0x00000002
Service Class ID List:
        LAN Access Using PPP (0x1102)
Protocol Descriptor List:
        L2CAP (0x0100)
        RFCOMM (0x0003)
                Protocol specific parameter #1: u/int8/bool 1
Bluetooth Profile Descriptor List:
        LAN Access Using PPP (0x1102) ver. 1.0
</screen>

      <para>... and so on. Note that each service has a list of attributes
        (RFCOMM channel for example). Depending on the service you might need to
        make a note of some of the attributes. Some Bluetooth implementations do
        not support service browsing and may return an empty list. In this case
        it is possible to search for the specific service. The example below
        shows how to search for the OBEX Object Push (OPUSH) service.</para>

      <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen>

      <para>Offering services on &os; to Bluetooth clients is done with the
        &man.sdpd.8; server.</para>
      <screen>&prompt.root; <userinput>sdpd</userinput></screen>

      <para>The local server application that wants to provide Bluetooth
        service to the remote clients will register service with the local
        SDP daemon. The example of such application is &man.rfcomm.pppd.8;.
        Once started it will register Bluetooth LAN service with the local
        SDP daemon.</para>

      <para>The list of services registered with the local SDP server can be
        obtained by issuing SDP browse query via local control channel.</para>

      <screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen>

    </sect2>

    <sect2>
      <title>Dial-Up Networking (DUN) and Network Access with PPP (LAN)
        Profiles</title>

      <para>The Dial-Up Networking (DUN) profile is mostly used with modems
        and cellular phones. The scenarios covered by this profile are the
        following:</para>

      <itemizedlist>
        <listitem><para>use of a cellular phone or modem by a computer as
          a wireless modem for connecting to a dial-up internet access server,
          or using other dial-up services;</para></listitem>

        <listitem><para>use of a cellular phone or modem by a computer to
          receive data calls.</para></listitem>
      </itemizedlist>

      <para>Network Access with PPP (LAN) profile can be used in the following
        situations:</para>

      <itemizedlist>
        <listitem><para>LAN access for a single Bluetooth device;
           </para></listitem>

        <listitem><para>LAN access for multiple Bluetooth devices;
          </para></listitem>

        <listitem><para>PC to PC (using PPP networking over serial cable
          emulation).</para></listitem>
      </itemizedlist>

      <para>In &os; both profiles are implemented with &man.ppp.8; and
        &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth
        connection into something PPP can operate with. Before any profile
        can be used, a new PPP label in the <filename>/etc/ppp/ppp.conf</filename>
        must be created. Consult &man.rfcomm.pppd.8; manual page for examples.
      </para>

      <para>In the following example &man.rfcomm.pppd.8; will be used to open
        RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on
        DUN RFCOMM channel. The actual RFCOMM channel number will be obtained
        from the remote device via SDP. It is possible to specify RFCOMM channel
        by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP
        query. Use &man.sdpcontrol.8; to find out RFCOMM
        channel on the remote device.</para>

      <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>

      <para>In order to provide Network Access with PPP (LAN) service the
        &man.sdpd.8; server must be running. A new entry for LAN clients must
        be created in the <filename>/etc/ppp/ppp.conf</filename> file. Consult
        &man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP
        server on valid RFCOMM channel number. The RFCOMM PPP server will
        automatically register Bluetooth LAN service with the local SDP daemon.
        The example below shows how to start RFCOMM PPP server.</para>

      <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>

    </sect2>

    <indexterm><primary>OBEX</primary></indexterm>
    <sect2>
      <title>OBEX Object Push (OPUSH) Profile</title>
      <para>OBEX is a widely used protocol for simple file transfers between
        mobile devices. Its main use is in infrared communication, where it is
        used for generic file transfers between notebooks or Palm handhelds,
        and for sending business cards or calendar entries between cellular
        phones and other devices with PIM applications.</para>

      <para>The OBEX server and client are implemented as a third-party package
        <application>obexapp-1.2</application> that can be downloaded from
        <ulink url="http://www.geocities.com/m_evmenkin/">here</ulink>.
        The package requires the <application>openobex-1.0.1</application>
        library (included) and the <filename role="package">devel/gmake</filename>
        port.</para>

      <para>OBEX client is used to push and/or pull objects from the OBEX server.
        An object can, for example, be a business card or an appointment.
        The OBEX client can obtain RFCOMM channel number from the remote device
        via SDP. This can be done by specifying service name instead of RFCOMM
        channel number. Supported service names are: IrMC, FTRN and OPUSH.
        It is possible to specify RFCOMM channel as a number. Below is an
        example of an OBEX session, where device information object is pulled
        from the cellular phone, and a new object (business card) is pushed
        into the phone's directory.</para>

      <screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput>
obex&gt; get
get: remote file&gt; telecom/devinfo.txt
get: local file&gt; devinfo-t39.txt
Success, response: OK, Success (0x20)
obex&gt; put
put: local file&gt; new.vcf
put: remote file&gt; new.vcf
Success, response: OK, Success (0x20)
obex&gt; di
Success, response: OK, Success (0x20)</screen>

      <para>In order to provide OBEX Object Push service,
        &man.sdpd.8; server must be running. A root folder, where all incoming
        objects will be stored, must be created. The default path to the root
        folder is <filename>/var/spool/obex</filename>. Finally, start OBEX
        server on valid RFCOMM channel number. The OBEX server will
        automatically register OBEX Object Push service with the local SDP
        daemon. The example below shows how to start OBEX server.</para>

      <screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
    </sect2>

    <sect2>
      <title>Serial Port (SP) Profile</title>
      <para>The Serial Port (SP) profile allows Bluetooth device to perform
        RS232 (or similar) serial cable emulation. The scenario covered by this
        profile deals with legacy applications using Bluetooth as a cable
        replacement, through a virtual serial port abstraction.</para>

      <para>The &man.rfcomm.sppd.1; utility implements the Serial Port profile.
        Pseudo tty is used as a virtual serial port abstraction. The example
        below shows how to connect to a remote device Serial Port service.
        Note that you do not have to specify RFCOMM channel -
        &man.rfcomm.sppd.1; can obtain it from the remote device via SDP.
        If you would like to override this, specify RFCOMM channel in the
        command line.</para>

      <screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6</userinput>
rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen>

      <para>Once connected pseudo tty can be used as serial port.</para>

      <screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen>

    </sect2>

    <sect2>
      <title>Troubleshooting</title>

      <sect3>
        <title>A remote device cannot connect</title>
        <para>Some older Bluetooth devices do not support role switching.
          By default, when &os; is accepting a new connection, it tries to
          perform role switch and become a master. Devices, which do not
          support this will not be able to connect. Note the role switching is
          performed when a new connection is being established, so it is not
          possible to ask the remote device if it does support role switching.
          There is a HCI option to disable role switching on the local
          side.</para>

        <screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>

      </sect3>

      <sect3>
        <title>Something is going wrong, can I see what exactly is happening?</title>
        <para>Yes, you can. Use the <application>hcidump-1.5</application>
          third-party package that can be downloaded from
          <ulink url="http://www.geocities.com/m_evmenkin/">here</ulink>.
          The <application>hcidump</application> utility is similar to
          &man.tcpdump.1;. It can used to display the content of the Bluetooth
          packets on the terminal and to dump the Bluetooth packets to a
          file.</para>
      </sect3>

    </sect2>

  </sect1>

  <sect1 id="network-bridging">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Steve</firstname>
      	  <surname>Peterson</surname>
	  <contrib>Written by </contrib>
        </author>
      </authorgroup>
    </sect1info>
    <title>Bridging</title>

    <sect2>
      <title>Introduction</title>
      <indexterm><primary>IP subnet</primary></indexterm>
      <indexterm><primary>bridge</primary></indexterm>
      <para>It is sometimes useful to divide one physical network
	(such as an Ethernet segment) into two separate network
	segments without having to create IP subnets and use a router
	to connect the segments together.  A device that connects two
	networks together in this fashion is called a
	<quote>bridge</quote>.  A FreeBSD system with two network
	interface cards can act as a bridge.</para>

      <para>The bridge works by learning the MAC layer addresses
	(Ethernet addresses) of the devices on each of its network interfaces.
	It forwards traffic between two networks only when its source and
	destination are on different networks.</para>

      <para>In many respects, a bridge is like an Ethernet switch with very
	few ports.</para>
    </sect2>

    <sect2>
      <title>Situations Where Bridging Is Appropriate</title>

      <para>There are two common situations in which a bridge is used
	today.</para>

      <sect3>
	<title>High Traffic on a Segment</title>

	<para>Situation one is where your physical network segment is
	  overloaded with traffic, but you do not want for whatever reason to
	  subnet the network and interconnect the subnets with a
	  router.</para>

	<para>Let us consider an example of a newspaper where the Editorial and
	  Production departments are on the same subnetwork.  The Editorial
	  users all use server <hostid>A</hostid> for file service, and the Production users
	  are on server <hostid>B</hostid>.  An Ethernet network is used to connect all users together,
	  and high loads on the network are slowing things down.</para>

	<para>If the Editorial users could be segregated on one
	  network segment and the Production users on another, the two
	  network segments could be connected with a bridge.  Only the
	  network traffic destined for interfaces on the
	  <quote>other</quote> side of the bridge would be sent to the
	  other network, reducing congestion on each network
	  segment.</para>
      </sect3>

      <sect3>
	<title>Filtering/Traffic Shaping Firewall</title>
	<indexterm><primary>firewall</primary></indexterm>
	<indexterm><primary>network address translation</primary></indexterm>

	<para>The second common situation is where firewall functionality is
	  needed without network address translation (NAT).</para>

	<para>An example is a small company that is connected via DSL
	  or ISDN to their ISP.  They have a 13 globally-accessible IP
	  addresses from their ISP and have 10 PCs on their network.
	  In this situation, using a router-based firewall is
	  difficult because of subnetting issues.</para>

	<indexterm><primary>router</primary></indexterm>
	<indexterm><primary>DSL</primary></indexterm>
	<indexterm><primary>ISDN</primary></indexterm>
	<para>A bridge-based firewall can be configured and dropped into the
	  path just downstream of their DSL/ISDN router without any IP
	  numbering issues.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Configuring a Bridge</title>

      <sect3>
	<title>Network Interface Card Selection</title>

	<para>A bridge requires at least two network cards to function.
	  Unfortunately, not all network interface cards 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 <literal>IPFIREWALL</literal> option as
	  well.  Read <xref linkend="firewalls"> for general
	  information on configuring the bridge as a firewall.</para>

	<para>If you need to allow non-IP packets (such as ARP) to flow
	  through the bridge, there is a firewall option that
	  must be set.  This option is
	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this
	  changes the default rule for the firewall to accept any packet.
	  Make sure you know how this changes the meaning of your ruleset
	  before you set it.</para>
      </sect3>

      <sect3>
	<title>Traffic Shaping Support</title>

	<para>If you want to use the bridge as a traffic shaper, you will need
	  to add the <literal>DUMMYNET</literal> option to your kernel
	  configuration.  Read &man.dummynet.4; for further
	  information.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Enabling the Bridge</title>

      <para>Add the line:</para>

      <programlisting>net.link.ether.bridge=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>

      <para>For &os;&nbsp;5.2-RELEASE and later, use instead the following
	lines:</para>

      <programlisting>net.link.ether.bridge.enable=1
net.link.ether.bridge.config=<replaceable>if1</replaceable>,<replaceable>if2</replaceable>
net.link.ether.bridge.ipfw=1</programlisting>

    </sect2>
    
    <sect2>
      <title>Other Information</title>

      <para>If you want to be able to &man.telnet.1; into the bridge from the network,
	it is correct to assign one of the network cards an IP address.  The
	consensus is that assigning both cards an address is a bad
	idea.</para>

      <para>If you have multiple bridges on your network, there cannot be more
	than one path between any two workstations.  Technically, this means
	that there is no support for spanning tree link management.</para>

      <para>A bridge can add latency to your &man.ping.8; times, especially for
        traffic from one segment to another.</para>
      
    </sect2>
  </sect1>

  <sect1 id="network-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 set up on the
	  <acronym>NFS</acronym> server and made available throughout
	  the network.</para>
      </listitem>

      <listitem>
	<para>Storage devices such as floppy disks, CDROM drives, and
	  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>
      <authorgroup>
	<author>
	  <firstname>Alex</firstname>
	  <surname>Dupre</surname>
	  <contrib>Reorganized and enhanced by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Diskless Operation</title>

    <indexterm><primary>diskless workstation</primary></indexterm>
    <indexterm><primary>diskless operation</primary></indexterm>

    <para>A FreeBSD machine can boot over the network and operate without a
      local disk, using filesystems mounted from an <acronym>NFS</acronym> server.  No system
      modification is necessary, beyond standard configuration files.
      Such a system is relatively easy to  set up because all the necessary elements
      are readily available:</para>
    <itemizedlist>
      <listitem>
	<para>There are at least two possible methods to load the kernel over
	  the network:</para>
	<itemizedlist>
	  <listitem>
	    <para><acronym>PXE</acronym>: The &intel; Preboot Execution
	      Environment system is a form of smart boot ROM built into some
	      networking cards or motherboards.  See &man.pxeboot.8; for more
	      details.</para>
	  </listitem>
	  <listitem>
	    <para>The <application>etherboot</application>
	      port (<filename
	      role="package">net/etherboot</filename>) produces
	      ROM-able code to boot kernels over the network.  The
	      code can be either burnt into a boot PROM on a network
	      card, or loaded from a local floppy (or hard) disk
	      drive, or from a running &ms-dos; system.  Many network
	      cards are supported.</para>
	  </listitem>
	</itemizedlist>
	</listitem>

      <listitem>
	<para>A sample script
	  (<filename>/usr/share/examples/diskless/clone_root</filename>) eases
	  the creation and maintenance of the workstation's root 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 <acronym>NFS</acronym> file or to
	  a local disk.</para>
      </listitem>
    </itemizedlist>

    <para>There are many ways to set up diskless workstations.  Many
      elements are involved, and most can be customized to suit local
      taste.  The following will describe variations on the setup of a complete system,
      emphasizing simplicity and compatibility with the
      standard FreeBSD startup scripts.  The system described has the
      following characteristics:</para>

    <itemizedlist>
      <listitem>
	<para>The diskless workstations use a shared
	  read-only <filename>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; (&os;&nbsp;4.X) or &man.md.4; (&os;&nbsp;5.X) filesystems.  Any changes
	  will be lost when the system reboots.</para>
      </listitem>
      <listitem>
	<para>The kernel is transferred and loaded either with
	  <application>etherboot</application> or <acronym>PXE</acronym>
	  as some situations may mandate the use of either method.</para>
      </listitem>
    </itemizedlist>

    <caution><para>As described, this system is insecure.  It should
	live in a protected area of a network, and be untrusted by
	other hosts.</para>
    </caution>

    <para>All the information in this section has been tested
      using &os; releases 4.9-RELEASE and 5.2.1-RELEASE.  The text is
      primarily structured for 4.X usage.  Notes have been inserted where
      appropriate to indicate 5.X changes.</para>

    <sect2>
      <title>Background Information</title>

      <para>Setting up diskless workstations is both relatively
	straightforward and prone to errors.  These are sometimes
	difficult to diagnose for a number of reasons.  For example:</para>

      <itemizedlist>
	<listitem>
	  <para>Compile time options may determine different behaviours at
	    runtime.</para>
	</listitem>

	<listitem>
	  <para>Error messages are often cryptic or totally absent.</para>
	</listitem>
      </itemizedlist>

      <para>In this context, having some knowledge of the background
	mechanisms involved is very useful to solve the problems that
	may arise.</para>

      <para>Several operations need to be performed for a successful
	bootstrap:</para>
        
      <itemizedlist>
	<listitem>
	  <para>The machine needs to obtain initial parameters such as its IP
	    address, executable filename, server name, root path.  This is
	    done using the <acronym>DHCP</acronym> or BOOTP protocols.
	    <acronym>DHCP</acronym> is a compatible extension of BOOTP, and
	    uses the same port numbers and basic packet format.</para>

	  <para>It is possible to configure a system to use only BOOTP.
	    The &man.bootpd.8; server program is included in the base &os;
	    system.</para>

	  <para>However, <acronym>DHCP</acronym> has a number of advantages
	    over BOOTP (nicer configuration files, possibility of using
	    <acronym>PXE</acronym>, plus many others not directly related to
	    diskless operation), and we will describe mainly a
	    <acronym>DHCP</acronym> configuration, with equivalent exemples
	    using &man.bootpd.8; when possible.  The sample configuration will
	    use the <application>ISC DHCP</application> software package
	    (release 3.0.1.r12 was installed on the test server).</para>
	</listitem>

	<listitem>
	  <para>The machine needs to transfer one or several programs to local
	    memory.  Either <acronym>TFTP</acronym> or <acronym>NFS</acronym>
	    are used.  The choice between <acronym>TFTP</acronym> and
	    <acronym>NFS</acronym> is a compile time option in several places.
	    A common source of error is to specify filenames for the wrong
	    protocol: <acronym>TFTP</acronym> typically transfers all files from
	    a single directory on the server, and would expect filenames
	    relative to this directory.  <acronym>NFS</acronym> needs absolute
	    file paths.</para>
	</listitem>

	<listitem>
	  <para>The possible intermediate bootstrap programs and the kernel
	    need to be initialized and executed.  There are several important
	    variations in this area:</para>

	  <itemizedlist>
	    <listitem>
	      <para><acronym>PXE</acronym> will load &man.pxeboot.8;, which is
		a modified version of the &os; third stage loader.  The
		&man.loader.8; will obtain most parameters necessary to system
		startup, and leave them in the kernel environment before
		transferring control.  It is possible to use a
		<filename>GENERIC</filename> kernel in this case.</para>
	    </listitem>

	    <listitem>
	      <para><application>etherboot</application>, will directly
		load the kernel, with less preparation.  You will need to
		build a kernel with specific options.</para>
	    </listitem>
	  </itemizedlist>

	  <para><acronym>PXE</acronym> and <application>etherboot</application>
	    work equally well with 4.X systems.  Because 5.X kernels
	    normally let the &man.loader.8; do more work for them,
	    <acronym>PXE</acronym> is preferred for 5.X systems.</para>

	  <para>If your <acronym>BIOS</acronym> and network cards support
	    <acronym>PXE</acronym>, you should probably use it.  However,
	    it is still possible to start a 5.X system with
	    <application>etherboot</application>.</para>
	</listitem>

	<listitem>
	  <para>Finally, the machine needs to access its filesystems.
	    <acronym>NFS</acronym> is used in all cases.</para>
	</listitem>
      </itemizedlist>

      <para>See also &man.diskless.8; manual page.</para>
    </sect2>

    <sect2>
      <title>Setup Instructions</title>

      <sect3>
	  <title>Configuration Using <application>ISC DHCP</application></title>
	  <indexterm>
	    <primary>DHCP</primary>
	    <secondary>diskless operation</secondary>
	  </indexterm>

	  <para>The <application>ISC DHCP</application> server can answer
	    both BOOTP and <acronym>DHCP</acronym> requests.</para>

	  <para>As of release 4.9, <application>ISC DHCP
  	    3.0</application> is not part of the base
	    system.  You will first need to install the
	    <filename role="package">net/isc-dhcp3-server</filename> port or the
	    corresponding package.  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, where host <hostid>margaux</hostid>
	    uses <application>etherboot</application> and host
	    <hostid>corbieres</hostid> uses <acronym>PXE</acronym>:</para>

          <programlisting>
default-lease-time 600;
max-lease-time 7200;
authoritative;

option domain-name "example.com";
option domain-name-servers 192.168.4.1;
option routers 192.168.4.1;

subnet 192.168.4.0 netmask 255.255.255.0 {
  use-host-decl-names on; <co id="co-dhcp-host-name">
  option subnet-mask 255.255.255.0;
  option broadcast-address 192.168.4.255;

  host margaux {
    hardware ethernet 01:23:45:67:89:ab;
    fixed-address margaux.example.com;
    next-server 192.168.4.4; <co id="co-dhcp-next-server">
    filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename">
    option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path">
  }
  host corbieres {
    hardware ethernet 00:02:b3:27:62:df;
    fixed-address corbieres.example.com;
    next-server 192.168.4.4;
    filename "pxeboot";
    option root-path "192.168.4.4:/data/misc/diskless";
  }
}
          </programlisting>

	  <calloutlist>
	    <callout arearefs="co-dhcp-host-name"><para>This option tells
		<application>dhcpd</application> to send the value in the
		<literal>host</literal> declarations as the hostname for the
		diskless host.  An alternate way would be to add an
		<literal>option host-name
		  <replaceable>margaux</replaceable></literal> inside the
		host declarations.</para>
	    </callout>

	    <callout arearefs="co-dhcp-next-server"><para>The
		<literal>next-server</literal> directive designates
		the <acronym>TFTP</acronym> or <acronym>NFS</acronym> server to
		use for loading loader or kernel file (the default is to use
		the same host as the
		<acronym>DHCP</acronym> server).</para>
	    </callout>

	    <callout arearefs="co-dhcp-filename"><para>The
		<literal>filename</literal> directive defines the file that
		<application>etherboot</application> or <acronym>PXE</acronym>
		will load for the next execution step.  It must be specified
		according to the transfer method used.
		<application>etherboot</application> can be compiled to use
		<acronym>NFS</acronym> or <acronym>TFTP</acronym>.  The &os;
		port configures <acronym>NFS</acronym> by default.
		<acronym>PXE</acronym> uses <acronym>TFTP</acronym>, which is
		why a relative filename is used here (this may depend on the
		<acronym>TFTP</acronym> server configuration, but would be
		fairly typical).  Also, <acronym>PXE</acronym> loads
		<filename>pxeboot</filename>, not the kernel.  There are other
		interesting possibilities, like loading
		<filename>pxeboot</filename> from a &os; CD-ROM
		<filename role="directory">/boot</filename> directory (as
		&man.pxeboot.8; can load a <filename>GENERIC</filename> kernel,
		this makes it possible to use <acronym>PXE</acronym> to boot
		from a remote CD-ROM).</para>
	    </callout>

	    <callout arearefs="co-dhcp-root-path"><para>The
		<literal>root-path</literal> option defines the path to
		the root filesystem, in usual <acronym>NFS</acronym> notation.
		When using <acronym>PXE</acronym>, it is possible to leave off
		the host's IP as long as you do not enable the kernel option
		BOOTP.  The <acronym>NFS</acronym> server will then be
		the same as the <acronym>TFTP</acronym> one.</para>
	    </callout>
	  </calloutlist>

      </sect3>
      <sect3>
	  <title>Configuration Using BOOTP</title>
	  <indexterm>
	    <primary>BOOTP</primary>
	    <secondary>diskless operation</secondary>
	  </indexterm>

	  <para>Here follows an equivalent <application>bootpd</application>
	    configuration (reduced to one client).  This would be found in
	    <filename>/etc/bootptab</filename>.</para>

	  <para>Please note that <application>etherboot</application>
	    must be compiled with the non-default option
	    <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP,
	    and that <acronym>PXE</acronym> <emphasis>needs</emphasis> <acronym>DHCP</acronym>.  The only
	    obvious advantage of <application>bootpd</application> is
	    that it exists in the base system.</para>

          <programlisting>
.def100:\
  :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
  :sm=255.255.255.0:\
  :ds=192.168.4.1:\
  :gw=192.168.4.1:\
  :hd="/tftpboot":\
  :bf="/kernel.diskless":\
  :rp="192.168.4.4:/data/misc/diskless":

margaux:ha=0123456789ab:tc=.def100
          </programlisting>
      </sect3>

      <sect3>
	<title>Preparing a Boot Program with
	  <application>Etherboot</application></title>

	<indexterm>
	  <primary>Etherboot</primary>
	</indexterm>

	<para><ulink url="http://etherboot.sourceforge.net">Etherboot's Web
	  site</ulink> contains
	  <ulink url="http://etherboot.sourceforge.net/doc/html/userman/t1.html">
	  extensive documentation</ulink> mainly intended for Linux
	  systems, but nonetheless containing useful information.  The
	  following will just outline how you would use
	  <application>etherboot</application> on a FreeBSD
	  system.</para>

	<para>You must first install the <filename
	  role="package">net/etherboot</filename> package or port.
	  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>You can change the <application>etherboot</application>
	  configuration (i.e. to use <acronym>TFTP</acronym> instead of
	  <acronym>NFS</acronym>) by editing the <filename>Config</filename>
	  file in the <application>etherboot</application> source
	  directory.</para>

	<para>For our setup, we shall use a boot floppy.  For other methods
	  (PROM, or &ms-dos; program), please refer to the
	  <application>etherboot</application> documentation.</para>

	<para>To make a boot floppy, insert a floppy in the drive on the
	  machine where you installed <application>etherboot</application>,
	  then change your current directory to the <filename>src</filename>
	  directory in the <application>etherboot</application> tree and
	  type:</para>

	<screen>
&prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput>
	</screen>

	<para><replaceable>devicetype</replaceable> depends on the type of
	  the Ethernet card in the diskless workstation.  Refer to the
	  <filename>NIC</filename> file in the same directory to determine the
	  right <replaceable>devicetype</replaceable>.</para>

      </sect3>

      <sect3>
	<title>Booting with <acronym>PXE</acronym></title>

	<para>By default, the &man.pxeboot.8; loader loads the kernel via
	  <acronym>NFS</acronym>.  It can be compiled to use
	  <acronym>TFTP</acronym> instead by specifying the
	  <literal>LOADER_TFTP_SUPPORT</literal> option in
	  <filename>/etc/make.conf</filename>.  See the comments in
	  <filename>/etc/defaults/make.conf</filename> (or
	  <filename>/usr/share/examples/etc/make.conf</filename> for 5.X
	  systems) for instructions.</para>

	<para>There are two other undocumented <filename>make.conf</filename>
	  options which may be useful for setting up a serial console diskless
	  machine: <literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and
	  <literal>BOOT_PXELDR_ALWAYS_SERIAL</literal> (the latter only exists
	  on &os;&nbsp;5.X).</para>

	<para>To use <acronym>PXE</acronym> when the machine starts, you will
	  usually need to select the <literal>Boot from network</literal>
	  option in your <acronym>BIOS</acronym> setup, or type a function key
	  during the PC initialization.</para>
      </sect3>

      <sect3>
	<title>Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers</title>

	<indexterm>
	  <primary>TFTP</primary>
	  <secondary>diskless operation</secondary>
	</indexterm>
	<indexterm>
	  <primary>NFS</primary>
	  <secondary>diskless operation</secondary>
	</indexterm>

	<para>If you are using <acronym>PXE</acronym> or
	  <application>etherboot</application> configured to use
	  <acronym>TFTP</acronym>, you need to enable
	  <application>tftpd</application> on the file server:</para>
        <procedure>
          <step>
            <para>Create a directory from which <application>tftpd</application>
            will serve the files, e.g. <filename>/tftpboot</filename>.</para>
          </step>

          <step>
            <para>Add this line to your
	      <filename>/etc/inetd.conf</filename>:</para>

	    <programlisting>tftp	dgram	udp	wait	root	/usr/libexec/tftpd	tftpd -l -s /tftpboot</programlisting>

	    <note><para>It appears that at least some <acronym>PXE</acronym> versions want
		the <acronym>TCP</acronym> version of <acronym>TFTP</acronym>.  In this case, add a second line,
		replacing <literal>dgram udp</literal> with <literal>stream
		tcp</literal>.</para>
	    </note>
          </step>
	  <step>
	    <para>Tell <application>inetd</application> to reread its configuration
	      file:</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>In all cases, you also need to enable <acronym>NFS</acronym> and export the
	  appropriate filesystem on the <acronym>NFS</acronym> server.</para>

        <procedure>
          <step>
            <para>Add this to <filename>/etc/rc.conf</filename>:</para>
	    <programlisting>nfs_server_enable="YES"</programlisting>
          </step>

          <step>
            <para>Export the 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 corbieres</replaceable>
	      with the names of the diskless workstations):</para>

	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
          </step>
	  <step>
	    <para>Tell <application>mountd</application> to reread its configuration
	      file.  If you actually needed to enable <acronym>NFS</acronym> in
	      <filename>/etc/rc.conf</filename>
	      at the first step, you probably want to reboot instead.</para>
	    <screen>&prompt.root; <userinput>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>If using <application>etherboot</application>, you need to
	  create a kernel configuration file for the diskless client
	  with the following options (in addition to the usual ones):</para>

	<programlisting>
options     BOOTP          # Use BOOTP to obtain IP address/hostname
options     BOOTP_NFSROOT  # NFS mount root filesystem using BOOTP info
	</programlisting>

	<para>You may also want to use <literal>BOOTP_NFSV3</literal>,
	  <literal>BOOT_COMPAT</literal> and <literal>BOOTP_WIRED_TO</literal>
	  (refer to <filename>LINT</filename> in 4.X or
	  <filename>NOTES</filename> on 5.X).</para>

	<para>These option names are historical and slightly misleading as
	  they actually enable indifferent use of <acronym>DHCP</acronym> and
	  BOOTP inside the kernel (it is also possible to force strict BOOTP
	  or <acronym>DHCP</acronym> use).</para>

	<para>Build the kernel (see <xref linkend="kernelconfig">),
	  and copy it to the place specified
	  in <filename>dhcpd.conf</filename>.</para>

	<note>
	  <para>When using <acronym>PXE</acronym>, building a kernel with the
	  above options is not strictly necessary (though suggested).
	  Enabling them will cause more <acronym>DHCP</acronym> requests to be
	  issued during kernel startup, with a small risk of inconsistency
	  between the new values and those retrieved by &man.pxeboot.8; in some
	  special cases.  The advantage of using them is that the host name
	  will be set as a side effect.  Otherwise you will need to set the
	  host name by another method, for example in a client-specific
	  <filename>rc.conf</filename> file.</para>
	</note>

	<note>
	  <para>In order to be loadable with
	    <application>etherboot</application>, a 5.X kernel needs to have
	    the device hints compiled in.  You would typically set the
	    following option in the configuration file (see the
	    <filename>NOTES</filename> configuration comments file):</para>

	  <programlisting>hints		"GENERIC.hints"</programlisting>
	</note>

      </sect3>

      <sect3>
	  <title>Preparing the Root Filesystem</title>

	<indexterm>
	  <primary>root file system</primary>
	  <secondary>diskless operation</secondary>
	</indexterm>

	<para>You need to create a root filesystem for the diskless
	  workstations, in the location listed as
	  <literal>root-path</literal> in
	  <filename>dhcpd.conf</filename>.  The following sections describe
	  two ways to do it.</para>

	<sect4>
	  <title>Using the <filename>clone_root</filename> Script</title>

	<para>This is the quickest way to create a root filesystem, but
	  currently it is only supported on &os;&nbsp;4.X.  This shell script
	  is located at
	  <filename>/usr/share/examples/diskless/clone_root</filename>
	  and needs customization, at least to adjust
	  the place where the filesystem will be created (the
	  <literal>DEST</literal> variable).</para>

	<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
	    the system startup scripts in
	    <filename role="directory">/etc</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>
	</sect4>

	<sect4>
	  <title>Using the Standard <command>make world</command>
	    Procedure</title>

	  <para>This method can be applied to either &os;&nbsp;4.X or 5.X and
	    will install a complete virgin system (not only the root filesystem)
	    into <envar>DESTDIR</envar>.
	    All you have to do is simply execute the following script:</para>

	  <programlisting>#!/bin/sh
export DESTDIR=/data/misc/diskless
mkdir -p ${DESTDIR}
cd /usr/src; make world && make kernel
cd /usr/src/etc; make distribution</programlisting>

	  <para>Once done, you may need to customize your
	    <filename>/etc/rc.conf</filename> and
	    <filename>/etc/fstab</filename> placed into
	    <envar>DESTDIR</envar> according to your needs.</para>
	</sect4>
      </sect3>

      <sect3>
	<title>Configuring Swap</title>

	<para>If needed, a swap file located on the server can be
	  accessed via <acronym>NFS</acronym>.  One of the methods commonly
	  used to do this has been discontinued in release 5.X.</para>

	<sect4>
	  <title><acronym>NFS</acronym> Swap with &os;&nbsp;4.X</title>

	  <para>The swap file location and size can be specified with
	    BOOTP/<acronym>DHCP</acronym> &os;-specific options 128 and 129.
	    Examples of configuration files for
	    <application>ISC DHCP 3.0</application> or
	    <application>bootpd</application> follow:</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><literal>swap-path</literal> is the path to a directory
	      where swap files will be located.  Each file will be named
	      <filename>swap.<replaceable>client-ip</replaceable></filename>.</para>

	    <para>Older versions of <application>dhcpd</application> used a syntax of
	      <literal>option option-128 "...</literal>, which is no
	      longer supported.</para>
	    <para><filename>/etc/bootptab</filename> would use the
	      following syntax instead:</para>

	    <programlisting>T128="192.168.4.4:/netswapvolume/netswap":T129=0000fa00</programlisting>

	    <note><para>In <filename>/etc/bootptab</filename>, the swap
	      size must be expressed in hexadecimal format.</para></note>
	  </step>

	  <step>
	    <para>On the <acronym>NFS</acronym> 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 <acronym>NFS</acronym> swap file server, add the following line to
	    <filename>/etc/exports</filename>:</para>
	    <programlisting>
<replaceable>/netswapvolume</replaceable>  -maproot=0:10 -alldirs <replaceable>margaux corbieres</replaceable>
	    </programlisting>
	    <para>Then tell <application>mountd</application> to reread the
		exports file, as above.</para>
	  </step>
	</procedure>
	</sect4>

	<sect4>
	  <title><acronym>NFS</acronym> Swap with &os&nbsp;5.X</title>

	  <para>The kernel does not support enabling <acronym>NFS</acronym>
	    swap at boot time.  Swap must be enabled by the startup scripts,
	    by mounting a writeable file system and creating and enabling a
	    swap file.  To create a swap file of appropriate size, you can do
	    like this:</para>

	  <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen>

	  <para>To enable it you have to add the following line to your
	    <filename>rc.conf</filename>:</para>

	  <programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting>
        </sect4>
      </sect3>

      <sect3>
	<title>Miscellaneous Issues</title>


	<sect4>
	  <title>Running with a Read-only <filename>/usr</filename></title>

	  <indexterm>
	    <primary>diskless operation</primary>
	    <secondary>/usr read-only</secondary>
	  </indexterm>

	    <para>If the diskless workstation is configured to run X, you
	    will have to adjust the 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 pointless).</para>

	</sect4>

      </sect3>

    </sect2>
  </sect1>

  <sect1 id="network-isdn">
    <title>ISDN</title>

    <indexterm>
      <primary>ISDN</primary>
    </indexterm>

    <para>A good resource for information on ISDN technology and hardware is
      <ulink url="http://www.alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN
	Page</ulink>.</para>

    <para>A quick simple road map to ISDN follows:</para>

    <itemizedlist>
      <listitem>
        <para>If you live in Europe you might want to investigate the ISDN card
          section.</para>
      </listitem>

      <listitem>
	<para>If you are planning to use ISDN primarily to connect to the
	  Internet with an Internet Provider on a dial-up non-dedicated basis,
	  you might look into Terminal Adapters.  This will give you the
	  most flexibility, with the fewest problems, if you change
	  providers.</para>
      </listitem>

      <listitem>
	<para>If you are connecting two LANs together, or connecting to the
	  Internet with a dedicated ISDN connection, you might consider
	  the stand alone router/bridge option.</para>
      </listitem>
    </itemizedlist>

    <para>Cost is a significant factor in determining what solution you will
      choose.  The following options are listed from least expensive to most
      expensive.</para>

    <sect2 id="network-isdn-cards">
      <sect2info>
        <authorgroup>
          <author>
            <firstname>Hellmuth</firstname>
            <surname>Michaelis</surname>
            <contrib>Contributed by </contrib>
          </author>
        </authorgroup>
      </sect2info>
      <title>ISDN Cards</title>

      <indexterm>
        <primary>ISDN</primary>
        <secondary>cards</secondary>
      </indexterm>

      <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
	(or Euro-ISDN) standard using passive cards.  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>The <application>isdn4bsd</application> software allows you to connect
	to other ISDN routers using either IP over raw HDLC or by using
	synchronous PPP: either by using kernel PPP with <literal>isppp</literal>, a
	modified &man.sppp.4; driver, or by using userland &man.ppp.8;.  By using
	userland &man.ppp.8;, channel bonding of two or more ISDN
	B-channels is possible.  A telephone answering machine
	application is also available as well as many utilities such as
	a software 300 Baud modem.</para>

      <para>Some growing number of PC ISDN cards are supported under
	FreeBSD and the reports show that it is successfully used all
	over Europe and in many other parts of the world.</para>

      <para>The passive ISDN cards supported are mostly the ones with
	the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
	but also ISDN cards with chips from Cologne Chip (ISA bus only),
	PCI cards with Winbond W6692 chips, some cards with the
	Tiger300/320/ISAC chipset combinations and some vendor specific
	chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
	AVM Fritz!Card PnP.</para>

      <para>Currently the active supported ISDN cards are the AVM B1
	(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>

      <para>For documentation on <application>isdn4bsd</application>,
	have a look at <filename>/usr/share/examples/isdn/</filename>
	directory on your FreeBSD system or at the <ulink
	  url="http://www.freebsd-support.de/i4b/">homepage of
	  isdn4bsd</ulink> which also has pointers to hints, erratas and
	much more documentation such as the <ulink
	  url="http://people.FreeBSD.org/~hm/">isdn4bsd
	  handbook</ulink>.</para>

      <para>In case you are interested in adding support for a
	different ISDN protocol, a currently unsupported ISDN PC card or
	otherwise enhancing <application>isdn4bsd</application>, please
	get in touch with &a.hm;.</para>

      <para>For questions regarding the installation, configuration
	and troubleshooting <application>isdn4bsd</application>, a
	&a.isdn.name; mailing list is available.</para>
    </sect2>

    <sect2>
      <title>ISDN Terminal Adapters</title>

      <para>Terminal adapters (TA), are to ISDN what modems are to regular
	phone lines.</para>
      <indexterm><primary>modem</primary></indexterm>
      <para>Most TA's use the standard Hayes modem AT command set, and can be
	used as a drop in replacement for a modem.</para>

      <para>A TA will operate basically the same as a modem except connection
	and throughput speeds will be much faster than your old modem.  You
	will need to configure <link linkend="ppp">PPP</link> exactly the same
	as for a modem setup.  Make sure you set your serial speed as high as
	possible.</para>
      <indexterm><primary>PPP</primary></indexterm>
      <para>The main advantage of using a TA to connect to an Internet
	Provider is that you can do Dynamic PPP.  As IP address space becomes
	more and more scarce, most providers are not willing to provide you
	with a static IP anymore.  Most stand-alone routers are not able to
	accommodate dynamic IP allocation.</para>

      <para>TA's completely rely on the PPP daemon that you are running for
	their features and stability of connection.  This allows you to
	upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
	already have PPP set up.  However, at the same time any problems you
	experienced with the PPP program and are going to persist.</para>

      <para>If you want maximum stability, use the kernel <link
	  linkend="ppp">PPP</link> option, not the <link
	  linkend="userppp">userland PPP</link>.</para>

      <para>The following TA's are known to work with FreeBSD:</para>

      <itemizedlist>
	<listitem>
	  <para>Motorola BitSurfer and Bitsurfer Pro</para>
	</listitem>

	<listitem>
	  <para>Adtran</para>
	</listitem>
      </itemizedlist>

      <para>Most other TA's will probably work as well, TA vendors try to make
	sure their product can accept most of the standard modem AT command
	set.</para>

      <para>The real problem with external TA's is that, like modems,
	you need a good serial card in your computer.</para>

      <para>You should read the <ulink
	url="../../articles/serial-uart/index.html">FreeBSD Serial
	Hardware</ulink> tutorial for a detailed understanding of
	serial devices, and the differences between asynchronous and
	synchronous serial ports.</para>

      <para>A TA running off a standard PC serial port (asynchronous) limits
	you to 115.2&nbsp;Kbs, even though you have a 128&nbsp;Kbs connection.
	To fully utilize the 128&nbsp;Kbs that ISDN is capable of,
	you must move the TA to a synchronous serial card.</para>

      <para>Do not be fooled into buying an internal TA and thinking you have
	avoided the synchronous/asynchronous issue.  Internal TA's simply have
	a standard PC serial port chip built into them.  All this will do is
	save you having to buy another serial cable and find another empty
	electrical socket.</para>

      <para>A synchronous card with a TA is at least as fast as a stand-alone
	router, and with a simple 386 FreeBSD box driving it, probably more
	flexible.</para>

      <para>The choice of synchronous card/TA v.s. stand-alone router is largely a
	religious issue.  There has been some discussion of this in
	the mailing lists.  We suggest you search the <ulink
	url="../../../../search/index.html">archives</ulink> for
	the complete discussion.</para>
    </sect2>

    <sect2>
      <title>Stand-alone ISDN Bridges/Routers</title>
      <indexterm>
        <primary>ISDN</primary>
	<secondary>stand-alone bridges/routers</secondary>
      </indexterm>
      <para>ISDN bridges or routers are not at all specific to FreeBSD
	or any other operating system.  For a more complete
	description of routing and bridging technology, please refer
	to a networking reference book.</para>

      <para>In the context of this section, the terms router and bridge will
	be used interchangeably.</para>

      <para>As the cost of low end ISDN routers/bridges comes down, it
	will likely become a more and more popular choice.  An ISDN
	router is a small box that plugs directly into your local
	Ethernet network, and manages its own connection to the other
	bridge/router.  It has built in software to communicate via
	PPP and other popular protocols.</para>

      <para>A router will allow you much faster throughput than a
	standard TA, since it will be using a full synchronous ISDN
	connection.</para>

      <para>The main problem with ISDN routers and bridges is that
	interoperability between manufacturers can still be a problem.
	If you are planning to connect to an Internet provider, you
	should discuss your needs with them.</para>

      <para>If you are planning to connect two LAN segments together,
	such as your home LAN to the office LAN, this is the simplest
	lowest
	maintenance solution.  Since you are buying the equipment for
	both sides of the connection you can be assured that the link
	will work.</para>

      <para>For example to connect a home computer or branch office
	network to a head office network the following setup could be
	used:</para>

      <example>
	<title>Branch Office or Home Network</title>

	<indexterm><primary>10 base 2</primary></indexterm>
	<para>Network uses a bus based topology with 10 base 2
	  Ethernet (<quote>thinnet</quote>).  Connect router to network cable with
	  AUI/10BT transceiver, if necessary.</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="advanced-networking/isdn-bus">
          </imageobject>

	  <textobject>
	    <literallayout class="monospaced">---Sun workstation
|
---FreeBSD box
|
---Windows 95
|
Stand-alone router
   |
ISDN BRI line</literallayout>
          </textobject>

	  <textobject>
	    <phrase>10 Base 2 Ethernet</phrase>
	  </textobject>
	</mediaobject>

	<para>If your home/branch office is only one computer you can use a
	  twisted pair crossover cable to connect to the stand-alone router
	  directly.</para>
      </example>

      <example>
	<title>Head Office or Other LAN</title>

	<indexterm><primary>10 base T</primary></indexterm>
	<para>Network uses a star topology with 10 base T Ethernet
  	  (<quote>Twisted Pair</quote>).</para>

        <mediaobject>
          <imageobject>
            <imagedata fileref="advanced-networking/isdn-twisted-pair">
          </imageobject>

	  <textobject>
	    <literallayout class="monospaced">    -------Novell Server
    | H |
    |   ---Sun
    |   |
    | U ---FreeBSD
    |   |
    |   ---Windows 95
    | B |
    |___---Stand-alone router
                |
        ISDN BRI line</literallayout>
	  </textobject>

	  <textobject>
	    <phrase>ISDN Network Diagram</phrase>
	  </textobject>
	</mediaobject>
      </example>

      <para>One large advantage of most routers/bridges is that they allow you
	to have 2 <emphasis>separate independent</emphasis> PPP connections to
	2 separate sites at the <emphasis>same</emphasis> time.  This is not
	supported on most TA's, except for specific (usually expensive) models
	that
	have two serial ports.  Do not confuse this with channel bonding, MPP,
	etc.</para>

      <para>This can be a very useful feature if, for example, you
	have an dedicated ISDN connection at your office and would
	like to tap into it, but do not want to get another ISDN line
	at work.  A router at the office location can manage a
	dedicated B channel connection (64&nbsp;Kbps) to the Internet
	and use the other B channel for a separate data connection.
	The second B channel can be used for dial-in, dial-out or
	dynamically bonding (MPP, etc.) with the first B channel for
	more bandwidth.</para>

      <indexterm><primary>IPX/SPX</primary></indexterm>
      <para>An Ethernet bridge will also allow you to transmit more than just
	IP traffic.  You can also send IPX/SPX or whatever other protocols you
	use.</para>
    </sect2>
  </sect1>

  <sect1 id="network-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; like 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 the &windowsnt; domain system; although the
        internal implementation of the two are not at all similar,
        the basic functionality can be compared.</para>
    </sect2>

    <sect2>
      <title>Terms/Processes You Should Know</title>

      <para>There are several terms and several important user processes
        that you will come across when
        attempting to implement NIS on FreeBSD, whether you are trying to
        create an NIS server or act as an NIS client:</para>

      <indexterm>
	<primary><application>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 &windowsnt; 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>
      <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
      on the master -->

    </sect2>

    <sect2>
      <title>How Does It Work?</title>

      <para>There are three types of hosts in an NIS environment: master
	servers, slave servers, and clients.  Servers act as a central
	repository for host configuration information.  Master servers
	hold the authoritative copy of this information, while slave
	servers mirror this information for redundancy.  Clients rely on
	the servers to provide this information to them.</para>

      <para>Information in many files can be shared in this manner.  The
	<filename>master.passwd</filename>, <filename>group</filename>,
	and <filename>hosts</filename> files are commonly shared via NIS.
	Whenever a process on a client needs information that would
	normally be found in these files locally, it makes a query to the
	NIS server that it is bound to instead.</para>

      <sect3>
        <title>Machine Types</title>

        <itemizedlist>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>master server</secondary>
	  </indexterm>
          <listitem>
            <para>A <emphasis>NIS master server</emphasis>.
              This server, analogous to a &windowsnt;
              primary domain controller, maintains the files used by all
              of the NIS clients.  The <filename>passwd</filename>,
              <filename>group</filename>, and other various files used by the
              NIS clients live on the master server.</para>

            <note><para>It is possible for one machine to be an NIS
              master server for more than one NIS domain.  However, this will
              not be covered in this introduction, which assumes a relatively
              small-scale NIS environment.</para></note>
          </listitem>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>slave server</secondary>
	  </indexterm>
          <listitem>
            <para><emphasis>NIS slave servers</emphasis>.
              Similar to the &windowsnt; backup domain
              controllers, NIS slave servers maintain copies of the NIS
              master's data files.  NIS slave servers provide the redundancy,
              which is needed in important environments.  They also help
              to balance the load of the master server:  NIS Clients always
              attach to the NIS server whose response they get first, and
              this includes slave-server-replies.</para>
          </listitem>
	  <indexterm>
	    <primary>NIS</primary>
	    <secondary>client</secondary>
	  </indexterm>
          <listitem>
            <para><emphasis>NIS clients</emphasis>.  NIS clients, like most
              &windowsnt; workstations, authenticate against the NIS server (or the &windowsnt;
              domain controller in the &windowsnt; 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>
              <!--  Names taken from "Good Omens" by Neil Gaiman and Terry
                    Pratchett.  Many thanks for a brilliant book.  -->
              <entry>war, death, famine, pollution</entry>
              <entry>Your most important servers.  Only the IT
                employees are allowed to log onto these
                machines.</entry>
            </row>
            <row>
              <!-- gluttony was omitted because it was too fat -->
              <entry>pride, greed, envy, wrath, lust, sloth</entry>
              <entry>Less important servers.  All members of the IT
                department are allowed to login onto these machines.</entry>
            </row>

            <row>
              <entry>one, two, three, four, ...</entry>
              <entry>Ordinary workstations.  Only the
                <emphasis>real</emphasis> employees are allowed to use
                these machines.</entry>
            </row>

            <row>
              <entry>trashcan</entry>
              <entry>A very old machine without any critical data.
                Even the intern is allowed to use this box.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>If you tried to implement these restrictions by separately
        blocking each user, you would have to add one
        -<replaceable>user</replaceable> line to each system's
	<filename>passwd</filename>
        for each user who is not allowed to login onto that system.
        If you forget just one entry, you could be in trouble.  It may
        be feasible to do this correctly during the initial setup,
        however you <emphasis>will</emphasis> eventually forget to add
        the lines for new users during day-to-day operations.  After
        all, Murphy was an optimist.</para>

      <para>Handling this situation with netgroups offers several
        advantages.  Each user need not be handled separately;
        you assign a user to one or more netgroups and allow or forbid
        logins for all members of the netgroup.  If you add a new
        machine, you will only have to define login restrictions for
        netgroups.  If a new user is added, you will only have to add
        the user to one or more netgroups.  Those changes are
        independent of each other; no more <quote>for each combination
        of user and machine do...</quote> If your NIS setup is planned
        carefully, you will only have to modify exactly one central
        configuration file to grant or deny access to machines.</para>

      <para>The first step is the initialization of the NIS map
        netgroup.  FreeBSD's &man.ypinit.8; does not create this map by
        default, but its NIS implementation will support it once it has
        been created.  To create an empty map, simply type</para>

      <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen>

      <para>and start adding content.  For our example, we need at
         least four netgroups: IT employees, IT apprentices, normal
         employees and interns.</para>

      <programlisting>IT_EMP  (,alpha,test-domain)    (,beta,test-domain)
IT_APP  (,charlie,test-domain)  (,delta,test-domain)
USERS   (,echo,test-domain)     (,foxtrott,test-domain) \
        (,golf,test-domain)
INTERNS (,able,test-domain)     (,baker,test-domain)</programlisting>

      <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
        are the names of the netgroups.  Each bracketed group adds
        one or more user accounts to it.  The three fields inside a
        group are:</para>

      <orderedlist>
        <listitem>
          <para>The name of the host(s) where the following items are
            valid.  If you do not specify a hostname, the entry is
            valid on all hosts.  If you do specify a hostname, you
            will enter a realm of darkness, horror and utter confusion.</para>
        </listitem>

        <listitem>
          <para>The name of the account that belongs to this
            netgroup.</para>
        </listitem>

        <listitem>
          <para>The NIS domain for the account.  You can import
            accounts from other NIS domains into your netgroup if you
            are one of the unlucky fellows with more than one NIS
            domain.</para>
        </listitem>
      </orderedlist>

      <para>Each of these fields can contain wildcards.  See
        &man.netgroup.5; for details.</para>

      <note>
        <indexterm><primary>netgroups</primary></indexterm>
        <para>Netgroup names longer than 8 characters should not be
          used, especially if you have machines running other
          operating systems within your NIS domain.  The names are
          case sensitive; using capital letters for your netgroup
          names is an easy way to distinguish between user, machine
          and netgroup names.</para>

        <para>Some NIS clients (other than FreeBSD) cannot handle
          netgroups with a large number of entries.  For example, some
          older versions of &sunos; start to cause trouble if a netgroup
          contains more than 15 <emphasis>entries</emphasis>.  You can
          circumvent this limit by creating several sub-netgroups with
          15 users or less and a real netgroup that consists of the
          sub-netgroups:</para>

        <programlisting>BIGGRP1  (,joe1,domain)  (,joe2,domain)  (,joe3,domain) [...]
BIGGRP2  (,joe16,domain)  (,joe17,domain) [...]
BIGGRP3  (,joe31,domain)  (,joe32,domain)
BIGGROUP  BIGGRP1 BIGGRP2 BIGGRP3</programlisting>

        <para>You can repeat this process if you need more than 225
          users within a single netgroup.</para>
      </note>

      <para>Activating and distributing your new NIS map is
        easy:</para>

      <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
ellington&prompt.root; <userinput>make</userinput></screen>

      <para>This will generate the three NIS maps
        <filename>netgroup</filename>,
        <filename>netgroup.byhost</filename> and
        <filename>netgroup.byuser</filename>.  Use &man.ypcat.1; to
        check if your new NIS maps are available:</para>

      <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen>

      <para>The output of the first command should resemble the
        contents of <filename>/var/yp/netgroup</filename>.  The second
        command will not produce output if you have not specified
        host-specific netgroups.  The third command can be used to
        get the list of netgroups for a user.</para>

      <para>The client setup is quite simple.  To configure the server
        <replaceable>war</replaceable>, you only have to start
        &man.vipw.8; and replace the line</para>

      <programlisting>+:::::::::</programlisting>

      <para>with</para>

      <programlisting>+@IT_EMP:::::::::</programlisting>

      <para>Now, only the data for the users defined in the netgroup
        <replaceable>IT_EMP</replaceable> is imported into
        <replaceable>war</replaceable>'s password database and only
        these users are allowed to login.</para>

      <para>Unfortunately, this limitation also applies to the ~
	function of the shell and all routines converting between user
	names and numerical user IDs.  In other words,
	<command>cd ~<replaceable>user</replaceable></command> will not work,
	<command>ls -l</command> will show the numerical id instead of
	the username and <command>find . -user joe -print</command> will
	fail with <errorname>No such user</errorname>.  To fix this, you will
	have to import all user entries <emphasis>without allowing them
	to login onto your servers</emphasis>.</para>

      <para>This can be achieved by adding another line to
        <filename>/etc/master.passwd</filename>.  This line should
        contain:</para>

      <para><literal>+:::::::::/sbin/nologin</literal>, meaning
        <quote>Import all entries but replace the shell with
        <filename>/sbin/nologin</filename> in the imported
        entries</quote>.  You can replace any field
        in the passwd entry by placing a default value in your
        <filename>/etc/master.passwd</filename>.</para>

      <!-- Been there, done that, got the scars to prove it - ue -->
      <warning>
        <para>Make sure that the line
        <literal>+:::::::::/sbin/nologin</literal> is placed after
        <literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
        accounts imported from NIS will have /sbin/nologin as their
        login shell.</para>
      </warning>

      <para>After this change, you will only have to change one NIS
        map if a new employee joins the IT department.  You could use
        a similar approach for the less important servers by replacing
        the old <literal>+:::::::::</literal> in their local version
        of <filename>/etc/master.passwd</filename> with something like
        this:</para>

      <programlisting>+@IT_EMP:::::::::
+@IT_APP:::::::::
+:::::::::/sbin/nologin</programlisting>

      <para>The corresponding lines for the normal workstations
        could be:</para>

      <programlisting>+@IT_EMP:::::::::
+@USERS:::::::::
+:::::::::/sbin/nologin</programlisting>

      <para>And everything would be fine until there is a policy
        change a few weeks later:  The IT department starts hiring
        interns.  The IT interns are allowed to use the normal
        workstations and the less important servers; and the IT
        apprentices are allowed to login onto the main servers.  You
        add a new netgroup IT_INTERN, add the new IT interns to this
        netgroup and start to change the config on each and every
        machine...  As the old saying goes:  <quote>Errors in
        centralized planning lead to global mess</quote>.</para>

      <para>NIS' ability to create netgroups from other netgroups can
        be used to prevent situations like these.  One possibility
        is the creation of role-based netgroups.  For example, you
        could create a netgroup called
        <replaceable>BIGSRV</replaceable> to define the login
        restrictions for the important servers, another netgroup
        called <replaceable>SMALLSRV</replaceable> for the less
        important servers and a third netgroup called
        <replaceable>USERBOX</replaceable> for the normal
        workstations.  Each of these netgroups contains the netgroups
        that are allowed to login onto these machines.  The new
        entries for your NIS map netgroup should look like this:</para>

      <programlisting>BIGSRV    IT_EMP  IT_APP
SMALLSRV  IT_EMP  IT_APP  ITINTERN
USERBOX   IT_EMP  ITINTERN USERS</programlisting>

      <para>This method of defining login restrictions works
        reasonably well if you can define groups of machines with
        identical restrictions.  Unfortunately, this is the exception
        and not the rule.  Most of the time, you will need the ability
        to define login restrictions on a per-machine basis.</para>

      <para>Machine-specific netgroup definitions are the other
        possibility to deal with the policy change outlined above.  In
        this scenario, the <filename>/etc/master.passwd</filename> of
        each box contains two lines starting with <quote>+</quote>.
        The first of them adds a netgroup with the accounts allowed to
        login onto this machine, the second one adds all other
        accounts with <filename>/sbin/nologin</filename> as shell.  It
        is a good idea to use the ALL-CAPS version of the machine name
        as the name of the netgroup.  In other words, the lines should
        look like this:</para>

      <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
+:::::::::/sbin/nologin</programlisting>

      <para>Once you have completed this task for all your machines,
        you will not have to modify the local versions of
        <filename>/etc/master.passwd</filename> ever again.  All
        further changes can be handled by modifying the NIS map.  Here
        is an example of a possible netgroup map for this
        scenario with some additional goodies.</para>

      <programlisting># Define groups of users first
IT_EMP    (,alpha,test-domain)    (,beta,test-domain)
IT_APP    (,charlie,test-domain)  (,delta,test-domain)
DEPT1     (,echo,test-domain)     (,foxtrott,test-domain)
DEPT2     (,golf,test-domain)     (,hotel,test-domain)
DEPT3     (,india,test-domain)    (,juliet,test-domain)
ITINTERN  (,kilo,test-domain)     (,lima,test-domain)
D_INTERNS (,able,test-domain)     (,baker,test-domain)
#
# Now, define some groups based on roles
USERS     DEPT1   DEPT2     DEPT3
BIGSRV    IT_EMP  IT_APP
SMALLSRV  IT_EMP  IT_APP    ITINTERN
USERBOX   IT_EMP  ITINTERN  USERS
#
# And a groups for a special tasks
# Allow echo and golf to access our anti-virus-machine
SECURITY  IT_EMP  (,echo,test-domain)  (,golf,test-domain)
#
# machine-based netgroups
# Our main servers
WAR       BIGSRV
FAMINE    BIGSRV
# User india needs access to this server
POLLUTION  BIGSRV  (,india,test-domain)
#
# This one is really important and needs more access restrictions
DEATH     IT_EMP
#
# The anti-virus-machine mentioned above
ONE       SECURITY
#
# Restrict a machine to a single user
TWO       (,hotel,test-domain)
# [...more groups to follow]</programlisting>

      <para>If you are using some kind of database to manage your user
        accounts, you should be able to create the first part of the
        map with your database's report tools.  This way, new users
        will automatically have access to the boxes.</para>

      <para>One last word of caution: It may not always be advisable
        to use machine-based netgroups.  If you are deploying a couple of
        dozen or even hundreds of identical machines for student labs,
        you should use role-based netgroups instead of machine-based
        netgroups to keep the size of the NIS map within reasonable
        limits.</para>
    </sect2>

    <sect2>
      <title>Important Things to Remember</title>

      <para>There are still a couple of things that you will need to do
        differently now that you are in an NIS environment.</para>

      <itemizedlist>
        <listitem>
          <para>Every time you wish to add a user to the lab, you
            must add it to the master NIS server <emphasis>only</emphasis>,
            and <emphasis>you must remember to rebuild the NIS
            maps</emphasis>.  If you forget to do this, the new user will
            not be able to login anywhere except on the NIS master.
            For example, if we needed to add a new user
            <quote>jsmith</quote> to the lab, we would:</para>

          <screen>&prompt.root; <userinput>pw useradd jsmith</userinput>
&prompt.root; <userinput>cd /var/yp</userinput>
&prompt.root; <userinput>make test-domain</userinput></screen>

          <para>You could also run <command>adduser jsmith</command> instead
            of <command>pw useradd jsmith</command>.</para>
        </listitem>
        <listitem>
          <para><emphasis>Keep the administration accounts out of the NIS
            maps</emphasis>.  You do not want to be propagating administrative
            accounts and passwords to machines that will have users that
            should not have access to those accounts.</para>
        </listitem>
        <listitem>
          <para><emphasis>Keep the NIS master and slave
            secure, and minimize their downtime</emphasis>.
            If somebody either hacks or simply turns off
            these machines, they have effectively rendered many people without
            the ability to login to the lab.</para>

          <para>This is the chief weakness of any centralized administration
            system.  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-server</filename> port.  The
        &man.dhclient.8;, &man.dhcp-options.5;, and &man.dhclient.conf.5;
        manual pages, in addition to the references below, are useful
        resources.</para>
    </sect2>

    <sect2>
      <title>How It Works</title>
      <indexterm><primary>UDP</primary></indexterm>
      <para>When <command>dhclient</command>, the DHCP client, is
	executed on the client machine, it begins broadcasting
	requests for configuration information.  By default, these
	requests are on UDP port 68.  The server replies on UDP 67,
	giving the client an IP address and other relevant network
	information such as netmask, router, and DNS servers.  All of
	this information comes in the form of a DHCP
	<quote>lease</quote> and is only valid for a certain time
	(configured by the DHCP server maintainer).  In this manner,
	stale IP addresses for clients no longer connected to the
	network can be automatically reclaimed.</para>

      <para>DHCP clients can obtain a great deal of information from
        the server.  An exhaustive list may be found in
        &man.dhcp-options.5;.</para>
    </sect2>

    <sect2>
      <title>FreeBSD Integration</title>

      <para>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-server</filename> port in the ports
          collection.  This port contains the ISC DHCP server and
          documentation.</para>
    </sect2>

    <sect2>
      <title>Files</title>
      <indexterm>
        <primary>DHCP</primary>
        <secondary>configuration files</secondary>
      </indexterm>
      <itemizedlist>
        <listitem><para><filename>/etc/dhclient.conf</filename></para>
          <para><command>dhclient</command> requires a configuration file,
            <filename>/etc/dhclient.conf</filename>.  Typically the file
            contains only comments, the defaults being reasonably sane.  This
            configuration file is described by the &man.dhclient.conf.5;
            manual page.</para>
        </listitem>

        <listitem><para><filename>/sbin/dhclient</filename></para>
          <para><command>dhclient</command> is statically linked and
            resides in <filename>/sbin</filename>.  The &man.dhclient.8;
            manual page gives more information about
            <command>dhclient</command>.</para>
        </listitem>

        <listitem><para><filename>/sbin/dhclient-script</filename></para>
          <para><command>dhclient-script</command> is the FreeBSD-specific
            DHCP client configuration script.  It is described in
            &man.dhclient-script.8;, but should not need any user
            modification to function properly.</para>
        </listitem>

        <listitem><para><filename>/var/db/dhclient.leases</filename></para>
          <para>The DHCP client keeps a database of valid leases in this
            file, which is written as a log.  &man.dhclient.leases.5;
            gives a slightly longer description.</para>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Further Reading</title>

      <para>The DHCP protocol is fully described in
        <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
        An informational resource has also been set up at
        <ulink url="http://www.dhcp.org/">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-server</filename>
	    port to provide this service.  See <xref linkend="ports"> for
	    more information on using the ports collection.</para>
	</sect3>

	<sect3>
	  <title>DHCP Server Installation</title>
	  <indexterm>
	    <primary>DHCP</primary>
	    <secondary>installation</secondary>
	  </indexterm>
	  <para>In order to configure your FreeBSD system as a DHCP server,
	    you will need to ensure that the &man.bpf.4;
	    device is compiled into your kernel.  To do this, add
	    <literal>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-server</filename> port.
	    By default, this will be
	    <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and you
	    should copy this to
	    <filename>/usr/local/etc/dhcpd.conf</filename> before proceeding
	    to make changes.</para>
	</sect3>

	<sect3>
	  <title>Configuring the DHCP Server</title>
	  <indexterm>
	    <primary>DHCP</primary>
	    <secondary>dhcpd.conf</secondary>
	  </indexterm>
	  <para><filename>dhcpd.conf</filename> is
	    comprised of declarations regarding subnets and hosts, and is
	    perhaps most easily explained using an example :</para>

	  <programlisting>option domain-name "example.com";<co id="domain-name">
option domain-name-servers 192.168.4.100;<co id="domain-name-servers">
option subnet-mask 255.255.255.0;<co id="subnet-mask">

default-lease-time 3600;<co id="default-lease-time">
max-lease-time 86400;<co id="max-lease-time">
ddns-update-style none;<co id="ddns-update-style">

subnet 192.168.4.0 netmask 255.255.255.0 {
  range 192.168.4.129 192.168.4.254;<co id="range">
  option routers 192.168.4.1;<co id="routers">
}

host mailhost {
  hardware ethernet 02:03:04:05:06:07;<co id="hardware">
  fixed-address mailhost.example.com;<co id="fixed-address">
}</programlisting>

	  <calloutlist>
	    <callout arearefs="domain-name">
	      <para>This option specifies the domain that will be provided
		to clients as the default search domain.  See
		&man.resolv.conf.5; for more information on what this
		means.</para>
	    </callout>

	    <callout arearefs="domain-name-servers">
	      <para>This option specifies a comma separated list of DNS
		servers that the client should use.</para>
	    </callout>

	    <callout arearefs="subnet-mask">
	      <para>The netmask that will be provided to clients.</para>
	    </callout>

	    <callout arearefs="default-lease-time">
	      <para>A client may request a specific length of time that a
		lease will be valid.  Otherwise the server will assign
		a lease with this expiry value (in seconds).</para>
	    </callout>

	    <callout arearefs="max-lease-time">
	      <para>This is the maximum length of time that the server will
		lease for.  Should a client request a longer lease, a lease
		will be issued, although it will only be valid for
		<literal>max-lease-time</literal> seconds.</para>
	    </callout>

	    <callout arearefs="ddns-update-style">
	      <para>This option specifies whether the DHCP server should
		attempt to update DNS when a lease is accepted or released.
		In the ISC implementation, this option is
		<emphasis>required</emphasis>.</para>
	    </callout>

	    <callout arearefs="range">
	      <para>This denotes which IP addresses should be used in
		the pool reserved for allocating to clients.  IP
		addresses between, and including, the ones stated are
		handed out to clients.</para>
	    </callout>

	    <callout arearefs="routers">
	      <para>Declares the default gateway that will be provided to
		clients.</para>
	    </callout>

	    <callout arearefs="hardware">
	      <para>The hardware MAC address of a host (so that the DHCP server
		can recognize a host when it makes a request).</para>
	    </callout>

	    <callout arearefs="fixed-address">
	      <para>Specifies that the host should always be given the same
		IP address.  Note that 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
		&man.dhcpd.8; manual page installed with the
		port gives more information about
		<application>dhcpd</application>.</para>
	    </listitem>

	    <listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
	      <para><application>dhcpd</application> requires a configuration
		file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
		will start providing service to clients.  This file needs to
		contain all the information that should be provided to clients
		that are being serviced, along with information regarding the
		operation of the server.  This configuration file is described
		by the &man.dhcpd.conf.5; manual page installed
		by the port.</para>
	    </listitem>

	    <listitem><para><filename>/var/db/dhcpd.leases</filename></para>
	      <para>The DHCP server keeps a database of leases it has issued
		in this file, which is written as a log.  The manual page
		&man.dhcpd.leases.5;, installed by the port
		gives a slightly longer description.</para>
	    </listitem>

	    <listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
	      <para><application>dhcrelay</application> is used in advanced
		environments where one DHCP server forwards a request from a
		client to another DHCP server on a separate network.  If you
		require this functionality, then install the <filename
		role="package">net/isc-dhcp3-server</filename> port.  The
		&man.dhcrelay.8; manual page provided with the
		port contains more detail.</para>
	    </listitem>
	  </itemizedlist>
	</sect3>

      </sect2>

  </sect1>

  <sect1 id="network-dns">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Chern</firstname>
          <surname>Lee</surname>
          <contrib>Contributed by </contrib>
        </author>
      </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 in a particular zone
		file</entry>
	    </row>

	    <row>
	      <entry><application>named</application>, BIND, name server</entry>
	      <entry>Common names for the BIND name server package within
		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>The beginning of the Internet zone hierarchy.
		All zones fall under the root zone, similar to how
		all files in a file system fall under the root directory.</entry>
	    </row>

	    <row>
	      <entry>Zone</entry>
	      <entry>An individual domain, subdomain, or portion of the DNS administered by
		the same authority</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <indexterm>
	<primary>zones</primary>
	<secondary>examples</secondary>
      </indexterm>

      <para>Examples of zones:
      </para>
      <itemizedlist>
        <listitem>
          <para><hostid>.</hostid> is the root zone</para>
        </listitem>
        <listitem>
          <para><hostid>org.</hostid> is a zone under the root zone</para>
        </listitem>
        <listitem>
          <para><hostid>example.org</hostid> is a zone under the
          <hostid>org.</hostid> 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>

	<indexterm>
	  <primary>MX record</primary>
	</indexterm>

        <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>
<!-- I don't like this next bit -->
&prompt.root; <userinput>sh make-localhost && mv localhost.rev localhost-v6.rev master</userinput>
&prompt.root; <userinput>cat > master/named.localhost
$ORIGIN localhost.
$TTL 6h
@	IN	SOA	localhost. postmaster.localhost. (
			1	; serial
			3600	; refresh
			1800	; retry
			604800	; expiration
			3600 )	; minimum
	IN	NS	localhost.
	IN	A		127.0.0.1
^D</userinput></screen>

	  <calloutlist>
	    <callout arearefs="localtime">
	      <para>This allows <application>named</application> to log the
		correct time to &man.syslogd.8;</para>
	    </callout>
	  </calloutlist>
	</listitem>

	<listitem>
	  <para>If you are running a version of &os; prior to 4.9-RELEASE, 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>

	  <para>If you are running &os; version 4.9-RELEASE or later, then
	    the copy of <command>named-xfer</command> in
	    <filename>/usr/libexec</filename> is statically linked by default,
	    and you can simply use &man.cp.1; to copy it into your sandbox.</para>
	</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 set up 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;.  The &man.ntpd.8; program changes the
	  clock gradually, whereas &man.ntpdate.8; sets the clock, no
	  matter how great the difference between a machine's current
	  clock setting and the correct time.</para>

	<para>To enable &man.ntpdate.8; at boot time, add
	  <literal>ntpdate_enable="YES"</literal> to
	  <filename>/etc/rc.conf</filename>.  You will also need to
	  specify all servers you wish to synchronize with and any
	  flags to be passed to &man.ntpdate.8; in
	  <varname>ntpdate_flags</varname>.</para>
      </sect3>

      <sect3>
	<indexterm>
	  <primary>NTP</primary>
	  <secondary>ntp.conf</secondary>
	</indexterm>

	<title>General Configuration</title>

	<para>NTP is configured by the
	  <filename>/etc/ntp.conf</filename> file in the format
	  described in &man.ntp.conf.5;.  Here is a simple
	  example:</para>

	<programlisting>server ntplocal.example.com prefer
server timeserver.example.org
server ntp2a.example.net

driftfile /var/db/ntp.drift</programlisting>

	<para>The <literal>server</literal> option specifies which
	  servers are to be used, with one server listed on each line.
	  If a server is specified with the <literal>prefer</literal>
	  argument, as with <hostid
	  role="fqdn">ntplocal.example.com</hostid>, that server is
	  preferred over other servers.  A response from a preferred
	  server will be discarded if it differs significantly from
	  other servers' responses, otherwise it will be used without
	  any consideration to other responses.  The
	  <literal>prefer</literal> argument is normally used for NTP
	  servers that are known to be highly accurate, such as those
	  with special time monitoring hardware.</para>

	<para>The <literal>driftfile</literal> option specifies which
	  file is used to store the system clock's frequency offset.
	  The &man.ntpd.8; program uses this to automatically compensate for the
	  clock's natural drift, allowing it to maintain a reasonably
	  correct setting even if it is cut off from all external time
	  sources for a period of time.</para>

	<para>The <literal>driftfile</literal> option specifies which
	  file is used to store information about previous responses
	  from the NTP servers you are using.  This file contains
	  internal information for NTP.  It should not be modified by
	  any other process.</para>
      </sect3>

      <sect3>
	<title>Controlling Access to Your Server</title>

	<para>By default, your NTP server will be accessible to all
	  hosts on the Internet.  The <literal>restrict</literal>
	  option in <filename>/etc/ntp.conf</filename> allows you to control which
	  machines can access your server.</para>

	<para>If you want to deny all machines from accessing your NTP
	  server, add the following line to
	  <filename>/etc/ntp.conf</filename>:</para>

        <programlisting>restrict default ignore</programlisting>

        <para>If you only want to
	  allow machines within your own network to synchronize their
	  clocks with your server, but ensure they are not allowed to
	  configure the server or used as peers to synchronize
	  against, add</para>

        <programlisting>restrict 192.168.1.0 mask 255.255.255.0 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 <literal>xntpd_enable="YES"</literal> 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>

      <note>
	<para>Under &os;&nbsp;5.X, various options in
	  <filename>/etc/rc.conf</filename> have been renamed.  Thus,
	  you have to replace every instance of <literal>xntpd</literal>
	  with <literal>ntpd</literal> in the options above.</para></note>
    </sect2>

    <sect2>
      <title>Using ntpd with a Temporary Internet
	Connection</title>

      <para>The &man.ntpd.8; program does not need a permanent
	connection to the Internet to function properly.  However, if
	you have a temporary connection that is configured to dial out
	on demand, it is a good idea to prevent NTP traffic from
	triggering a dial out or keeping the connection alive.  If you
	are using user PPP, you can use <literal>filter</literal>
	directives in <filename>/etc/ppp/ppp.conf</filename>.  For
	example:</para>

      <programlisting> set filter dial 0 deny udp src eq 123
 # Prevent NTP traffic from initiating dial out
 set filter dial 1 permit 0 0
 set filter alive 0 deny udp src eq 123
 # Prevent incoming NTP traffic from keeping the connection open
 set filter alive 1 deny udp dst eq 123
 # Prevent outgoing NTP traffic from keeping the connection open
 set filter alive 2 permit 0/0 0/0</programlisting>

      <para>For more details see the <literal>PACKET
	FILTERING</literal> section in &man.ppp.8; and the examples in
	<filename>/usr/share/examples/ppp/</filename>.</para>

      <note>
	<para>Some Internet access providers block low-numbered ports,
	  preventing NTP from functioning since replies never
	  reach your machine.</para>
      </note>
    </sect2>

    <sect2>
      <title>Further Information</title>

      <para>Documentation for the NTP server can be found in
	<filename>/usr/share/doc/ntp/</filename> in HTML
	format.</para>
    </sect2>
  </sect1>

  <sect1 id="network-natd">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Chern</firstname>
          <surname>Lee</surname>
          <contrib>Contributed by </contrib>
        </author>
      </authorgroup>
    </sect1info>
    <title>Network Address Translation</title>

    <sect2 id="network-natoverview">
      <title>Overview</title>
      <indexterm>
        <primary><application>natd</application></primary>
      </indexterm>
      <para>FreeBSD's Network Address Translation daemon, commonly known as
        &man.natd.8; is a daemon that accepts incoming raw IP packets,
        changes the source to the local machine and re-injects these packets
        back into the outgoing IP packet stream.  &man.natd.8; does this by changing
        the source IP address and port such that when data is received back,
        it is able to determine the original location of the data and forward
        it back to its original requester.</para>
      <indexterm><primary>Internet connection sharing</primary></indexterm>
      <indexterm><primary>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&mdash;one for connecting
        to the Internet router, the other connecting to a LAN.  All the
        machines on the LAN are connected through a hub or switch.</para>

      <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>

      <note>
	<para>It is also possible to use a configuration file for
	  &man.natd.8; when there are too many options to pass.  In this
	  case, the configuration file must be defined by adding the
	  following line to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>natd_flags="-f /etc/natd.conf"</programlisting>

	<para>The <filename>/etc/natd.conf</filename> file will
	  contain a list of configuration options, one per line.  For
	  example the next section case would use the following
	  file:</para>

	<programlisting>redirect_port tcp 192.168.0.2:6667 6667
redirect_port tcp 192.168.0.3:80 80</programlisting>

	<para>For more information about the configuration file,
	  consult the &man.natd.8; manual page about the
	  <option>-f</option> option.</para>
      </note>

      <para>Each machine and interface behind the LAN should be
        assigned IP address numbers in the private network space as
        defined by <ulink
        url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink>
        and have a default gateway of the <application>natd</application> machine's internal IP
        address.</para>

      <para>For example, client <hostid>A</hostid> and
        <hostid>B</hostid> behind the LAN have IP addresses of <hostid
        role="ipaddr">192.168.0.2</hostid> and <hostid
        role="ipaddr">192.168.0.3</hostid>, while the natd machine's
        LAN interface has an IP address of <hostid
        role="ipaddr">192.168.0.1</hostid>.  Client <hostid>A</hostid>
        and <hostid>B</hostid>'s default gateway must be set to that
        of the <application>natd</application> machine, <hostid
        role="ipaddr">192.168.0.1</hostid>.  The <application>natd</application> machine's
        external, or Internet interface does not require any special
        modification for &man.natd.8; to work.</para>
    </sect2>

    <sect2 id="network-natdport-redirection">
      <title>Port Redirection</title>

      <para>The drawback with &man.natd.8; is that the LAN clients are not accessible
        from the Internet.  Clients on the LAN can make outgoing connections to
        the world but cannot receive incoming ones.  This presents a problem
        if trying to run Internet services on one of the LAN client machines.
        A simple way around this is to redirect selected Internet ports on the
        <application>natd</application> machine to a LAN client.
      </para>

      <para>For example, an IRC server runs on client <hostid>A</hostid>, and a web server runs
        on client <hostid>B</hostid>.  For this to work properly, connections received on ports
        6667 (IRC) and 80 (web) must be redirected to the respective machines.
      </para>

      <para>The <option>-redirect_port</option> must be passed to
        &man.natd.8; with the proper options.  The syntax is as follows:</para>
      <programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
                 [aliasIP:]aliasPORT[-aliasPORT]
                 [remoteIP[:remotePORT[-remotePORT]]]</programlisting>

      <para>In the above example, the argument should be:</para>

        <programlisting>    -redirect_port tcp 192.168.0.2:6667 6667
    -redirect_port tcp 192.168.0.3:80 80</programlisting>

      <para>
        This will redirect the proper <emphasis>tcp</emphasis> ports to the
        LAN client machines.
      </para>

      <para>The <option>-redirect_port</option> argument can be used to indicate port
        ranges over individual ports.  For example, <replaceable>tcp
        192.168.0.2:2000-3000 2000-3000</replaceable> would redirect
        all connections received on ports 2000 to 3000 to ports 2000
        to 3000 on client <hostid>A</hostid>.</para>

      <para>These options can be used when directly running
        &man.natd.8;, placed within the
        <literal>natd_flags=""</literal> option in
        <filename>/etc/rc.conf</filename>,
	or passed via a configuration file.</para>

      <para>For further configuration options, consult &man.natd.8;</para>
    </sect2>

    <sect2 id="network-natdaddress-redirection">
      <title>Address Redirection</title>
      <indexterm><primary>address redirection</primary></indexterm>
      <para>Address redirection is useful if several IP addresses are
        available, yet they must be on one machine.  With this,
        &man.natd.8; can assign each LAN client its own external IP address.
        &man.natd.8; then rewrites outgoing packets from the LAN clients
        with the proper external IP address and redirects
        all traffic incoming on that particular IP address back to
        the specific LAN client.  This is also known as static NAT.
        For example, the IP addresses <hostid role="ipaddr">128.1.1.1</hostid>,
        <hostid role="ipaddr">128.1.1.2</hostid>, and
        <hostid role="ipaddr">128.1.1.3</hostid> belong to the <application>natd</application> gateway
        machine.  <hostid role="ipaddr">128.1.1.1</hostid> can be used
        as the <application>natd</application> gateway machine's external IP address, while
        <hostid role="ipaddr">128.1.1.2</hostid> and
        <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to LAN
        clients <hostid>A</hostid> and <hostid>B</hostid>.</para>

      <para>The <option>-redirect_address</option> syntax is as follows:</para>

      <programlisting>-redirect_address localIP publicIP</programlisting>


      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row>
              <entry>localIP</entry>
              <entry>The internal IP address of the LAN client.</entry>
            </row>
            <row>
              <entry>publicIP</entry>
              <entry>The external IP address corresponding to the LAN client.</entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>In the example, this argument would read:</para>

      <programlisting>-redirect_address 192.168.0.2 128.1.1.2
-redirect_address 192.168.0.3 128.1.1.3</programlisting>

      <para>Like <option>-redirect_port</option>, these arguments are also placed within
        the <literal>natd_flags=""</literal> option of <filename>/etc/rc.conf</filename>, or passed via a configuration file.  With address
        redirection, there is no need for port redirection since all data
        received on a particular IP address is redirected.</para>

      <para>The external IP addresses on the <application>natd</application> machine must be active and aliased
        to the external interface.  Look at &man.rc.conf.5; to do so.</para>

    </sect2>
  </sect1>

  <sect1 id="network-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
	<literal>NO</literal> 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 <literal>tcp4</literal> for the protocol and the other using
	      <literal>tcp6</literal>.</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 <literal>-wW</literal>,
	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 <option>wait</option>
	      option, while stream socket daemons, which are usually
	      multi-threaded, should use <option>nowait</option>.
	      <option>wait</option> usually hands off multiple sockets
	      to a single daemon, while <option>nowait</option> spawns a
	      child daemon for each new socket.</para>

	    <para>The maximum number of child daemons
	      <application>inetd</application> may spawn can be set using
	      the <option>max-child</option> option.  If a limit of ten
	      instances of a particular daemon is needed, a
	      <literal>/10</literal> would be placed after
	      <option>nowait</option>.</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>This is the username that the particular daemon
	      should run as.  Most commonly, daemons run as the
	      <username>root</username> user.  For security purposes, it is
	      common to find some servers running as the
	      <username>daemon</username> user, or the least privileged
	      <username>nobody</username> user.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>server-program</term>

	  <listitem>
	    <para>The full path of the daemon to be executed when a
	      connection is received.  If the daemon is a service
	      provided by <application>inetd</application> internally,
	      then <option>internal</option> should be
	      used.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>server-program-arguments</term>

	  <listitem>
	    <para>This works in conjunction with
	      <option>server-program</option> by specifying the
	      arguments, starting with <literal>argv[0]</literal>, passed to the daemon on
	      invocation.  If <command>mydaemon -d</command> is
	      the command line, <literal>mydaemon -d</literal> would be
	      the value of <option>server-program-arguments</option>.
	      Again, if the daemon is an internal service, use
	      <option>internal</option> here.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="network-inetd-security">
      <title>Security</title>

      <para>Depending on the 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>max-connections-per-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
	(<application>ident</application>, <application>identd</application>) 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>First, you have to get a laplink cable.
	Then, confirm that both computers have a kernel with &man.lpt.4; driver
	support:</para>

      <screen>&prompt.root; <userinput>grep lp /var/run/dmesg.boot</userinput>
lpt0: &lt;Printer&gt; on ppbus0
lpt0: Interrupt-driven port</screen>

      <para>The parallel port must be an interrupt driven port, under
	&os;&nbsp;4.X, you should have a line similar to the
	following in your kernel configuration file:</para>

      <programlisting>device ppc0 at isa? irq 7</programlisting>

      <para>Under &os;&nbsp;5.X, the
	<filename>/boot/device.hints</filename> file should contain the
	following lines:</para>

      <programlisting>hint.ppc.0.at="isa"
hint.ppc.0.irq="7"</programlisting>

      <para>Then check if the kernel configuration file has a
	<literal>device plip</literal> line or if the
	<filename>plip.ko</filename> kernel module is loaded.  In both
	cases the parallel networking interface should appear when you
	directly use the &man.ifconfig.8; command.  Under
	&os;&nbsp;4.X like this:</para>

      <screen>&prompt.root; <userinput>ifconfig lp0</userinput>
lp0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500</screen>

      <para>and for &os;&nbsp;5.X:</para>

      <screen>&prompt.root; <userinput>ifconfig plip0</userinput>
plip0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500</screen>

      <note><para>The device name used for parallel interface is
	different between &os;&nbsp;4.X
	(<devicename>lp<replaceable>X</replaceable></devicename>)
	and &os;&nbsp;5.X
	(<devicename>plip<replaceable>X</replaceable></devicename>).</para></note>

      <para>Plug in the laplink cable into the parallel interface on
	both computers.</para>

      <para>Configure the network interface parameters on both
	sites as <username>root</username>.  For example, if you want connect
	the host <hostid>host1</hostid> running &os;&nbsp;4.X with <hostid>host2</hostid> running &os;&nbsp;5.X:</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 <hostid>host2</hostid> by doing:</para>

      <screen>&prompt.root; <userinput>ifconfig plip0 10.0.0.2 10.0.0.1</userinput></screen>


      <para>You now should have a working connection.  Please read the
        manual pages &man.lp.4; and &man.lpt.4; for more details.</para>

      <para>You should also add both hosts to
	<filename>/etc/hosts</filename>:</para>

      <programlisting>127.0.0.1               localhost.my.domain localhost
10.0.0.1                host1.my.domain host1
10.0.0.2                host2.my.domain</programlisting>

      <para>To confirm the connection works, go to each host and ping
	the other.  For example, on <hostid>host1</hostid>:</para>

          <screen>&prompt.root; <userinput>ifconfig 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          0       0       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 (<ulink
	  url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>)</para>
      </listitem>

      <listitem>
	<para>Anycast addresses (<quote>one-out-of many</quote>)</para>
      </listitem>

      <listitem>
	<para>Mandatory multicast addresses</para>
      </listitem>

      <listitem>
	<para>IPsec (IP security)</para>
      </listitem>

      <listitem>
	<para>Simplified header structure</para>
      </listitem>

      <listitem>
	<para>Mobile <acronym>IP</acronym></para>
      </listitem>

      <listitem>
	<para>IPv4-to-IPv6 transition mechanisms</para>
      </listitem>
    </itemizedlist>


    <para>For more information see:</para>

    <itemizedlist>
      <listitem>
	<para>IPv6 overview at <ulink url="http://playground.sun.com/pub/ipng/html/ipng-main.html">playground.sun.com</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.kame.net">KAME.net</ulink></para>
      </listitem>

      <listitem>
	<para><ulink url="http://www.6bone.net">6bone.net</ulink></para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>Background on IPv6 Addresses</title>
      <para>There are different types of IPv6 addresses: Unicast, Anycast and
	Multicast.</para>

      <para>Unicast addresses are the well known addresses.  A packet sent
	to a unicast address arrives exactly at the interface belonging to
	the address.</para>

      <para>Anycast addresses are syntactically indistinguishable from unicast
	addresses but they address a group of interfaces.  The packet destined for
	an anycast address will arrive at the nearest (in router metric)
	interface.  Anycast addresses may only be used by routers.</para>

      <para>Multicast addresses identify a group of interfaces.  A packet destined
	for a multicast address will arrive at all interfaces belonging to the
	multicast group.</para>

	<note><para>The IPv4 broadcast address (usually <hostid role="ipaddr">xxx.xxx.xxx.255</hostid>) is expressed
	  by multicast addresses in IPv6.</para></note>

      <table>
	<title>Reserved IPv6 addresses</title>

	<tgroup cols="4">
	  <thead>
	    <row>
	      <entry>IPv6 address</entry>
	      <entry>Prefixlength (Bits)</entry>
	      <entry>Description</entry>
	      <entry>Notes</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><hostid role="ip6addr">::</hostid></entry>
	      <entry>128 bits</entry>
	      <entry>unspecified</entry>
	      <entry>cf. <hostid role="ipaddr">0.0.0.0</hostid> in
		IPv4</entry>
	    </row>

	    <row>
	      <entry><hostid role="ip6addr">::1</hostid></entry>
	      <entry>128 bits</entry>
	      <entry>loopback address</entry>
	      <entry>cf. <hostid role="ipaddr">127.0.0.1</hostid> in
		IPv4</entry>
	    </row>

	    <row>
	      <entry><hostid
		role="ip6addr">::00:xx:xx:xx:xx</hostid></entry>
	      <entry>96 bits</entry>
	      <entry>embedded IPv4</entry>
	      <entry>The lower 32 bits are the IPv4 address.  Also
		called <quote>IPv4 compatible IPv6
		address</quote></entry>
	    </row>

	    <row>
	      <entry><hostid
		role="ip6addr">::ff:xx:xx:xx:xx</hostid></entry>
	      <entry>96 bits</entry>
	      <entry>IPv4 mapped IPv6 address</entry>
	      <entry>The lower 32 bits are the IPv4 address.
		For hosts which do not support IPv6.</entry>
	    </row>

	    <row>
	      <entry><hostid role="ip6addr">fe80::</hostid> - <hostid
		role="ip6addr">feb::</hostid></entry>
	      <entry>10 bits</entry>
	      <entry>link-local</entry>
	      <entry>cf. loopback address in IPv4</entry>
	    </row>

	    <row>
	      <entry><hostid role="ip6addr">fec0::</hostid> - <hostid
		role="ip6addr">fef::</hostid></entry>
	      <entry>10 bits</entry>
	      <entry>site-local</entry>
	      <entry>&nbsp;</entry>
	    </row>

	    <row>
	      <entry><hostid role="ip6addr">ff::</hostid></entry>
	      <entry>8 bits</entry>
	      <entry>multicast</entry>
	      <entry>&nbsp;</entry>
	    </row>

	    <row>
	      <entry><hostid role="ip6addr">001</hostid> (base
		2)</entry>
	      <entry>3 bits</entry>
	      <entry>global unicast</entry>
	      <entry>All global unicast addresses are assigned from
		this pool.  The first 3 bits are
		<quote>001</quote>.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </sect2>

    <sect2>
      <title>Reading IPv6 Addresses</title>
      <para>The canonical form is represented as: <hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, each
	<quote>x</quote> being a 16 Bit hex value.  For example
	<hostid role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></para>

      <para>Often an address will have long substrings of all zeros
	therefore 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 <ulink
	url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</para>
    </sect2>

    <sect2>
      <title>Getting Connected</title>

      <para>Currently there are four ways to connect to other IPv6 hosts and networks:</para>

      <itemizedlist>
	<listitem>
	  <para>Join the experimental 6bone</para>
	</listitem>

	<listitem>
	  <para>Getting an IPv6 network from your upstream provider.  Talk to your
	    Internet provider for instructions.</para>
	</listitem>

	<listitem>
	  <para>Tunnel via 6-to-4</para>
	</listitem>

	<listitem>
	  <para>Use the <filename role="package">net/freenet6</filename> port if you are on a dial-up connection.</para>
	</listitem>
      </itemizedlist>

      <para>Here we will talk on how to connect to the 6bone since it currently seems
	to be the most popular way.</para>

      <para>First take a look at the <ulink url="http://www.6bone.net/">6bone</ulink> site and find a 6bone connection nearest to
	you.  Write to the responsible person and with a little bit of luck you
	will be given instructions on how to set up your connection.  Usually this
	involves setting up a GRE (gif) tunnel.</para>

      <para>Here is a typical example on setting up a &man.gif.4; tunnel:</para>

      <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput>
&prompt.root; <userinput>ifconfig gif0</userinput>
gif0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1280
&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>MY_IPv4_ADDR</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 <hostid role="ip6addr">ff02::1%gif0</hostid>.  You should receive two ping replies.</para>

	<note><para>In case you are intrigued by the address <hostid role="ip6addr">ff02:1%gif0</hostid>, this is a
	  multicast address.  <literal>%gif0</literal> states that the multicast address at network
	  interface <devicename>gif0</devicename> is to be used.  Since we <command>ping</command> a multicast address the
	  other endpoint of the tunnel should reply as well.</para></note>

      <para>By now setting up a route to your 6bone uplink should be rather
	straightforward:</para>

      <screen>&prompt.root; <userinput>route add -inet6 default -interface gif0</userinput>
&prompt.root; <userinput>ping6 -n <replaceable>MY_UPLINK</replaceable></userinput></screen>

      <screen>&prompt.root; <userinput>traceroute6 www.jp.FreeBSD.org</userinput>
(3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
     1  atnet-meta6  14.147 ms  15.499 ms  24.319 ms
     2  6bone-gw2-ATNET-NT.ipv6.tilab.com  103.408 ms  95.072 ms *
     3  3ffe:1831:0:ffff::4  138.645 ms  134.437 ms  144.257 ms
     4  3ffe:1810:0:6:290:27ff:fe79:7677  282.975 ms  278.666 ms  292.811 ms
     5  3ffe:1800:0:ff00::4  400.131 ms  396.324 ms  394.769 ms
     6  3ffe:1800:0:3:290:27ff:fe14:cdee  394.712 ms  397.19 ms  394.102 ms</screen>

      <para>This output will differ from machine to machine.  By now you should be
	able to reach the IPv6 site <ulink url="http://www.kame.net">www.kame.net</ulink>
	and see the dancing tortoise &mdash; that is if you have a IPv6 enabled browser such as
	<filename role="package">www/mozilla</filename>.</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>

  <sect1 id="network-atm">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Harti</firstname>
	  <surname>Brandt</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>ATM on &os;&nbsp;5.X</title>

    <sect2>
      <title>Configuring classical IP over ATM (PVCs)</title>

      <para>Classical IP over ATM (<acronym>CLIP</acronym>) is the
	simplest method to use ATM with IP.  It can be used with
	switched connections (SVCs) and with permanent connections
	(PVCs).  This section describes how to set up a network based
	on PVCs.</para>

      <sect3>
	<title>Fully meshed configurations</title>

	<para>The first method to set up a <acronym>CLIP</acronym> with
	  PVCs is to connect each machine to each other machine in the
	  network via a dedicated PVC.  While this is simple to
	  configure it tends to become impractical for larger number
	  of machines.  The example supposes that we have four
	  machines in the network, each connected to the ATM network
	  with an ATM adapter card.  The first step is the planning of
	  the IP addresses and the ATM connections between the
	  machines.  We use the following:</para>

	<informaltable frame="none">
	  <tgroup cols="2">
	    <colspec colwidth="1*">
	    <colspec colwidth="1*">
	    <thead>
	      <row>
		<entry>Host</entry>
		<entry>IP Adress</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><hostid>hostA</hostid></entry>
		<entry><hostid role="ipaddr">192.168.173.1</hostid></entry>
	      </row>

	      <row>
		<entry><hostid>hostB</hostid></entry>
		<entry><hostid role="ipaddr">192.168.173.2</hostid></entry>
	      </row>

	      <row>
		<entry><hostid>hostC</hostid></entry>
		<entry><hostid role="ipaddr">192.168.173.3</hostid></entry>
	      </row>

	      <row>
		<entry><hostid>hostD</hostid></entry>
		<entry><hostid role="ipaddr">192.168.173.4</hostid></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>To build a fully meshed net we need one ATM connection
	  between each pair of machines:</para>

	<informaltable frame="none">
	  <tgroup cols="2">
	    <colspec colwidth="1*">
	    <colspec colwidth="1*">
	    <thead>
	      <row>
		<entry>Machines</entry>
		<entry>VPI.VCI couple</entry>
	      </row>
	    </thead>

	    <tbody>
	      <row>
		<entry><hostid>hostA</hostid> - <hostid>hostB</hostid></entry>
		<entry>0.100</entry>
	      </row>

	      <row>
		<entry><hostid>hostA</hostid> - <hostid>hostC</hostid></entry>
		<entry>0.101</entry>
	      </row>

	      <row>
		<entry><hostid>hostA</hostid> - <hostid>hostD</hostid></entry>
		<entry>0.102</entry>
	      </row>

	      <row>
		<entry><hostid>hostB</hostid> - <hostid>hostC</hostid></entry>
		<entry>0.103</entry>
	      </row>

	      <row>
		<entry><hostid>hostB</hostid> - <hostid>hostD</hostid></entry>
		<entry>0.104</entry>
	      </row>

	      <row>
		<entry><hostid>hostC</hostid> - <hostid>hostD</hostid></entry>
		<entry>0.105</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>The VPI and VCI values at each end of the connection may
	  of course differ, but for simplicity we assume that they are
	  the same.  Next we need to configure the ATM interfaces on
	  each host:</para>

	<screen>hostA&prompt.root; ifconfig hatm0 192.168.173.1 up
hostB&prompt.root; ifconfig hatm0 192.168.173.2 up
hostC&prompt.root; ifconfig hatm0 192.168.173.3 up
hostD&prompt.root; ifconfig hatm0 192.168.173.4 up</screen>

	<para>assuming that the ATM interface is
	  <devicename>hatm0</devicename> on all hosts.  Now the PVCs
	  need to configured on <hostid>hostA</hostid> (we assume that
	  they are already configured on the ATM switches, you need to
	  consult the manual for the switch on how to do this).</para>

	<screen>hostA&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr
hostA&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr
hostA&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr

hostB&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr
hostB&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr
hostB&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr

hostC&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr
hostC&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr
hostC&prompt.root; atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr

hostD&prompt.root; atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr
hostD&prompt.root; atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr
hostD&prompt.root; atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</screen>

	<para>Of course other traffic contracts than UBR can be used
	  given the ATM adapter supports those.  In this case the name
	  of the traffic contract is followed by the parameters of the
	  traffic.  Help for the &man.atmconfig.8; tool can be
	  obtained with:</para>

	<screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen>

	<para>or in the &man.atmconfig.8; manual page.</para>

	<para>The same configuration can also be done via
	  <filename>/etc/rc.conf</filename>.
	  For <hostid>hostA</hostid> this would look like:</para>

<programlisting>network_interfaces="lo0 hatm0"
ifconfig_hatm0="inet 192.168.173.1 up"
natm_static_routes="hostB hostC hostD"
route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr"
route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr"
route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting>

	<para>The current state of all <acronym>CLIP</acronym> routes
	  can be obtained with:</para>

	<screen>hostA&prompt.root; <userinput>atmconfig natm show</userinput></screen>
      </sect3>
    </sect2>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
<!--  LocalWords:  config mnt www -->
