path: root/el_GR.ISO8859-7/books/handbook/advanced-networking/chapter.sgml

<?xml version="1.0" encoding="ISO-8859-7" standalone="no"?>
<!--

  Ôï Åã÷åéñßäéï ôïõ FreeBSD: Ðñï÷ùñçìÝíá ÈÝìáôá Äéêôýùóçò

  The FreeBSD Greek Documentation Project

  $FreeBSD$

  %SOURCE%	en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
  %SRCID%	1.1

-->

<chapter id="advanced-networking">
  <title>Ðñï÷ùñçìÝíá ÈÝìáôá Äéêôýùóçò</title>

  <sect1 id="advanced-networking-synopsis">
    <title>Óýíïøç</title>

    <para>Ôï êåöÜëáéï áõôü êáëýðôåé ðñï÷ùñçìÝíá èÝìáôá äéêôýùóçò.</para>

    <para>Áöïý äéáâÜóåôå áõôü ôï êåöÜëáéï, èá îÝñåôå:</para>

    <itemizedlist>
      <listitem>
	<para>Ôá âáóéêÜ ôùí ðõëþí (gateways) êáé ôùí äñïìïëïãÞóåùí
          (routes).</para>
      </listitem>

      <listitem>
	<para>Ðùò íá ñõèìßóåôå óõóêåõÝò IEEE 802.11 êáé &bluetooth;.</para>
      </listitem>

      <listitem>
	<para>Ðùò íá êÜíåôå ôï &os; íá äñá ùò ãÝöõñá (bridge).</para>
      </listitem>

      <listitem>
	<para>Ðùò íá ñõèìßóåôå åêêßíçóç áðü ôï äßêôõï óå Ýíá ìç÷Üíçìá
          ÷ùñßò óêëçñü äßóêï.</para>
      </listitem>

      <listitem>
	<para>Ðùò íá ñõèìßóåôå ìåôÜöñáóç äéêôõáêþí äéåõèýíóåùí (NAT).</para>
      </listitem>

      <listitem>
	<para>Ðùò íá óõíäÝóåôå äýï õðïëïãéóôÝò ìÝóù PLIP.</para>
      </listitem>

      <listitem>
	<para>Ðùò íá ñõèìßóåôå ôï IPv6 óå Ýíá ìç÷Üíçìá &os;.</para>
      </listitem>

      <listitem>
	<para>Ðùò íá ñõèìßóåôå ôï ATM.</para>
      </listitem>

      <listitem>
	<para>Ðùò íá ñõèìßóåôå êáé íá ÷ñçóéìïðïéÞóåôå ôéò äõíáôüôçôåò ôïõ
          CARP (Common Access Redundancy Protocol) óôï &os;.</para>
      </listitem>
    </itemizedlist>

    <para>Ðñéí äéáâÜóåôå áõôü ôï êåöÜëáéï, èá ðñÝðåé:</para>

    <itemizedlist>
      <listitem>
	<para>Íá êáôáíïåßôå ôéò âáóéêÝò Ýííïéåò ôùí áñ÷åßùí script
          <filename>/etc/rc</filename>.</para>
      </listitem>

      <listitem>
	<para>Íá åßóôå åîïéêåéùìÝíïò ìå ôç âáóéêÞ ïñïëïãßá ôùí äéêôýùí.</para>
      </listitem>

      <listitem>
        <para>Íá ãíùñßæåôå ðùò íá ñõèìßóåôå êáé íá åãêáôáóôÞóåôå Ýíá íÝï
          ðõñÞíá óôï &os; (<xref linkend="kernelconfig"/>).</para>
      </listitem>

      <listitem>
      <para>Íá ãíùñßæåôå ðùò íá åãêáôáóôÞóåôå ðñüóèåôï ëïãéóìéêü ôñßôïõ
        êáôáóêåõáóôÞ (<xref linkend="ports"/>).</para>
      </listitem>

    </itemizedlist>
  </sect1>

  <sect1 id="network-routing">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Coranth</firstname>
      	  <surname>Gryphon</surname>
	  <contrib>Contributed by </contrib>
        </author>
      </authorgroup>
    </sect1info>
    <title>Gateways and Routes</title>

    <indexterm><primary>routing</primary></indexterm>
    <indexterm><primary>gateway</primary></indexterm>
    <indexterm><primary>subnet</primary></indexterm>
    <para>For one machine to be able to find another over a network,
      there must be a mechanism in place to describe how to get from
      one to the other.  This is called
      <firstterm>routing</firstterm>.  A <quote>route</quote> is a
      defined pair of addresses: a <quote>destination</quote> and a
      <quote>gateway</quote>.  The pair indicates that if you are
      trying to get to this <emphasis>destination</emphasis>,
      communicate through this <emphasis>gateway</emphasis>.  There
      are three types of destinations: individual hosts, subnets, and
      <quote>default</quote>.  The <quote>default route</quote> is
      used if none of the other routes apply.  We will talk a little
      bit more about default routes later on.  There are also three
      types of gateways: individual hosts, interfaces (also called
      <quote>links</quote>), and Ethernet hardware addresses (MAC
      addresses).
    </para>

    <sect2>
      <title>An Example</title>

      <para>To illustrate different aspects of routing, we will use the
	following example from <command>netstat</command>:</para>

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

Destination      Gateway            Flags     Refs     Use     Netif Expire

default          outside-gw         UGSc       37      418      ppp0
localhost        localhost          UH          0      181       lo0
test0            0:e0:b5:36:cf:4f   UHLW        5    63288       ed0     77
10.20.30.255     link#1             UHLW        1     2421
example.com      link#1             UC          0        0
host1            0:e0:a8:37:8:1e    UHLW        3     4601       lo0
host2            0:e0:a8:37:8:1e    UHLW        0        5       lo0 =>
host2.example.com link#1             UC          0        0
224              link#1             UC          0        0</screen>

      <indexterm><primary>default route</primary></indexterm>
      <para>The first two lines specify the default route (which we
	will cover in the <link linkend="network-routing-default">next
	  section</link>) and the <hostid>localhost</hostid> route.</para>

      <indexterm><primary>loopback device</primary></indexterm>
      <para>The interface (<literal>Netif</literal> column) that this
	routing table specifies to use for
	<literal>localhost</literal> is <devicename>lo0</devicename>,
	also known as the loopback device.  This says to keep all
	traffic for this destination internal, rather than sending it
	out over the LAN, since it will only end up back where it
	started.</para>

      <indexterm>
        <primary>Ethernet</primary>
        <secondary>MAC address</secondary>
      </indexterm>
      <para>The next thing that stands out are the addresses beginning
	with <hostid role="mac">0:e0:</hostid>.  These are Ethernet
	hardware addresses, which are also known as MAC addresses.
	FreeBSD will automatically identify any hosts
	(<hostid>test0</hostid> in the example) on the local Ethernet
	and add a route for that host, directly to it over the
	Ethernet interface, <devicename>ed0</devicename>.  There is
	also a timeout (<literal>Expire</literal> column) associated
	with this type of route, which is used if we fail to hear from
	the host in a specific amount of time.  When this happens, the
	route to this host will be automatically deleted.  These hosts
	are identified using a mechanism known as RIP (Routing
	Information Protocol), which figures out routes to local hosts
	based upon a shortest path determination.</para>

      <indexterm><primary>subnet</primary></indexterm>
      <para>FreeBSD will also add subnet routes for the local subnet (<hostid
	  role="ipaddr">10.20.30.255</hostid> is the broadcast address for the
	subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid
	  role="domainname">example.com</hostid> is the domain name associated
	with that subnet).  The designation <literal>link#1</literal> refers
	to the first Ethernet card in the machine.  You will notice no
	additional interface is specified for those.</para>

      <para>Both of these groups (local network hosts and local subnets) have
	their routes automatically configured by a daemon called
	<application>routed</application>.  If this is not run, then only
	routes which are statically defined (i.e. entered explicitly) will
	exist.</para>

      <para>The <literal>host1</literal> line refers to our host, which it
	knows by Ethernet address.  Since we are the sending host, FreeBSD
	knows to use the loopback interface (<devicename>lo0</devicename>)
	rather than sending it out over the Ethernet interface.</para>

      <para>The two <literal>host2</literal> lines are an example of
	what happens when we use an &man.ifconfig.8; alias (see the
	section on Ethernet for reasons why we would do this).  The
	<literal>=&gt;</literal> symbol after the
	<devicename>lo0</devicename> interface says that not only are
	we using the loopback (since this address also refers to the
	local host), but specifically it is an alias.  Such routes
	only show up on the host that supports the alias; all other
	hosts on the local network will simply have a
	<literal>link#1</literal> line for such routes.</para>

      <para>The final line (destination subnet <hostid role="ipaddr">224</hostid>) deals
	with multicasting, which will be covered in another section.</para>

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

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="4*"/>

	  <tbody>
	    <row>
	      <entry>U</entry>
	      <entry>Up: The route is active.</entry>
	    </row>

	    <row>
	      <entry>H</entry>
	      <entry>Host: The route destination is a single host.</entry>
	    </row>

	    <row>
	      <entry>G</entry>
	      <entry>Gateway: Send anything for this destination on to this
		remote system, which will figure out from there where to send
		it.</entry>
	    </row>

	    <row>
	      <entry>S</entry>
	      <entry>Static: This route was configured manually, not
		automatically generated by the system.</entry>
	    </row>

	    <row>
	      <entry>C</entry>
	      <entry>Clone: Generates a new route based upon this route for
		machines we connect to.  This type of route is normally used
		for local networks.</entry>
	    </row>

	    <row>
	      <entry>W</entry>
	      <entry>WasCloned: Indicated a route that was auto-configured
		based upon a local area network (Clone) route.</entry>
	    </row>

	    <row>
	      <entry>L</entry>
	      <entry>Link: Route involves references to Ethernet
		hardware.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>
    </sect2>

    <sect2 id="network-routing-default">
      <title>Default Routes</title>

      <indexterm><primary>default route</primary></indexterm>
      <para>When the local system needs to make a connection to a remote host,
	it checks the routing table to determine if a known path exists.  If
	the remote host falls into a subnet that we know how to reach (Cloned
	routes), then the system checks to see if it can connect along that
	interface.</para>

      <para>If all known paths fail, the system has one last option: the
	<quote>default</quote> route.  This route is a special type of gateway
	route (usually the only one present in the system), and is always
	marked with a <literal>c</literal> in the flags field.  For hosts on a
	local area network, this gateway is set to whatever machine has a
	direct connection to the outside world (whether via PPP link,
	DSL, cable modem, T1, or another network interface).</para>

      <para>If you are configuring the default route for a machine which
	itself is functioning as the gateway to the outside world, then the
	default route will be the gateway machine at your Internet Service
	Provider's (ISP) site.</para>

      <para>Let us look at an example of default routes.  This is a common
	configuration:</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2>
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Al</firstname>
	    <surname>Hoang</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <!-- Feb 2004 -->
      <title>Setting Up Static Routes</title>

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

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

	<mediaobject>
	  <imageobject>
	    <imagedata fileref="advanced-networking/static-routes"/>
	  </imageobject>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2>
      <title>Multicast Routing</title>
      <indexterm>
	<primary>multicast routing</primary>
      </indexterm>
      <indexterm>
	<primary>kernel options</primary>
	<secondary>MROUTING</secondary>
      </indexterm>
      <para>FreeBSD supports both multicast applications and multicast
	routing natively.  Multicast applications do not require any
	special configuration of FreeBSD; applications will generally
	run out of the box.  Multicast routing
	requires that support be compiled into the kernel:</para>

      <programlisting>options MROUTING</programlisting>

      <para>In addition, the multicast routing daemon, &man.mrouted.8;
	must be configured to set up tunnels and <acronym>DVMRP</acronym> via
	<filename>/etc/mrouted.conf</filename>.  More details on
	multicast configuration may be found in the manual page for
	&man.mrouted.8;.</para>
    </sect2>
  </sect1>

  <sect1 id="network-wireless">
    <sect1info>
      <authorgroup>
	<author>
	  <othername>Loader</othername>
	</author>

	<author>
	  <firstname>Marc</firstname>
	  <surname>Fonvieille</surname>
	</author>

	<author>
	  <firstname>Murray</firstname>
	  <surname>Stokely</surname>
	</author>
      </authorgroup>
    </sect1info>
    <title>Wireless Networking</title>

    <indexterm><primary>wireless networking</primary></indexterm>
    <indexterm>
      <primary>802.11</primary>
      <see>wireless networking</see>
    </indexterm>

    <sect2>
      <title>Wireless Networking Basics</title>

      <para>Most wireless networks are based on the IEEE 802.11
	standards.  A basic wireless network consists of multiple
	stations communicating with radios that broadcast in either
	the 2.4GHz or 5GHz band (though this varies according to the
	locale and is also changing to enable communication in the
	2.3GHz and 4.9GHz ranges).</para>

      <para>802.11 networks are organized in two ways: in
	<emphasis>infrastructure mode</emphasis> one station acts as a
	master with all the other stations associating to it; the
	network is known as a BSS and the master station is termed an
	access point (AP).  In a BSS all communication passes through
	the AP; even when one station wants to communicate with
	another wireless station messages must go through the AP.  In
	the second form of network there is no master and stations
	communicate directly.  This form of network is termed an IBSS
	and is commonly known as an <emphasis>ad-hoc
	network</emphasis>.</para>

      <para>802.11 networks were first deployed in the 2.4GHz band
	using protocols defined by the IEEE 802.11 and 802.11b
	standard.  These specifications include the operating
	frequencies, MAC layer characteristics including framing and
	transmission rates (communication can be done at various
	rates).  Later the 802.11a standard defined operation in the
	5GHz band, including different signalling mechanisms and
	higher transmission rates.  Still later the 802.11g standard
	was defined to enable use of 802.11a signalling and
	transmission mechanisms in the 2.4GHz band in such a way as to
	be backwards compatible with 802.11b networks.</para>

      <para>Separate from the underlying transmission techniques
	802.11 networks have a variety of security mechanisms.  The
	original 802.11 specifications defined a simple security
	protocol called WEP. This protocol uses a fixed pre-shared key
	and the RC4 cryptographic cipher to encode data transmitted on
	a network.  Stations must all agree on the fixed key in order
	to communicate.  This scheme was shown to be easily broken and
	is now rarely used except to discourage transient users from
	joining networks.  Current security practice is given by the
	IEEE 802.11i specification that defines new cryptographic
	ciphers and an additional protocol to authenticate stations to
	an access point and exchange keys for doing data
	communication.  Further, cryptographic keys are periodically
	refreshed and there are mechanisms for detecting intrusion
	attempts (and for countering intrusion attempts).  Another
	security protocol specification commonly used in wireless
	networks is termed WPA.  This was a precursor to 802.11i
	defined by an industry group as an interim measure while
	waiting for 802.11i to be ratified.  WPA specifies a subset of
	the requirements found in 802.11i and is designed for
	implementation on legacy hardware.  Specifically WPA requires
	only the TKIP cipher that is derived from the original WEP
	cipher.  802.11i permits use of TKIP but also requires support
	for a stronger cipher, AES-CCM, for encrypting data.  (The AES
	cipher was not required in WPA because it was deemed too
	computationally costly to be implemented on legacy
	hardware.)</para>

      <para>Other than the above protocol standards the other
	important standard to be aware of is 802.11e.  This defines
	protocols for deploying multi-media applications such as
	streaming video and voice over IP (VoIP) in an 802.11 network.
	Like 802.11i, 802.11e also has a precursor specification
	termed WME (later renamed WMM) that has been defined by an
	industry group as a subset of 802.11e that can be deployed now
	to enable multi-media applications while waiting for the final
	ratification of 802.11e.  The most important thing to know
	about 802.11e and WME/WMM is that it enables prioritized
	traffic use of a wireless network through Quality of Service
	(QoS) protocols and enhanced media access protocols.  Proper
	implementation of these protocols enable high speed bursting
	of data and prioritized traffic flow.</para>

      <para>Since the 6.0 version, &os; supports networks that operate
	using 802.11a, 802.11b, and 802.11g.  The WPA and 802.11i
	security protocols are likewise supported (in conjunction with
	any of 11a, 11b, and 11g) and QoS and traffic prioritization
	required by the WME/WMM protocols are supported for a limited
	set of wireless devices.</para>
    </sect2>

    <sect2 id="network-wireless-basic">
      <title>Basic Setup</title>

      <sect3>
	<title>Kernel Configuration</title>

	<para>To use wireless networking you need a wireless
	  networking card and to configure the kernel with the
	  appropriate wireless networking support.  The latter is
	  separated into multiple modules so that you only need to
	  configure the software you are actually going to use.</para>

	<para>The first thing you need is a wireless device.  The most
	  commonly used devices are those that use parts made by
	  Atheros.  These devices are supported by the &man.ath.4;
	  driver and require the following line to be added to the
	  <filename>/boot/loader.conf</filename> file:</para>

	<programlisting>if_ath_load="YES"</programlisting>

	<para>The Atheros driver is split up into three separate
	  pieces: the driver proper (&man.ath.4;), the hardware
	  support layer that handles chip-specific functions
	  (&man.ath.hal.4;), and an algorithm for selecting which of
	  several possible rates for transmitting frames
	  (ath_rate_sample here).  When you load this support as
	  modules these dependencies are automatically handled for
	  you.  If instead of an Atheros device you had another device
	  you would select the module for that device; e.g.:</para>

	<programlisting>if_wi_load="YES"</programlisting>

	<para>for devices based on the Intersil Prism parts
	  (&man.wi.4; driver).</para>

	<note>
	  <para>In the rest of this document, we will use an
	    &man.ath.4; device, the device name in the examples must
	    be changed according to your configuration.  A list of
	    available wireless drivers can be found at the beginning
	    of the &man.wlan.4; manual page.  If a native &os; driver
	    for your wireless device does not exist, it may be
	    possible to directly use the &windows; driver with the
	    help of the <link
	    linkend="config-network-ndis">NDIS</link> driver
	    wrapper.</para>
	</note>

	<para>With a device driver configured you need to also bring
	  in the 802.11 networking support required by the driver.
	  For the &man.ath.4; driver this is at least the &man.wlan.4;
	  module; this module is automatically loaded with the
	  wireless device driver.  With that you will need the modules
	  that implement cryptographic support for the security
	  protocols you intend to use.  These are intended to be
	  dynamically loaded on demand by the &man.wlan.4; module but
	  for now they must be manually configured.  The following
	  modules are available: &man.wlan.wep.4;, &man.wlan.ccmp.4;
	  and &man.wlan.tkip.4;.  Both &man.wlan.ccmp.4; and
	  &man.wlan.tkip.4; drivers are only needed if you intend to
	  use the WPA and/or 802.11i security protocols.  If your
	  network is to run totally open (i.e., with no encryption)
	  then you do not even need the &man.wlan.wep.4; support.  To
	  load these modules at boot time, add the following lines to
	  <filename>/boot/loader.conf</filename>:</para>

	<programlisting>wlan_wep_load="YES"
wlan_ccmp_load="YES"
wlan_tkip_load="YES"</programlisting>

	<para>With this information in the system bootstrap
	  configuration file (i.e.,
	  <filename>/boot/loader.conf</filename>), you have to reboot
	  your &os; box.  If you do not want to reboot your machine
	  for the moment, you can just load the modules by hand using
	  &man.kldload.8;.</para>

	<note>
	  <para>If you do not want to use modules, it is possible to
	    compile these drivers into the kernel by adding the
	    following lines to your kernel configuration file:</para>

	  <programlisting>device ath               # Atheros IEEE 802.11 wireless network driver
device ath_hal           # Atheros Hardware Access Layer
device ath_rate_sample   # John Bicket's SampleRate control algorithm.
device wlan              # 802.11 support (Required)
device wlan_wep          # WEP crypto support for 802.11 devices
device wlan_ccmp         # AES-CCMP crypto support for 802.11 devices
device wlan_tkip         # TKIP and Michael crypto support for 802.11 devices</programlisting>

	  <para>With this information in the kernel configuration
	    file, recompile the kernel and reboot your &os;
	    machine.</para>
	</note>

	<para>When the system is up, we could find some information
	  about the wireless device in the boot messages, like
	  this:</para>

	<screen>ath0: &lt;Atheros 5212&gt; mem 0xff9f0000-0xff9fffff irq 17 at device 2.0 on pci2
ath0: Ethernet address: 00:11:95:d5:43:62
ath0: mac 7.9 phy 4.5 radio 5.6</screen>
      </sect3>
    </sect2>

    <sect2>
      <title>Infrastructure Mode</title>

      <para>The infrastructure mode or BSS mode is the mode that is
	typically used.  In this mode, a number of wireless access
	points are connected to a wired network.  Each wireless
	network has its own name, this name is called the SSID of the
	network.  Wireless clients connect to the wireless access
	points.</para>

      <sect3>
	<title>&os; Clients</title>

	<sect4>
	  <title>How to Find Access Points</title>

	  <para>To scan for networks, use the
	    <command>ifconfig</command> command.  This request may
	    take a few moments to complete as it requires that the
	    system switches to each available wireless frequency and
	    probes for available access points.  Only the super-user
	    can initiate such a scan:</para>

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput>
SSID            BSSID              CHAN RATE  S:N   INT CAPS
dlinkap         00:13:46:49:41:76    6   54M 29:0   100 EPS  WPA WME
freebsdap       00:11:95:c3:0d:ac    1   54M 22:0   100 EPS  WPA</screen>

	  <note>
	    <para>You must mark the interface <option>up</option>
	      before you can scan.  Subsequent scan requests do not
	      require you to mark the interface up again.</para>
	  </note>

	  <para>The output of a scan request lists each BSS/IBSS
	    network found.  Beside the name of the network,
	    <literal>SSID</literal>, we find the
	    <literal>BSSID</literal> which is the MAC address of the
	    access point.  The <literal>CAPS</literal> field
	    identifies the type of each network and the capabilities
	    of the stations operating there:</para>

	  <variablelist>
	    <varlistentry>
	      <term><literal>E</literal></term>

	      <listitem>
		<para>Extended Service Set (ESS).  Indicates that the
		  station is part of an infrastructure network (in
		  contrast to an IBSS/ad-hoc network).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>I</literal></term>

	      <listitem>
		<para>IBSS/ad-hoc network.  Indicates that the station
		  is part of an ad-hoc network (in contrast to an ESS
		  network).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>P</literal></term>

	      <listitem>
		<para>Privacy.  Data confidentiality is required for
		  all data frames exchanged within the BSS.  This means
		  that this BSS requires the station to use
		  cryptographic means such as WEP, TKIP or AES-CCMP to
		  encrypt/decrypt data frames being exchanged with
		  others.</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>S</literal></term>

	      <listitem>
		<para>Short Preamble.  Indicates that the network is
		  using short preambles (defined in 802.11b High
		  Rate/DSSS PHY, short preamble utilizes a 56 bit sync
		  field in contrast to a 128 bit field used in long
		  preamble mode).</para>
	      </listitem>
	    </varlistentry>

	    <varlistentry>
	      <term><literal>s</literal></term>

	      <listitem>
		<para>Short slot time.  Indicates that the 802.11g
		  network is using a short slot time because there are
		  no legacy (802.11b) stations present.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>

	  <para>One can also display the current list of known
	    networks with:</para>

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> list scan</userinput></screen>

	  <para>This information may be updated automatically by the
	    adapter or manually with a <option>scan</option> request.
	    Old data is automatically removed from the cache, so over
	    time this list may shrink unless more scans are
	    done.</para>
	</sect4>

	<sect4>
	  <title>Basic Settings</title>

	  <para>This section provides a simple example of how to make
	    the wireless network adapter work in &os; without
	    encryption.  After you are familiar with these concepts,
	    we strongly recommend using <link
	    linkend="network-wireless-wpa">WPA</link> to set up your
	    wireless network.</para>

	  <para>There are three basic steps to configure a wireless
	    network: selecting an access point, authenticating your
	    station, and configuring an IP address.  The following
	    sections discuss each step.</para>

	  <sect5>
	    <title>Selecting an Access Point</title>

	    <para>Most of time it is sufficient to let the system
	      choose an access point using the builtin heuristics.
	      This is the default behaviour when you mark an interface
	      up or otherwise configure an interface by listing it in
	      <filename>/etc/rc.conf</filename>, e.g.:</para>

	    <programlisting>ifconfig_ath0="DHCP"</programlisting>

	    <para>If there are multiple access points and you want to
	      select a specific one, you can select it by its
	      SSID:</para>

	    <programlisting>ifconfig_ath0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>

	    <para>In an environment where there are multiple access
	      points with the same SSID (often done to simplify
	      roaming) it may be necessary to associate to one
	      specific device.  In this case you can also specify the
	      BSSID of the access point (you can also leave off the
	      SSID):</para>

	    <programlisting>ifconfig_ath0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting>

	    <para>There are other ways to constrain the choice of an
	      access point such as limiting the set of frequencies the
	      system will scan on.  This may be useful if you have a
	      multi-band wireless card as scanning all the possible
	      channels can be time-consuming.  To limit operation to a
	      specific band you can use the <option>mode</option>
	      parameter; e.g.:</para>

	    <programlisting>ifconfig_ath0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>

	    <para>will force the card to operate in 802.11g which is
	      defined only for 2.4GHz frequencies so any 5GHz channels
	      will not be considered.  Other ways to do this are the
	      <option>channel</option> parameter, to lock operation to
	      one specific frequency, and the
	      <option>chanlist</option> parameter, to specify a list
	      of channels for scanning.  More information about these
	      parameters can be found in the &man.ifconfig.8; manual
	      page.</para>
	  </sect5>

	  <sect5>
	    <title>Authentication</title>

	    <para>Once you have selected an access point your station
	      needs to authenticate before it can pass data.
	      Authentication can happen in several ways.  The most
	      common scheme used is termed open authentication and
	      allows any station to join the network and communicate.
	      This is the authentication you should use for test
	      purpose the first time you set up a wireless network.
	      Other schemes require cryptographic handshakes be
	      completed before data traffic can flow; either using
	      pre-shared keys or secrets, or more complex schemes that
	      involve backend services such as RADIUS.  Most users
	      will use open authentication which is the default
	      setting.  Next most common setup is WPA-PSK, also known
	      as WPA Personal, which is described <link
	      linkend="network-wireless-wpa-wpa-psk">below</link>.</para>

	    <note>
	      <para>If you have an &apple; &airport; Extreme base
		station for an access point you may need to configure
		shared-key authentication together with a WEP key.
		This can be done in the
		<filename>/etc/rc.conf</filename> file or using the
		&man.wpa.supplicant.8; program.  If you have a single
		&airport; base station you can setup access with
		something like:</para>

	      <programlisting>ifconfig_ath0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting>

	      <para>In general shared key authentication is to be
		avoided because it uses the WEP key material in a
		highly-constrained manner making it even easier to
		crack the key.  If WEP must be used (e.g., for
		compatibility with legacy devices) it is better to use
		WEP with <literal>open</literal> authentication.  More
		information regarding WEP can be found in the <xref
		linkend="network-wireless-wep"/>.</para>
	    </note>
	  </sect5>

	  <sect5>
	    <title>Getting an IP Address with DHCP</title>

	    <para>Once you have selected an access point and set the
	      authentication parameters, you will have to get an IP
	      address to communicate.  Most of time you will obtain
	      your wireless IP address via DHCP.  To achieve that,
	      simply edit <filename>/etc/rc.conf</filename> and add
	      <literal>DHCP</literal> to the configuration for your
	      device as shown in various examples above:</para>

	    <programlisting>ifconfig_ath0="DHCP"</programlisting>

	    <para>At this point, you are ready to bring up the
	      wireless interface:</para>

	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput></screen>

	    <para>Once the interface is running, use
	      <command>ifconfig</command> to see the status of the
	      interface <devicename>ath0</devicename>:</para>

	    <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
        inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
        inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
        ether 00:11:95:d5:43:62
        media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps)
        status: associated
        ssid dlinkap channel 6 bssid 00:13:46:49:41:76
        authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen>

	    <para>The <literal>status: associated</literal> means you
	      are connected to the wireless network (to the
	      <literal>dlinkap</literal> network in our case).  The
	      <literal>bssid 00:13:46:49:41:76</literal> part is the
	      MAC address of your access point; the
	      <literal>authmode</literal> line informs you that the
	      communication is not encrypted
	      (<literal>OPEN</literal>).</para>
	  </sect5>

	  <sect5>
	    <title>Static IP Address</title>

	    <para>In the case you cannot obtain an IP address from a
	      DHCP server, you can set a fixed IP address.  Replace
	      the <literal>DHCP</literal> keyword shown above with the
	      address information.  Be sure to retain any other
	      parameters you have set up for selecting an access
	      point:</para>

	    <programlisting>ifconfig_ath0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting>
	  </sect5>
	</sect4>

	<sect4 id="network-wireless-wpa">
	  <title>WPA</title>

	  <para>WPA (Wi-Fi Protected Access) is a security protocol
	    used together with 802.11 networks to address the lack of
	    proper authentication and the weakness of <link
	    linkend="network-wireless-wep">WEP</link>.  WPA leverages
	    the 802.1X authentication protocol and uses one of several
	    ciphers instead of WEP for data integrity.  The only
	    cipher required by WPA is TKIP (Temporary Key Integrity
	    Protocol) which is a cipher that extends the basic RC4
	    cipher used by WEP by adding integrity checking, tamper
	    detection, and measures for responding to any detected
	    intrusions.  TKIP is designed to work on legacy hardware
	    with only software modification; it represents a
	    compromise that improves security but is still not
	    entirely immune to attack.  WPA also specifies the
	    AES-CCMP cipher as an alternative to TKIP and that is
	    preferred when possible; for this specification the term
	    WPA2 (or RSN) is commonly used.</para>

	  <para>WPA defines authentication and encryption protocols.
	    Authentication is most commonly done using one of two
	    techniques: by 802.1X and a backend authentication service
	    such as RADIUS, or by a minimal handshake between the
	    station and the access point using a pre-shared secret.
	    The former is commonly termed WPA Enterprise with the
	    latter known as WPA Personal.  Since most people will not
	    set up a RADIUS backend server for wireless network,
	    WPA-PSK is by far the most commonly encountered
	    configuration for WPA.</para>

	  <para>The control of the wireless connection and the
	    authentication (key negotiation or authentication with a
	    server) is done with the &man.wpa.supplicant.8; utility.
	    This program requires a configuration file,
	    <filename>/etc/wpa_supplicant.conf</filename>, to run.
	    More information regarding this file can be found in the
	    &man.wpa.supplicant.conf.5; manual page.</para>

	  <sect5 id="network-wireless-wpa-wpa-psk">
	    <title>WPA-PSK</title>

	    <para>WPA-PSK also known as WPA-Personal is based on a
	      pre-shared key (PSK) generated from a given password and
	      that will be used as the master key in the wireless
	      network.  This means every wireless user will share the
	      same key.  WPA-PSK is intended for small networks where
	      the use of an authentication server is not possible or
	      desired.</para>

	    <warning>
	      <para>Always use strong passwords that are
		sufficiently long and made from a rich alphabet so
		they will not be guessed and/or attacked.</para>
	    </warning>

	    <para>The first step is the configuration of the
	      <filename>/etc/wpa_supplicant.conf</filename> file with
	      the SSID and the pre-shared key of your network:</para>

	    <programlisting>network={
  ssid="freebsdap"
  psk="freebsdmall"
}</programlisting>

	    <para>Then, in <filename>/etc/rc.conf</filename>, we
	      indicate that the wireless device configuration will be
	      done with WPA and the IP address will be obtained with
	      DHCP:</para>

	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>

	    <para>Then, we can bring up the interface:</para>

	    <screen>&prompt.root; <userinput><filename>/etc/rc.d/netif</filename> start</userinput>
Starting wpa_supplicant.
DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 5
DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 6
DHCPOFFER from 192.168.0.1
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.1
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      ether 00:11:95:d5:43:62
      media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps)
      status: associated
      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
      authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
      protmode CTS roaming MANUAL bintval 100</screen>

	    <para>Or you can try to configure it manually using the
	      same <filename>/etc/wpa_supplicant.conf</filename> <link
	      linkend="network-wireless-wpa-wpa-psk">above</link>, and
	      run:</para>

	    <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>ath0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz)
Associated with 00:11:95:c3:0d:ac
WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=TKIP GTK=TKIP]</screen>

	    <para>The next operation is the launch of the
	      <command>dhclient</command> command to get the IP
	      address from the DHCP server:</para>

	    <screen>&prompt.root; <userinput>dhclient <replaceable>ath0</replaceable></userinput>
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.1
bound to 192.168.0.254 -- renewal in 300 seconds.
&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      ether 00:11:95:d5:43:62
      media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/48Mbps)
      status: associated
      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
      authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
      protmode CTS roaming MANUAL bintval 100</screen>

	    <note>
	      <para>If the <filename>/etc/rc.conf</filename> is set up
		with the line <literal>ifconfig_ath0="DHCP"</literal>
		then it is no need to run the
		<command>dhclient</command> command manually,
		<command>dhclient</command> will be launched after
		<command>wpa_supplicant</command> plumbs the
		keys.</para>
	    </note>

	    <para>In the case where the use of DHCP is not possible,
	      you can set a static IP address after
	      <command>wpa_supplicant</command> has authenticated the
	      station:</para>

	    <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
      inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255
      ether 00:11:95:d5:43:62
      media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps)
      status: associated
      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
      authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36
      protmode CTS roaming MANUAL bintval 100</screen>

	    <para>When DHCP is not used, you also have to manually set
	      up the default gateway and the nameserver:</para>

	    <screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput>
&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" &gt;&gt; /etc/resolv.conf</userinput></screen>
	  </sect5>

	  <sect5 id="network-wireless-wpa-eap-tls">
	    <title>WPA with EAP-TLS</title>

	    <para>The second way to use WPA is with an 802.1X backend
	      authentication server, in this case WPA is called
	      WPA-Enterprise to make difference with the less secure
	      WPA-Personal with its pre-shared key.  The
	      authentication in WPA-Enterprise is based on EAP
	      (Extensible Authentication Protocol).</para>

	    <para>EAP does not come with an encryption method, it was
	      decided to embed EAP inside an encrypted tunnel.  Many
	      types of EAP authentication methods have been designed,
	      the most common methods are EAP-TLS, EAP-TTLS and
	      EAP-PEAP.</para>

	    <para>EAP-TLS (EAP with Transport Layer Security) is a
	      very well-supported authentication protocol in the
	      wireless world since it was the first EAP method to be
	      certified by the <ulink
	      url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>.
	      EAP-TLS will require three certificates to run: the CA
	      certificate (installed on all machines), the server
	      certificate for your authentication server, and one
	      client certificate for each wireless client.  In this
	      EAP method, both authentication server and wireless
	      client authenticate each other in presenting their
	      respective certificates, and they verify that these
	      certificates were signed by your organization's
	      certificate authority (CA).</para>

	    <para>As previously, the configuration is done via
	      <filename>/etc/wpa_supplicant.conf</filename>:</para>

	    <programlisting>network={
  ssid="freebsdap" <co id="co-tls-ssid"/>
  proto=RSN  <co id="co-tls-proto"/>
  key_mgmt=WPA-EAP <co id="co-tls-kmgmt"/>
  eap=TLS <co id="co-tls-eap"/>
  identity="loader" <co id="co-tls-id"/>
  ca_cert="/etc/certs/cacert.pem" <co id="co-tls-cacert"/>
  client_cert="/etc/certs/clientcert.pem" <co id="co-tls-clientcert"/>
  private_key="/etc/certs/clientkey.pem" <co id="co-tls-pkey"/>
  private_key_passwd="freebsdmallclient" <co id="co-tls-pwd"/>
}</programlisting>

	    <calloutlist>
	      <callout arearefs="co-tls-ssid">
		<para>This field indicates the network name
		  (SSID).</para>
	      </callout>

	      <callout arearefs="co-tls-proto">
		<para>Here, we use RSN (IEEE 802.11i) protocol, i.e.,
		  WPA2.</para>
	      </callout>

	      <callout arearefs="co-tls-kmgmt">
		<para>The <literal>key_mgmt</literal> line refers to
		  the key management protocol we use.  In our case it
		  is WPA using EAP authentication:
		  <literal>WPA-EAP</literal>.</para>
	      </callout>

	      <callout arearefs="co-tls-eap">
		<para>In this field, we mention the EAP method for our
		  connection.</para>
	      </callout>

	      <callout arearefs="co-tls-id">
		<para>The <literal>identity</literal> field contains
		  the identity string for EAP.</para>
	      </callout>

	      <callout arearefs="co-tls-cacert">
		<para>The <literal>ca_cert</literal> field indicates
		  the pathname of the CA certificate file.  This file
		  is needed to verify the server certificat.</para>
	      </callout>

	      <callout arearefs="co-tls-clientcert">
		<para>The <literal>client_cert</literal> line gives
		  the pathname to the client certificate file.  This
		  certificate is unique to each wireless client of the
		  network.</para>
	      </callout>

	      <callout arearefs="co-tls-pkey">
		<para>The <literal>private_key</literal> field is the
		  pathname to the client certificate private key
		  file.</para>
	      </callout>

	      <callout arearefs="co-tls-pwd">
		<para>The <literal>private_key_passwd</literal> field
		  contains the passphrase for the private key.</para>
	      </callout>
	    </calloutlist>

	    <para>Then add the following line to
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>

	    <para>The next step is to bring up the interface with the
	      help of the <filename>rc.d</filename> facility:</para>

	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
Starting wpa_supplicant.
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      ether 00:11:95:d5:43:62
      media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
      status: associated
      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
      authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
      txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen>

	    <para>As previously shown, it is also possible to bring up
	      the interface manually with both
	      <command>wpa_supplicant</command> and
	      <command>ifconfig</command> commands.</para>
	  </sect5>

	  <sect5 id="network-wireless-wpa-eap-ttls">
	    <title>WPA with EAP-TTLS</title>

	    <para>With EAP-TLS both the authentication server and the
	      client need a certificate, with EAP-TTLS (EAP-Tunneled
	      Transport Layer Security) a client certificate is
	      optional.  This method is close to what some secure web
	      sites do , where the web server can create a secure SSL
	      tunnel even if the visitors do not have client-side
	      certificates.  EAP-TTLS will use the encrypted TLS
	      tunnel for safe transport of the authentication
	      data.</para>

	    <para>The configuration is done via the
	      <filename>/etc/wpa_supplicant.conf</filename>
	      file:</para>

	    <programlisting>network={
  ssid="freebsdap"
  proto=RSN
  key_mgmt=WPA-EAP
  eap=TTLS <co id="co-ttls-eap"/>
  identity="test" <co id="co-ttls-id"/>
  password="test" <co id="co-ttls-passwd"/>
  ca_cert="/etc/certs/cacert.pem" <co id="co-ttls-cacert"/>
  phase2="auth=MD5" <co id="co-ttls-pha2"/>
}</programlisting>

	    <calloutlist>
	      <callout arearefs="co-ttls-eap">
		<para>In this field, we mention the EAP method for our
		  connection.</para>
	      </callout>

	      <callout arearefs="co-ttls-id">
		<para>The <literal>identity</literal> field contains
		  the identity string for EAP authentication inside
		  the encrypted TLS tunnel.</para>
	      </callout>

	      <callout arearefs="co-ttls-passwd">
		<para>The <literal>password</literal> field contains
		  the passphrase for the EAP authentication.</para>
	      </callout>

	      <callout arearefs="co-ttls-cacert">
		<para>The <literal>ca_cert</literal> field indicates
		  the pathname of the CA certificate file.  This file
		  is needed to verify the server certificat.</para>
	      </callout>

	      <callout arearefs="co-ttls-pha2">
		<para>In this field, we mention the authentication
		  method used in the encrypted TLS tunnel.  In our
		  case, EAP with MD5-Challenge has been used.  The
		  <quote>inner authentication</quote> phase is often
		  called <quote>phase2</quote>.</para>
	      </callout>
	    </calloutlist>

	    <para>You also have to add the following line to
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>

	    <para>The next step is to bring up the interface:</para>

	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
Starting wpa_supplicant.
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      ether 00:11:95:d5:43:62
      media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
      status: associated
      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
      authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
      txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen>
	  </sect5>

	  <sect5 id="network-wireless-wpa-eap-peap">
	    <title>WPA with EAP-PEAP</title>

	    <para>PEAP (Protected EAP) has been designed as an
	      alternative to EAP-TTLS.  There are two types of PEAP
	      methods, the most common one is PEAPv0/EAP-MSCHAPv2.  In
	      the rest of this document, we will use the PEAP term to
	      refer to that EAP method.  PEAP is the most used EAP
	      standard after EAP-TLS, in other words if you have a
	      network with mixed OSes, PEAP should be the most
	      supported standard after EAP-TLS.</para>

	    <para>PEAP is similar to EAP-TTLS: it uses a server-side
	      certificate to authenticate clients by creating an
	      encrypted TLS tunnel between the client and the
	      authentication server, which protects the ensuing
	      exchange of authentication information.  In term of
	      security the difference between EAP-TTLS and PEAP is
	      that PEAP authentication broadcasts the username in
	      clear, only the password is sent in the encrypted TLS
	      tunnel.  EAP-TTLS will use the TLS tunnel for both
	      username and password.</para>

	    <para>We have to edit the
	      <filename>/etc/wpa_supplicant.conf</filename> file and
	      add the EAP-PEAP related settings:</para>

	    <programlisting>network={
  ssid="freebsdap"
  proto=RSN
  key_mgmt=WPA-EAP
  eap=PEAP <co id="co-peap-eap"/>
  identity="test" <co id="co-peap-id"/>
  password="test" <co id="co-peap-passwd"/>
  ca_cert="/etc/certs/cacert.pem" <co id="co-peap-cacert"/>
  phase1="peaplabel=0" <co id="co-peap-pha1"/>
  phase2="auth=MSCHAPV2" <co id="co-peap-pha2"/>
}</programlisting>

	    <calloutlist>
	      <callout arearefs="co-peap-eap">
		<para>In this field, we mention the EAP method for our
		  connection.</para>
	      </callout>

	      <callout arearefs="co-peap-id">
		<para>The <literal>identity</literal> field contains
		  the identity string for EAP authentication inside
		  the encrypted TLS tunnel.</para>
	      </callout>

	      <callout arearefs="co-peap-passwd">
		<para>The <literal>password</literal> field contains
		  the passphrase for the EAP authentication.</para>
	      </callout>

	      <callout arearefs="co-peap-cacert">
		<para>The <literal>ca_cert</literal> field indicates
		  the pathname of the CA certificate file.  This file
		  is needed to verify the server certificat.</para>
	      </callout>

	      <callout arearefs="co-peap-pha1">
		<para>This field contains the parameters for the
		  first phase of the authentication (the TLS
		  tunnel).  According to the authentication server
		  used, you will have to specify a specific label
		  for the authentication.  Most of time, the label
		  will be <quote>client EAP encryption</quote> which
		  is set by using <literal>peaplabel=0</literal>.
		  More information can be found in the
		  &man.wpa.supplicant.conf.5; manual page.</para>
	      </callout>

	      <callout arearefs="co-peap-pha2">
		<para>In this field, we mention the authentication
		  protocol used in the encrypted TLS tunnel.  In the
		  case of PEAP, it is
		  <literal>auth=MSCHAPV2</literal>.</para>
	      </callout>
	    </calloutlist>

	    <para>The following must be added to
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>ifconfig_ath0="WPA DHCP"</programlisting>

	    <para>Then, we can bring up the interface:</para>

	    <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput>
Starting wpa_supplicant.
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPREQUEST on ath0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      ether 00:11:95:d5:43:62
      media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps)
      status: associated
      ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
      authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit
      txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen>
	  </sect5>
	</sect4>

	<sect4 id="network-wireless-wep">
	  <title>WEP</title>

	  <para>WEP (Wired Equivalent Privacy) is part of the original
	    802.11 standard.  There is no authentication mechanism,
	    only a weak form of access control, and it is easily to be
	    cracked.</para>

	  <para>WEP can be set up with
	    <command>ifconfig</command>:</para>

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid my_net \
	    wepmode on weptxkey 3 wepkey 3:0x3456789012</userinput></screen>

	  <itemizedlist>
	    <listitem>
	      <para>The <literal>weptxkey</literal> means which WEP
		key will be used in the transmission.  Here we used the
		third key.  This must match the setting in the access
		point.</para>
	    </listitem>

	    <listitem>
	      <para>The <literal>wepkey</literal> means setting the
		selected WEP key.  It should in the format
		<replaceable>index:key</replaceable>, if the index is
		not given, key <literal>1</literal> is set.  That is
		to say we need to set the index if we use keys other
		than the first key.</para>

	      <note>
		<para>You must replace
		  the <literal>0x3456789012</literal> with the key
		  configured for use on the access point.</para>
	      </note>
	    </listitem>
	  </itemizedlist>

	  <para>You are encouraged to read &man.ifconfig.8; manual
	    page for further information.</para>

	  <para>The <command>wpa_supplicant</command> facility also
	    can be used to configure your wireless interface with WEP.
	    The example above can be set up by adding the following
	    lines to
	    <filename>/etc/wpa_supplicant.conf</filename>:</para>

	  <programlisting>network={
  ssid="my_net"
  key_mgmt=NONE
  wep_key3=3456789012
  wep_tx_keyidx=3
}</programlisting>

	  <para>Then:</para>

	  <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>ath0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz)
Associated with 00:13:46:49:41:76</screen>
	</sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>Ad-hoc Mode</title>

      <para>IBSS mode, also called ad-hoc mode, is designed for point
	to point connections.  For example, to establish an ad-hoc
	network between the machine <hostid>A</hostid> and the machine
	<hostid>B</hostid> we will just need to choose two IP adresses
	and a SSID.</para>

      <para>On the box <hostid>A</hostid>:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mediaopt adhoc</userinput>
&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
  ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	  inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
	  ether 00:11:95:c3:0d:ac
	  media: IEEE 802.11 Wireless Ethernet autoselect &lt;adhoc&gt; (autoselect &lt;adhoc&gt;)
	  status: associated
	  ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac
	  authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen>

      <para>The <literal>adhoc</literal> parameter indicates the
	interface is running in the IBSS mode.</para>

      <para>On <hostid>B</hostid>, we should be able to detect
	<hostid>A</hostid>:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput>
  SSID            BSSID              CHAN RATE  S:N   INT CAPS
  freebsdap       02:11:95:c3:0d:ac    2   54M 19:0   100 IS</screen>

      <para>The <literal>I</literal> in the output confirms the
	machine <hostid>A</hostid> is in ad-hoc mode.  We just have to
	configure <hostid>B</hostid> with a different IP
	address:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mediaopt adhoc</userinput>
&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput>
  ath0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
	  inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1
	  inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
	  ether 00:11:95:d5:43:62
	  media: IEEE 802.11 Wireless Ethernet autoselect &lt;adhoc&gt; (autoselect &lt;adhoc&gt;)
	  status: associated
	  ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac
	  authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen>

	  <para>Both <hostid>A</hostid> and <hostid>B</hostid> are now
	    ready to exchange informations.</para>
    </sect2>

    <sect2>
      <title>Troubleshooting</title>

      <para>If you are having trouble with wireless networking, there
	are a number of steps you can take to help troubleshoot the
	problem.</para>

      <itemizedlist>
	<listitem>
	  <para>If you do not see the access point listed when
	    scanning be sure you have not configured your wireless
	    device to a limited set of channels.</para>
	</listitem>

	<listitem>
	  <para>If you cannot associate to an access point verify the
	    configuration of your station matches the one of the
	    access point.  This includes the authentication scheme and
	    any security protocols.  Simplify your configuration as
	    much as possible.  If you are using a security protocol
	    such as WPA or WEP configure the access point for open
	    authentication and no security to see if you can get
	    traffic to pass.</para>
	</listitem>

	<listitem>
	  <para>Once you can associate to the access point diagnose
	    any security configuration using simple tools like
	    &man.ping.8;.</para>

	  <para>The <command>wpa_supplicant</command> has much
	    debugging support; try running it manually with the
	    <option>-dd</option> option and look at the system
	    logs.</para>
	</listitem>

	<listitem>
	  <para>There are also many lower-level debugging tools.  You
	    can enable debugging messages in the 802.11 protocol
	    support layer using the <command>wlandebug</command>
	    program found in
	    <filename>/usr/src/tools/tools/net80211</filename>.  For
	    example:</para>

	  <screen>&prompt.root; <userinput>wlandebug -i <replaceable>ath0</replaceable> +scan+auth+debug+assoc</userinput>
  net.wlan.0.debug: 0 =&gt; 0xc80000&lt;assoc,auth,scan&gt;</screen>

	  <para>can be used to enable console messages related to
	    scanning for access points and doing the 802.11 protocol
	    handshakes required to arrange communication.</para>

	  <para>There are also many useful statistics maintained by
	    the 802.11 layer; the <command>wlanstats</command> tool
	    will dump these informations.  These statistics should
	    identify all errors identified by the 802.11 layer.
	    Beware however that some errors are identified in the
	    device drivers that lie below the 802.11 layer so they may
	    not show up.  To diagnose device-specific problems you
	    need to refer to the drivers' documentation.</para>
	</listitem>
      </itemizedlist>

      <para>If the above information does not help to clarify the
	problem, please submit a problem report and include output
	from the above tools.</para>
    </sect2>
  </sect1>

  <sect1 id="network-bluetooth">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Pav</firstname>
          <surname>Lucistnik</surname>
          <contrib>Written by </contrib>
          <affiliation>
	    <address><email>pav@FreeBSD.org</email></address>
          </affiliation>
        </author>
      </authorgroup>
    </sect1info>
    <title>Bluetooth</title>

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

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

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

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

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

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

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

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

      <note>
	<para>The Bluetooth stack has to be started manually on &os; 6.0, and
	  on &os; 5.X before 5.5.  It is done automatically from &man.devd.8;
	  on &os; 5.5, 6.1 and newer.</para>

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

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

    </sect2>

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

      <indexterm><primary>HCI</primary></indexterm>

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

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

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

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

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

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

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

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

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

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

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

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

    </sect2>

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

      <indexterm><primary>L2CAP</primary></indexterm>

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

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

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

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

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

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

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

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

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

    </sect2>

    <sect2>
      <title>RFCOMM Protocol</title>

      <indexterm><primary>RFCOMM</primary></indexterm>

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

    <sect2>
      <title>Pairing of Devices</title>

      <indexterm><primary>pairing</primary></indexterm>

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

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

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

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

      <para>On &os; 5.5, 6.1 and newer, the following line can be added to the
	<filename>/etc/rc.conf</filename> file to have
	<application>hcsecd</application> started automatically on system
	start:</para>

      <programlisting>hcsecd_enable="YES"</programlisting>

      <para>The following is a sample of the
        <application>hcsecd</application> daemon output:</para>

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

    </sect2>

    <sect2>
      <title>Service Discovery Protocol (SDP)</title>

      <indexterm><primary>SDP</primary></indexterm>

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

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

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

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

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

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

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

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

      <para>Offering services on &os; to Bluetooth clients is done with the
	&man.sdpd.8; server. On &os; 5.5, 6.1 and newer, the following line can
	be added to the <filename>/etc/rc.conf</filename> file:</para>

      <programlisting>sdpd_enable="YES"</programlisting>

      <para>Then the <application>sdpd</application> daemon can be started with:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/sdpd start</userinput></screen>

      <para>On &os; 6.0, and on &os; 5.X before 5.5,
	<application>sdpd</application> is not integrated into the system
	startup scripts.  It has to be started manually with:</para>

      <screen>&prompt.root; <userinput>sdpd</userinput></screen>

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

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

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

    </sect2>

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

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

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

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

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

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

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

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

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

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

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

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

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

    </sect2>

    <sect2>
      <title>OBEX Object Push (OPUSH) Profile</title>

      <indexterm><primary>OBEX</primary></indexterm>

      <para>OBEX is a widely used protocol for simple file transfers between
        mobile devices. Its main use is in infrared communication, where it is
        used for generic file transfers between notebooks or PDAs,
        and for sending business cards or calendar entries between cellular
        phones and other devices with PIM applications.</para>

      <para>The OBEX server and client are implemented as a third-party package
        <application>obexapp</application>, which is available as
	<filename role="package">comms/obexapp</filename> port.</para>

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

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

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

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

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

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

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

      <para>Once connected, the pseudo tty can be used as serial port:</para>

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

    </sect2>

    <sect2>
      <title>Troubleshooting</title>

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

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

      </sect3>

      <sect3>
        <title>Something is going wrong, can I see what exactly is happening?</title>
        <para>Yes, you can.  Use the third-party package
          <application>hcidump</application>, which is available as
	  <filename role="package">comms/hcidump</filename> port.
          The <application>hcidump</application> utility is similar to
          &man.tcpdump.1;. It can be used to display the content of the Bluetooth
          packets on the terminal and to dump the Bluetooth packets to a
          file.</para>
      </sect3>

    </sect2>

  </sect1>

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

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

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

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

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

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

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

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

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

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

      <sect3>
	<title>Filtering/Traffic Shaping Firewall</title>
	<indexterm><primary>firewall</primary></indexterm>
	<indexterm><primary>NAT</primary></indexterm>

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

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

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

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

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

	<para>A bridge requires at least two network cards to function.
	  Unfortunately, not all network interface cards
	  support bridging.  Read &man.bridge.4; for details on the cards that
	  are supported.</para>

	<para>Install and test the two network cards before continuing.</para>
      </sect3>

      <sect3>
	<title>Kernel Configuration Changes</title>
	<indexterm>
	  <primary>kernel options</primary>
	  <secondary>BRIDGE</secondary>
	</indexterm>

	<para>To enable kernel support for bridging, add the:</para>

	<programlisting>options BRIDGE</programlisting>

	<para>statement to your kernel configuration file, and rebuild your
	  kernel.</para>
      </sect3>

      <sect3>
	<title>Firewall Support</title>
	<indexterm><primary>firewall</primary></indexterm>
	<para>If you are planning to use the bridge as a firewall, you
	  will need to add the <literal>IPFIREWALL</literal> option as
	  well.  Read <xref linkend="firewalls"/> for general
	  information on configuring the bridge as a firewall.</para>

	<para>If you need to allow non-IP packets (such as ARP) to flow
	  through the bridge, there are three options available.
	  The first is to add the following option to the kernel and
	  rebuild:</para>

	<programlisting>option	IPFIREWALL_DEFAULT_TO_ACCEPT</programlisting>

	<para>The second is to set the firewall type to <quote><literal>open</literal></quote> in the
	  <filename>rc.conf</filename> file:</para>

	<programlisting>firewall_type="open"</programlisting>

	<para>Note that these options will make the firewall seem completely
	  transparent; any packet or connection will be permitted by default.
	  This may require significant changes to the firewall ruleset.</para>

	<para>The third option is to apply the following &man.ipfw.8;
	  rule:</para>

	<screen>&prompt.root; <userinput>ipfw add allow mac-type arp layer2</userinput></screen>

	<para>Or add it to the current firewall ruleset.  This rule effectively
	  allows &man.arp.8; packets through, so it must be be applied near the
	  beginning of the ruleset for early evaluation.</para>
      </sect3>

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

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

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

      <para>Add the line:</para>

      <programlisting>net.link.ether.bridge.enable=1</programlisting>

      <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
	runtime, and the line:</para>

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

      <para>to enable bridging on the specified interfaces (replace
	<replaceable>if1</replaceable> and
	<replaceable>if2</replaceable> with the names of your two
	network interfaces).  If you want the bridged packets to be
	filtered by &man.ipfw.8;, you should add:</para>

      <programlisting>net.link.ether.bridge.ipfw=1</programlisting>

      <para>as well.</para>

      <para>For versions prior to &os;&nbsp;5.2-RELEASE, use instead the following
	lines:</para>

      <programlisting>net.link.ether.bridge=1
net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable>
net.link.ether.bridge_ipfw=1</programlisting>

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

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

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

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

  <sect1 id="network-diskless">
    <sect1info>
      <authorgroup>
        <author>
          <firstname>Jean-Fran&ccedil;ois</firstname>
          <surname>Dock&egrave;s</surname>
          <contrib>Updated by </contrib>
        </author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Alex</firstname>
	  <surname>Dupre</surname>
	  <contrib>Reorganized and enhanced by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Diskless Operation</title>

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

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

      <listitem>
	<para>A sample script
	  (<filename>/usr/share/examples/diskless/clone_root</filename>) eases
	  the creation and maintenance of the workstation's root file system
	  on the server.  The script will probably require a little
	  customization but it will get you started very quickly.</para>
      </listitem>

      <listitem>
	<para>Standard system startup files exist in <filename>/etc</filename>
	  to detect and support a diskless system startup.</para>
      </listitem>

      <listitem>
	<para>Swapping, if needed, can be done either to an <acronym>NFS</acronym> file or to
	  a local disk.</para>
      </listitem>
    </itemizedlist>

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

    <itemizedlist>
      <listitem>
	<para>The diskless workstations use a shared
	  read-only <filename>/</filename> file system, and a shared
	  read-only <filename>/usr</filename>.</para>
	<para>The root file system is a copy of a
	  standard FreeBSD root (typically the server's), with some
	  configuration files overridden by ones specific to diskless
	  operation or, possibly, to the workstation they belong to.</para>
	<para>The parts of the root which have to be
	  writable are overlaid with &man.md.4; file systems.  Any changes
	  will be lost when the system reboots.</para>
      </listitem>
      <listitem>
	<para>The kernel is transferred and loaded either with
	  <application>Etherboot</application> or <acronym>PXE</acronym>
	  as some situations may mandate the use of either method.</para>
      </listitem>
    </itemizedlist>

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

    <para>All the information in this section has been tested
      using &os; 5.2.1-RELEASE.</para>

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

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

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

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

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

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

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

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

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

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

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

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

	  <para><acronym>PXE</acronym> and <application>Etherboot</application>
	    work equally well; however, because kernels
	    normally let the &man.loader.8; do more work for them,
	    <acronym>PXE</acronym> is the preferred method.</para>

	  <para>If your <acronym>BIOS</acronym> and network cards support
	    <acronym>PXE</acronym>, you should probably use it.</para>
	</listitem>

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

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

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

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

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

	  <para><application>ISC DHCP
  	    3.0</application> is not part of the base
	    system.  You will first need to install the
	    <filename role="package">net/isc-dhcp3-server</filename> port or the
	    corresponding package.</para>

	  <para>Once <application>ISC DHCP</application> is installed, it
	    needs a configuration file to run (normally named
	    <filename>/usr/local/etc/dhcpd.conf</filename>).  Here follows
	    a commented example, where host <hostid>margaux</hostid>
	    uses <application>Etherboot</application> and host
	    <hostid>corbieres</hostid> uses <acronym>PXE</acronym>:</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	<para>You must first install the <filename
	  role="package">net/etherboot</filename> package or port.</para>

	<para>You can change the <application>Etherboot</application>
	  configuration (i.e. to use <acronym>TFTP</acronym> instead of
	  <acronym>NFS</acronym>) by editing the <filename>Config</filename>
	  file in the <application>Etherboot</application> source
	  directory.</para>

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

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

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

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

      </sect3>

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

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

	<para>There are two other <filename>make.conf</filename>
	  options which may be useful for setting up a serial console diskless
	  machine: <literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and
	  <literal>BOOT_PXELDR_ALWAYS_SERIAL</literal>.</para>

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

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

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

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

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

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

	    <note><para>It appears that at least some <acronym>PXE</acronym> versions want
		the <acronym>TCP</acronym> version of <acronym>TFTP</acronym>.  In this case, add a second line,
		replacing <literal>dgram udp</literal> with <literal>stream
		tcp</literal>.</para>
	    </note>
          </step>
	  <step>
	    <para>Tell <application>inetd</application> to reread its configuration
	      file.  The <option>inetd_enable="YES"</option> must be in
	      the <filename>/etc/rc.conf</filename> file for this
	      command to execute correctly:</para>
	    <screen>&prompt.root; <userinput>/etc/rc.d/inetd restart</userinput></screen>
	  </step>
        </procedure>

	<para>You can place the <filename>tftpboot</filename>
	  directory anywhere on the server.  Make sure that the
	  location is set in both <filename>inetd.conf</filename> and
	  <filename>dhcpd.conf</filename>.</para>

	<para>In all cases, you also need to enable <acronym>NFS</acronym> and export the
	  appropriate file system on the <acronym>NFS</acronym> server.</para>

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

          <step>
            <para>Export the file system where the diskless root directory
	      is located by adding the following to
	      <filename>/etc/exports</filename> (adjust the volume mount
	      point and replace <replaceable>margaux corbieres</replaceable>
	      with the names of the diskless workstations):</para>

	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
          </step>
	  <step>
	    <para>Tell <application>mountd</application> to reread its configuration
	      file.  If you actually needed to enable <acronym>NFS</acronym> in
	      <filename>/etc/rc.conf</filename>
	      at the first step, you probably want to reboot instead.</para>
	    <screen>&prompt.root; <userinput>/etc/rc.d/mountd restart</userinput></screen>
	  </step>
        </procedure>

      </sect3>

      <sect3>
	<title>Building a Diskless Kernel</title>

	<indexterm>
	  <primary>diskless operation</primary>
	  <secondary>kernel configuration</secondary>
	</indexterm>

	<para>If using <application>Etherboot</application>, you need to
	  create a kernel configuration file for the diskless client
	  with the following options (in addition to the usual ones):</para>

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

	<para>You may also want to use <literal>BOOTP_NFSV3</literal>,
	  <literal>BOOT_COMPAT</literal> and <literal>BOOTP_WIRED_TO</literal>
	  (refer to <filename>NOTES</filename>).</para>

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

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

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

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

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

      </sect3>

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

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

	<para>You need to create a root file system for the diskless
	  workstations, in the location listed as
	  <literal>root-path</literal> in
	  <filename>dhcpd.conf</filename>.</para>

	<sect4>
	  <title>Using <command>make world</command> to populate root</title>

	  <para>This method is quick and
	    will install a complete virgin system (not only the root file system)
	    into <envar>DESTDIR</envar>.
	    All you have to do is simply execute the following script:</para>

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

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

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

	<para>If needed, a swap file located on the server can be
	  accessed via <acronym>NFS</acronym>.</para>

	<sect4>
	  <title><acronym>NFS</acronym> Swap</title>

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

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

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

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

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


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

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

	    <para>If the diskless workstation is configured to run X, you
	    will have to adjust the <application>XDM</application> configuration file, which puts
	    the error log on <filename>/usr</filename> by default.</para>
	</sect4>
	<sect4>
	  <title>Using a Non-FreeBSD Server</title>

	  <para>When the server for the root file system is not running FreeBSD,
	    you will have to create the root file system on a
	    FreeBSD machine, then copy it to its destination, using
	    <command>tar</command> or <command>cpio</command>.</para>
	  <para>In this situation, there are sometimes
	    problems with the special files in <filename>/dev</filename>,
	    due to differing major/minor integer sizes.  A solution to this
	    problem is to export a directory from the non-FreeBSD server,
	    mount this directory onto a FreeBSD machine, and
	    use &man.devfs.5; to allocate device nodes transparently for
	    the user.</para>

	</sect4>

      </sect3>

    </sect2>
  </sect1>

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

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

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

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

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

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

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

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

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

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

      <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
	(or Euro-ISDN) standard using passive cards.  Some active cards
	are supported where the firmware
	also supports other signaling protocols; this also includes the
	first supported Primary Rate (PRI) ISDN card.</para>

      <para>The <application>isdn4bsd</application> software allows you to connect
	to other ISDN routers using either IP over raw HDLC or by using
	synchronous PPP: either by using kernel PPP with <literal>isppp</literal>, a
	modified &man.sppp.4; driver, or by using userland &man.ppp.8;.  By using
	userland &man.ppp.8;, channel bonding of two or more ISDN
	B-channels is possible.  A telephone answering machine
	application is also available as well as many utilities such as
	a software 300 Baud modem.</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2 id="network-natoverview">
      <title>Overview</title>
      <indexterm>
        <primary><application>natd</application></primary>
      </indexterm>
      <para>FreeBSD's Network Address Translation daemon, commonly known as
        &man.natd.8; is a daemon that accepts incoming raw IP packets,
        changes the source to the local machine and re-injects these packets
        back into the outgoing IP packet stream.  &man.natd.8; does this by changing
        the source IP address and port such that when data is received back,
        it is able to determine the original location of the data and forward
        it back to its original requester.</para>
      <indexterm><primary>Internet connection sharing</primary></indexterm>
      <indexterm><primary>NAT</primary></indexterm>
      <para>The most common use of NAT is to perform what is commonly known as
        Internet Connection Sharing.</para>
    </sect2>

    <sect2 id="network-natsetup">
      <title>Setup</title>
      <para>Due to the diminishing IP space in IPv4, and the increased number
        of users on high-speed consumer lines such as cable or DSL, people are
        increasingly in need of an Internet Connection Sharing solution.  The
        ability to connect several computers online through one connection and
        IP address makes &man.natd.8; a reasonable choice.</para>

      <para>Most commonly, a user has a machine connected to a cable or DSL
        line with one IP address and wishes to use this one connected computer to
        provide Internet access to several more over a LAN.</para>

      <para>To do this, the FreeBSD machine on the Internet must act as a
        gateway.  This gateway machine must have two NICs&mdash;one for connecting
        to the Internet router, the other connecting to a LAN.  All the
        machines on the LAN are connected through a hub or switch.</para>

      <note>
	<para>There are many ways to get a LAN connected to the Internet
	  through a &os; gateway.   This example will only cover a
	  gateway with at least two NICs.</para>
      </note>

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

	<textobject>
	  <literallayout class="monospaced">  _______       __________       ________
 |       |     |          |     |        |
 |  Hub  |-----| Client B |-----| Router |----- Internet
 |_______|     |__________|     |________|
     |
 ____|_____
|          |
| Client A |
|__________|</literallayout>
        </textobject>

	<textobject>
	  <phrase>Network Layout</phrase>
	</textobject>
      </mediaobject>

      <para>A setup like this is commonly used to share an Internet
        connection.  One of the <acronym>LAN</acronym> machines is
        connected to the Internet.  The rest of the machines access
        the Internet through that <quote>gateway</quote>
        machine.</para>
    </sect2>

    <sect2 id="network-natdkernconfiguration">
      <title>Configuration</title>

      <indexterm>
        <primary>kernel</primary>
	<secondary>configuration</secondary>
      </indexterm>

      <para>The following options must be in the kernel configuration
        file:</para>
      <programlisting>options IPFIREWALL
options IPDIVERT</programlisting>

      <para>Additionally, at choice, the following may also be suitable:</para>
      <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSE</programlisting>

      <para>The following must be in <filename>/etc/rc.conf</filename>:</para>

      <programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"/>
firewall_enable="YES" <co id="co-natd-firewall-enable"/>
firewall_type="OPEN" <co id="co-natd-firewall-type"/>
natd_enable="YES"
natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface"/>
natd_flags="" <co id="co-natd-natd-flags"/></programlisting>

      <calloutlist>
        <callout arearefs="co-natd-gateway-enable">
          <para>Sets up the machine to act as a gateway.  Running
            <command>sysctl net.inet.ip.forwarding=1</command> would
            have the same effect.</para>
	</callout>

        <callout arearefs="co-natd-firewall-enable">
          <para>Enables the firewall rules in
            <filename>/etc/rc.firewall</filename> at boot.</para>
	</callout>

        <callout arearefs="co-natd-firewall-type">
          <para>This specifies a predefined firewall ruleset that
            allows anything in.  See
            <filename>/etc/rc.firewall</filename> for additional
            types.</para>
	</callout>

        <callout arearefs="co-natd-natd-interface">
          <para>Indicates which interface to forward packets through
            (the interface connected to the Internet).</para>
	</callout>

        <callout arearefs="co-natd-natd-flags">
          <para>Any additional configuration options passed to
            &man.natd.8; on boot.</para>
	</callout>
      </calloutlist>

      <para>Having the previous options defined in
        <filename>/etc/rc.conf</filename> would run
        <command>natd -interface fxp0</command> at boot.  This can also
        be run manually.</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      <programlisting>-redirect_address localIP publicIP</programlisting>


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

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

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

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

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

    </sect2>
  </sect1>

  <sect1 id="network-plip">
    <title>Parallel Line IP (PLIP)</title>

    <indexterm><primary>PLIP</primary></indexterm>
    <indexterm>
      <primary>Parallel Line IP</primary>
      <see>PLIP</see>
    </indexterm>

    <para>PLIP lets us run TCP/IP between parallel ports.  It is
      useful on machines without network cards, or to install on
      laptops.  In this section, we will discuss:</para>

    <itemizedlist>
      <listitem>
	<para>Creating a parallel (laplink) cable.</para>
      </listitem>

      <listitem>
	<para>Connecting two computers with PLIP.</para>
      </listitem>
    </itemizedlist>

    <sect2 id="network-create-parallel-cable">
      <title>Creating a Parallel Cable</title>

      <para>You can purchase a parallel cable at most computer supply
        stores.  If you cannot do that, or you just want to know how
        it is done, the following table shows how to make one out of a normal parallel
        printer cable.</para>

      <table frame="none">
	<title>Wiring a Parallel Cable for Networking</title>

	<tgroup cols="5">
	  <thead>
	    <row>
	      <entry>A-name</entry>

	      <entry>A-End</entry>

	      <entry>B-End</entry>

	      <entry>Descr.</entry>

	      <entry>Post/Bit</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><literallayout>DATA0
-ERROR</literallayout></entry>

	      <entry><literallayout>2
15</literallayout></entry>

	      <entry><literallayout>15
2</literallayout></entry>

	      <entry>Data</entry>

	      <entry><literallayout>0/0x01
1/0x08</literallayout></entry>
	    </row>

	    <row>
	      <entry><literallayout>DATA1
+SLCT</literallayout></entry>

	      <entry><literallayout>3
13</literallayout></entry>

	      <entry><literallayout>13
3</literallayout></entry>

	      <entry>Data</entry>

	      <entry><literallayout>0/0x02
1/0x10</literallayout></entry>
	    </row>

	    <row>
	      <entry><literallayout>DATA2
+PE</literallayout></entry>

	      <entry><literallayout>4
12</literallayout></entry>

	      <entry><literallayout>12
4</literallayout></entry>

	      <entry>Data</entry>

	      <entry><literallayout>0/0x04
1/0x20</literallayout></entry>
	    </row>

	    <row>
	      <entry><literallayout>DATA3
-ACK</literallayout></entry>

	      <entry><literallayout>5
10</literallayout></entry>

	      <entry><literallayout>10
5</literallayout></entry>

	      <entry>Strobe</entry>

	      <entry><literallayout>0/0x08
1/0x40</literallayout></entry>
	    </row>

	    <row>
	      <entry><literallayout>DATA4
BUSY</literallayout></entry>

	      <entry><literallayout>6
11</literallayout></entry>

	      <entry><literallayout>11
6</literallayout></entry>

	      <entry>Data</entry>

	      <entry><literallayout>0/0x10
1/0x80</literallayout></entry>
	    </row>

	    <row>
	      <entry>GND</entry>

	      <entry>18-25</entry>

	      <entry>18-25</entry>

	      <entry>GND</entry>

	      <entry>-</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>
    </sect2>

    <sect2 id="network-plip-setup">
      <title>Setting Up PLIP</title>

      <para>First, you have to get a laplink cable.
	Then, confirm that both computers have a kernel with &man.lpt.4; driver
	support:</para>

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

      <para>The parallel port must be an interrupt driven port,
	you should have lines similar to the
	following in your in the
	<filename>/boot/device.hints</filename> file:</para>

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

      <para>Then check if the kernel configuration file has a
	<literal>device plip</literal> line or if the
	<filename>plip.ko</filename> kernel module is loaded.  In both
	cases the parallel networking interface should appear when you
	use the &man.ifconfig.8; command to display it:</para>

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

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

      <para>Configure the network interface parameters on both
	sites as <username>root</username>.  For example, if you want to connect
	the host <hostid>host1</hostid> with another machine <hostid>host2</hostid>:</para>

      <programlisting>                 host1 &lt;-----&gt; host2
IP Address    10.0.0.1      10.0.0.2</programlisting>

      <para>Configure the interface on <hostid>host1</hostid> by doing:</para>

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

      <para>Configure the interface on <hostid>host2</hostid> by doing:</para>

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


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

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

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

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

          <screen>&prompt.root; <userinput>ifconfig plip0</userinput>
plip0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
        inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
&prompt.root; <userinput>netstat -r</userinput>
Routing tables

Internet:
Destination        Gateway          Flags     Refs     Use      Netif Expire
host2              host1            UH          0       0       plip0
&prompt.root; <userinput>ping -c 4 host2</userinput>
PING host2 (10.0.0.2): 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms

--- host2 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>

    </sect2>
  </sect1>

  <sect1 id="network-ipv6">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Aaron</firstname>
	  <surname>Kaplan</surname>
	  <contrib>Originally Written by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Restructured and Added by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
   <author>
      <firstname>Brad</firstname>
      <surname>Davis</surname>
      <contrib>Extended by </contrib>
   </author>
      </authorgroup>

    </sect1info>

    <title>IPv6</title>
    <para>IPv6 (also known as IPng <quote>IP next generation</quote>) is
      the new version of the well known IP protocol (also known as
      <acronym>IPv4</acronym>).  Like the other current *BSD systems,
      FreeBSD includes the KAME IPv6 reference implementation.
      So your FreeBSD system comes with all you will need to experiment with IPv6.
      This section focuses on getting IPv6 configured and running.</para>

    <para>In the early 1990s, people became aware of the rapidly
      diminishing address space of IPv4.  Given the expansion rate of the
      Internet there were two major concerns:</para>

    <itemizedlist>
      <listitem>
	<para>Running out of addresses.  Today this is not so much of a concern
	  anymore since RFC1918 private address space
	  (<hostid role="ipaddr">10.0.0.0/8</hostid>,
	  <hostid role="ipaddr">172.16.0.0/12</hostid>, and
	  <hostid role="ipaddr">192.168.0.0/16</hostid>)
	  and Network Address Translation (<acronym>NAT</acronym>) are
	  being employed.</para>
      </listitem>

      <listitem>
	<para>Router table entries were getting too large.  This is
	  still a concern today.</para>
      </listitem>
    </itemizedlist>

    <para>IPv6 deals with these and many other issues:</para>

    <itemizedlist>
      <listitem>
	<para>128 bit address space.  In other words theoretically there are
	  340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
	  available.  This means there are approximately
	  6.67 * 10^27 IPv6 addresses per square meter on our planet.</para>
      </listitem>

      <listitem>
	<para>Routers will only store network aggregation addresses in their routing
	  tables thus reducing the average space of a routing table to 8192
	  entries.</para>
      </listitem>
    </itemizedlist>

    <para>There are also lots of other useful features of IPv6 such as:</para>

    <itemizedlist>
      <listitem>
	<para>Address autoconfiguration (<ulink
	  url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>)</para>
      </listitem>

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

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

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

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

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

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


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

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

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

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

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

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

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

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

      <table frame="none">
	<title>Reserved IPv6 addresses</title>

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

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

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

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

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

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

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

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

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

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

      <para>Often an address will have long substrings of all zeros
	therefore one such substring per address can be abbreviated by <quote>::</quote>.
	Also up to three leading <quote>0</quote>s per hexquad can be omitted.
	For example <hostid role="ip6addr">fe80::1</hostid>
	corresponds to the canonical form
	<hostid role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid>.</para>

      <para>A third form is to write the last 32 Bit part in the
	well known (decimal) IPv4 style with dots <quote>.</quote>
	as separators.  For example
	<hostid role="ip6addr">2002::10.0.0.1</hostid>
	corresponds to the (hexadecimal) canonical representation
	<hostid role="ip6addr">2002:0000:0000:0000:0000:0000:0a00:0001</hostid>
	which in turn is equivalent to
	writing <hostid role="ip6addr">2002::a00:1</hostid>.</para>

      <para>By now the reader should be able to understand the following:</para>

      <screen>&prompt.root; <userinput>ifconfig</userinput></screen>

      <programlisting>rl0: flags=8943&lt;UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST&gt; mtu 1500
         inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
         inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
         ether 00:00:21:03:08:e1
         media: Ethernet autoselect (100baseTX )
         status: active</programlisting>

      <para><hostid role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid>
	is an auto configured link-local address.  It is generated from the MAC
	address as part of the auto configuration.</para>

      <para>For further information on the structure of IPv6 addresses
	see <ulink
	url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</para>
    </sect2>

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

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

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

	<listitem>
	  <para>Tunnel via 6-to-4 (<ulink
	    url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para>
	</listitem>

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

    <sect2>
      <title>DNS in the IPv6 World</title>

      <para>There used to be two types of DNS records for IPv6.  The IETF
	has declared A6 records obsolete.  AAAA records are the standard
	now.</para>

      <para>Using AAAA records is straightforward.  Assign your hostname to the new
	IPv6 address you just received by adding:</para>

      <programlisting>MYHOSTNAME           AAAA    MYIPv6ADDR</programlisting>

      <para>To your primary zone DNS file.  In case you do not serve your own
	<acronym>DNS</acronym> zones ask your <acronym>DNS</acronym> provider.
	Current versions of <application>bind</application> (version 8.3 and 9)
	and <filename role="package">dns/djbdns</filename> (with the IPv6 patch)
	support AAAA records.</para>
    </sect2>

    <sect2>
      <title>Applying the needed changes to <filename>/etc/rc.conf</filename></title>

      <sect3>
	<title>IPv6 Client Settings</title>

	<para>These settings will help you configure a machine that will be on
	  your LAN and act as a client, not a router.  To have &man.rtsol.8;
	  autoconfigure your interface on boot all you need to add is:</para>

	<programlisting>ipv6_enable="YES"</programlisting>

	<para>To statically assign an IP address such as <hostid role="ip6addr">
	  2001:471:1f11:251:290:27ff:fee0:2093</hostid>, to your
	  <devicename>fxp0</devicename> interface, add:</para>

	<programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting>

	<para>To assign a default router of
	  <hostid role="ip6addr">2001:471:1f11:251::1</hostid>
	  add the following to <filename>/etc/rc.conf</filename>:</para>

	<programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting>

      </sect3>

      <sect3>
	<title>IPv6 Router/Gateway Settings</title>

	<para>This will help you take the directions that your tunnel provider has
	  given you and convert it into settings that will persist through reboots.
	  To restore your tunnel on startup use something like the following in
	  <filename>/etc/rc.conf</filename>:</para>

	<para>List the Generic Tunneling interfaces that will be configured, for
	  example <devicename>gif0</devicename>:</para>

	<programlisting>gif_interfaces="gif0"</programlisting>

	<para>To configure the interface with a local endpoint of
	  <replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint of
	  <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para>

	<programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>

	<para>To apply the IPv6 address you have been assigned for use as your
	  IPv6 tunnel endpoint, add:</para>

	<programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>

	<para>Then all you have to do is set the default route for IPv6.  This is
	  the other side of the IPv6 tunnel:</para>

	<programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>

      </sect3>

      <sect3>
	<title>IPv6 Tunnel Settings</title>

	<para>If the server is to route IPv6 between the rest of your network
	  and the world, the following <filename>/etc/rc.conf</filename>
	  setting will also be needed:</para>

	<programlisting>ipv6_gateway_enable="YES"</programlisting>

      </sect3>
    </sect2>

    <sect2>
      <title>Router Advertisement and Host Auto Configuration</title>

      <para>This section will help you setup &man.rtadvd.8; to advertise the
	IPv6 default route.</para>

      <para>To enable &man.rtadvd.8; you will need the following in your
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>rtadvd_enable="YES"</programlisting>

      <para>It is important that you specify the interface on which to do
	IPv6 router solicitation.  For example to tell &man.rtadvd.8; to use
	<devicename>fxp0</devicename>:</para>

      <programlisting>rtadvd_interfaces="fxp0"</programlisting>

      <para>Now we must create the configuration file,
	<filename>/etc/rtadvd.conf</filename>.  Here is an example:</para>

      <programlisting>fxp0:\
	:addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting>

      <para>Replace <devicename>fxp0</devicename> with the interface you
	are going to be using.</para>

      <para>Next, replace <hostid role="ip6addr">2001:471:1f11:246::</hostid>
	with the prefix of your allocation.</para>

      <para>If you are dedicated a <hostid role="netmask">/64</hostid> subnet
	you will not need to change anything else.  Otherwise, you will need to
	change the <literal>prefixlen#</literal> to the correct value.</para>

   </sect2>
  </sect1>

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

    <title>Asynchronous Transfer Mode (ATM)</title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  <sect1 id="carp">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Common Access Redundancy Protocol (CARP)</title>

    <indexterm><primary>CARP</primary></indexterm>
    <indexterm><primary>Common Access Redundancy Protocol</primary></indexterm>

    <para>The Common Access Redundancy Protocol, or
      <acronym>CARP</acronym> allows multiple hosts to share the same
      <acronym>IP</acronym> address.  In some configurations, this may
      be used for availability or load balancing.  Hosts may use separate
      <acronym>IP</acronym> addresses as well, as in the example provided
      here.</para>

    <para>To enable support for <acronym>CARP</acronym>, the &os;
      kernel must be rebuilt with the following option:</para>

    <programlisting>device	carp</programlisting>

    <para><acronym>CARP</acronym> functionality should now be available
      and may be tuned via several <command>sysctl</command>
      <acronym>OID</acronym>s.  Devices themselves may be loaded via
      the <command>ifconfig</command> command:</para>

    <screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen>

    <para>In a real environment, these interfaces will need unique
      identification numbers known as a <acronym>VHID</acronym>.  This
      <acronym>VHID</acronym> or Virtual Host Identification will be
      used to distinguish the host on the network.</para>

    <sect2>
      <title>Using CARP For Server Availability (CARP)</title>

      <para>One use of <acronym>CARP</acronym>, as noted above, is for
	server availability.  This example will provide failover support
	for three hosts, all with unique <acronym>IP</acronym>
	addresses and providing the same web content.  These machines will
	act in conjunction with a Round Robin <acronym>DNS</acronym>
	configuration.  The failover machine will have two additional
	<acronym>CARP</acronym> interfaces, one for each of the content
	server's <acronym>IP</acronym>s.  When a failure occurs, the
	failover server should pick up the failed machine's
	<acronym>IP</acronym> address.  This means the failure should
	go completely unnoticed to the user.  The failover server
	requires identical content and services as the other content
	servers it is expected to pick up load for.</para>

      <para>The two machines should be configured identically other
	than their issued hostnames and <acronym>VHID</acronym>s.
	This example calls these machines
	<hostid>hosta.example.org</hostid> and
	<hostid>hostb.example.org</hostid> respectively.  First, the
	required lines for a <acronym>CARP</acronym> configuration have
	to be added to <filename>rc.conf</filename>.  For
	<hostid>hosta.example.org</hostid>, the
	<filename>rc.conf</filename> file should contain the following
	lines:</para>

      <programlisting>hostname="hosta.example.org"
ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0"
cloned_interfaces="carp0"
ifconfig_carp0="vhid 1 pass testpast 192.168.1.50/24"</programlisting>

      <para>On <hostid>hostb.example.org</hostid> the following lines
	should be in <filename>rc.conf</filename>:</para>

      <programlisting>hostname="hostb.example.org"
ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0"
cloned_interfaces="carp0"
ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting>

      <note>
	<para>It is very important that the passwords, specified by the
	  <option>pass</option> option to <command>ifconfig</command>,
	  are identical.  The <devicename>carp</devicename> devices will
	  only listen to and accept advertisements from machines with the
	  correct password.  The <acronym>VHID</acronym> must also be
	  different for each machine.</para>
      </note>

      <para>The third machine,
	<hostid>provider.example.org</hostid>, should be prepared so that
	it may handle failover from either host.  This machine will require
	two <devicename>carp</devicename> devices, one to handle each
	host.  The appropriate <filename>rc.conf</filename>
	configuration lines will be similar to the following:</para>

      <programlisting>hostname="provider.example.org"
ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0"
cloned_interfaces="carp0 carp1"
ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24"
ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlisting>

      <para>Having the two <devicename>carp</devicename> devices will
        allow <hostid>provider.example.org</hostid> to notice and pick
	up the <acronym>IP</acronym> address of either machine should
	it stop responding.</para>

      <note>
        <para>The default &os; kernel <emphasis>may</emphasis> have
	  preemption enabled.  If so,
	  <hostid>provider.example.org</hostid> may not relinquish the
	  <acronym>IP</acronym> address back to the original content
	  server.  In this case, an administrator may
	  <quote>nudge</quote> the interface.  The following command
	  should be issued on
	  <hostid>provider.example.org</hostid>:</para>

	<screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen>

	<para>This should be done on the <devicename>carp</devicename>
	  interface which corresponds to the correct host.</para>
      </note>

      <para>At this point, <acronym>CARP</acronym> should be completely
	enabled and available for testing.  For testing, either networking has
	to be restarted or the machines need to be rebooted.</para>

      <para>More information is always available in the &man.carp.4;
        manual page.</para>
    </sect2>
  </sect1>
</chapter>

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