Attachment #184060 for bug #219966

View | Details | Raw Unified | Return to bug 219966
Collapse All | Expand All




<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="advanced-networking">
  <title>Advanced Networking</title>

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

    <para>This chapter covers a number of advanced networking
      topics.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>The basics of gateways and routes.</para>
      </listitem>

      <listitem>
	<para>How to set up USB tethering.</para>
      </listitem>

      <listitem>
	<para>How to set up &ieee; 802.11 and &bluetooth;
	  devices.</para>
      </listitem>

      <listitem>
	<para>How to make &os; act as a bridge.</para>
      </listitem>

      <listitem>
	<para>How to set up network <acronym>PXE</acronym>
	  booting.</para>
      </listitem>

      <listitem>
	<para>How to set up <acronym>IPv6</acronym> on a &os;
	  machine.</para>
      </listitem>

      <listitem>
	<para>How to enable and utilize the features of the Common
	  Address Redundancy Protocol (<acronym>CARP</acronym>) in
	  &os;.</para>
      </listitem>

      <listitem>
	<para>How to configure multiple <acronym>VLANs</acronym> on
	  &os;.</para>
      </listitem>
    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>
      <listitem>
	<para>Understand the basics of the
	  <filename>/etc/rc</filename> scripts.</para>
      </listitem>

      <listitem>
	<para>Be familiar with basic network terminology.</para>
      </listitem>

      <listitem>
	<para>Know how to configure and install a new &os; kernel
	  (<xref linkend="kernelconfig"/>).</para>
      </listitem>

      <listitem>
	<para>Know how to install additional third-party software
	  (<xref linkend="ports"/>).</para>
      </listitem>

    </itemizedlist>
  </sect1>

  <sect1 xml:id="network-routing">
    <info>
      <title>Gateways and Routes</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Coranth</firstname>
	    <surname>Gryphon</surname>
	  </personname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>routing</primary>
    </indexterm>
    <indexterm>
      <primary>gateway</primary>
    </indexterm>
    <indexterm>
      <primary>subnet</primary>
    </indexterm>

    <para><firstterm>Routing</firstterm> is the mechanism that allows
      a system to find the network path to another system.  A
      <firstterm>route</firstterm> is a defined pair of addresses
      which represent the <quote>destination</quote> and a
      <quote>gateway</quote>.  The route indicates that when trying
      to get to the specified destination, send the packets through
      the specified gateway.  There are three types of destinations:
      individual hosts, subnets, and <quote>default</quote>.  The
      <quote>default route</quote> is used if no other routes apply.
      There are also three types of gateways: individual hosts,
      interfaces, also called links, and Ethernet hardware
      (<acronym>MAC</acronym>) addresses.  Known routes are stored in
      a routing table.</para>

    <para>This section provides an overview of routing basics.  It
      then demonstrates how to configure a &os; system as a router and
      offers some troubleshooting tips.</para>

    <sect2 xml:id="network-routing-default">
      <title>Routing Basics</title>

      <para>To view the routing table of a &os; system, use
	&man.netstat.1;:</para>

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

Internet:
Destination      Gateway            Flags     Refs     Use     Netif Expire
default          outside-gw         UGS        37      418       em0
localhost        localhost          UH          0      181       lo0
test0            0:e0:b5:36:cf:4f   UHLW        5    63288       re0     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 =&gt;
host2.example.com link#1            UC          0        0
224              link#1             UC          0        0</screen>

      <para>The entries in this example are as follows:</para>

      <variablelist>
	<varlistentry>
	  <term>default</term>
	  <listitem>
	    <para>The first route in this table specifies the
	      <literal>default</literal> route.  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 matches an entry in the table, the
	      system checks to see if it can connect using the
	      interface specified in that entry.</para>

	    <para>If the destination does not match an entry, or if
	      all known paths fail, the system uses the entry for the
	      default route.  For hosts on a local area network, the
	      <literal>Gateway</literal> field in the default route is
	      set to the system which has a direct connection to the
	      Internet.  When reading this entry, verify that the
	      <literal>Flags</literal> column indicates that the
	      gateway is usable (<literal>UG</literal>).</para>

	    <para>The default route for a machine which itself is
	      functioning as the gateway to the outside world will be
	      the gateway machine at the Internet Service Provider
	      (<acronym>ISP</acronym>).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>localhost</term>
	  <listitem>
	    <para>The second route is the <literal>localhost</literal>
	      route.  The interface specified in the
	      <literal>Netif</literal> column for
	      <literal>localhost</literal> is
	      <filename>lo0</filename>, also known as the loopback
	      device.  This indicates that all traffic for this
	      destination should be internal, rather than sending it
	      out over the network.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>MAC address</term>
	  <listitem>
	    <para>The addresses beginning with <systemitem
		class="etheraddress">0:e0:</systemitem> are
	      <acronym>MAC</acronym> addresses.  &os; will
	      automatically identify any hosts,
	      <systemitem>test0</systemitem> in the example, on the
	      local Ethernet and add a route for that host over the
	      Ethernet interface, <filename>re0</filename>.  This type
	      of route has a timeout, seen in the
	      <literal>Expire</literal> column, which is used if the
	      host does not respond in a specific amount of time.
	      When this happens, the route to this host will be
	      automatically deleted.  These hosts are identified using
	      the Routing Information Protocol
	      (<acronym>RIP</acronym>), which calculates routes to
	      local hosts based upon a shortest path
	      determination.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>subnet</term>
	  <listitem>
	    <para>&os; will automatically add subnet routes for the
	      local subnet.  In this example, <systemitem
		class="ipaddress">10.20.30.255</systemitem> is the
	      broadcast address for the subnet <systemitem
		class="ipaddress">10.20.30</systemitem> and
	      <systemitem
		class="fqdomainname">example.com</systemitem> is the
	      domain name associated with that subnet.  The
	      designation <literal>link#1</literal> refers to the
	      first Ethernet card in the machine.</para>

	    <para>Local network hosts and local subnets have their
	      routes automatically configured by a daemon called
	      &man.routed.8;.  If it is not running, only routes which
	      are statically defined by the administrator will
	      exist.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>host</term>
	  <listitem>
	    <para>The <literal>host1</literal> line refers to the host
	      by its Ethernet address.  Since it is the sending host,
	      &os; knows to use the loopback interface
	      (<filename>lo0</filename>) rather than the Ethernet
	      interface.</para>

	    <para>The two <literal>host2</literal> lines represent
	      aliases which were created using &man.ifconfig.8;.  The
	      <literal>=&gt;</literal> symbol after the
	      <filename>lo0</filename> interface says that an alias
	      has been set in addition to the loopback address.  Such
	      routes only show up on the host that supports the alias
	      and all other hosts on the local network will have a
	      <literal>link#1</literal> line for such routes.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>224</term>
	  <listitem>
	    <para>The final line (destination subnet <systemitem
		class="ipaddress">224</systemitem>) deals with
	      multicasting.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Various attributes of each route can be seen in the
	<literal>Flags</literal> column.  <xref linkend="routeflags"/>
	summarizes some of these flags and their meanings:</para>

      <table xml:id="routeflags" frame="none" pgwide="1">
	<title>Commonly Seen Routing Table Flags</title>

	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>Command</entry>
	      <entry>Purpose</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>U</entry>
	      <entry>The route is active (up).</entry>
	    </row>

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

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

	    <row>
	      <entry>S</entry>
	      <entry>This route was statically configured.</entry>
	    </row>

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

	    <row>
	      <entry>W</entry>
	      <entry>The route was auto-configured based upon a local
		area network (clone) route.</entry>
	    </row>

	    <row>
	      <entry>L</entry>
	      <entry>Route involves references to Ethernet (link)
		hardware.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <para>On a &os; system, the default route can defined in
	<filename>/etc/rc.conf</filename> by specifying the
	<acronym>IP</acronym> address of the default gateway:</para>

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

      <para>It is also possible to manually add the route using
	<command>route</command>:</para>

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

      <para>Note that manually added routes will not survive a reboot.
	For more information on manual manipulation of network
	routing tables, refer to &man.route.8;.</para>
    </sect2>

    <sect2 xml:id="network-static-routes">
      <info>
	<title>Configuring a Router with Static Routes</title>

	<authorgroup>
	  <author>
	    <personname>
	      <firstname>Al</firstname>
	      <surname>Hoang</surname>
	    </personname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </info>
      <!-- Feb 2004 -->

      <indexterm>
	<primary>dual homed hosts</primary>
      </indexterm>

      <para>A &os; system can be configured as the default gateway, or
	router, for a network if it is a dual-homed system.  A
	dual-homed system is a host which resides on at least two
	different networks.  Typically, each network is connected to a
	separate network interface, though <acronym>IP</acronym>
	aliasing can be used to bind multiple addresses, each on a
	different subnet, to one physical interface.</para>

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

      <para>In order for the system to forward packets between
	interfaces, &os; must be configured as a router.  Internet
	standards and good engineering practice prevent the &os;
	Project from enabling this feature by default, but it can be
	configured to start at boot by adding this line to
	<filename>/etc/rc.conf</filename>:</para>

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

      <para>To enable routing now, set the &man.sysctl.8; variable
	<varname>net.inet.ip.forwarding</varname> to
	<literal>1</literal>.  To stop routing, reset this variable to
	<literal>0</literal>.</para>

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

      <para>The routing table of a router needs additional routes so
	it knows how to reach other networks.  Routes can be either
	added manually using static routes or routes can be
	automatically learned using a routing protocol.  Static routes
	are appropriate for small networks and this section describes
	how to add a static routing entry for a small network.</para>

      <note>
	<para>For large networks, static routes quickly become
	  unscalable.  &os; comes with the standard
	  <acronym>BSD</acronym> routing daemon &man.routed.8;, which
	  provides the routing protocols <acronym>RIP</acronym>,
	  versions 1 and 2, and <acronym>IRDP</acronym>.  Support for
	  the <acronym>BGP</acronym> and <acronym>OSPF</acronym>
	  routing protocols can be installed using the
	  <package>net/zebra</package> package or port.</para>
      </note>

      <para>Consider the following network:</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, <systemitem>RouterA</systemitem> is a
	&os; machine that is acting as a router to the rest of the
	Internet.  It has a default route set to <systemitem
	  class="ipaddress">10.0.0.1</systemitem> which allows it to
	connect with the outside world.
	<systemitem>RouterB</systemitem> is already configured to use
	<systemitem class="ipaddress">192.168.1.1</systemitem> as its
	default gateway.</para>

      <para>Before adding any static routes, the routing table on
	<systemitem>RouterA</systemitem> looks like this:</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.0/24        link#1             UC          0        0    xl0
192.168.1.0/24     link#2             UC          0        0    xl1</screen>

      <para>With the current routing table,
	<systemitem>RouterA</systemitem> does not have a route to the
	<systemitem class="ipaddress">192.168.2.0/24</systemitem>
	network.  The following command adds the <literal>Internal Net
	  2</literal> network to <systemitem>RouterA</systemitem>'s
	routing table using <systemitem
	  class="ipaddress">192.168.1.2</systemitem> 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, <systemitem>RouterA</systemitem> can reach any host
	on the <systemitem
	  class="ipaddress">192.168.2.0/24</systemitem> network.
	However, the routing information will not persist if the &os;
	system reboots.  If a static route needs to be persistent, add
	it to <filename>/etc/rc.conf</filename>:</para>

      <programlisting># Add Internal Net 2 as a persistent 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, where each
	string references a route name.  The variable
	<literal>route_<replaceable>internalnet2</replaceable></literal>
	contains the static route for that route name.</para>

      <para>Using more than one string in
	<literal>static_routes</literal> creates multiple static
	routes.  The following shows an example of adding static
	routes for the <systemitem
	  class="ipaddress">192.168.0.0/24</systemitem> and
	<systemitem class="ipaddress">192.168.1.0/24</systemitem>
	networks:</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>
    </sect2>

    <sect2 xml:id="network-routing-troubleshooting">
      <title>Troubleshooting</title>

      <para>When an address space is assigned to a network, the
	service provider configures their routing tables so that all
	traffic for the network will be sent to the link for the site.
	But how do external sites know to send their packets to the
	network's <acronym>ISP</acronym>?</para>

      <para>There is a system that keeps track of all assigned
	address spaces and defines their point of connection to the
	Internet backbone, or 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 a particular network.</para>

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

      <indexterm>
	<primary>&man.traceroute.8;</primary>
      </indexterm>

      <para>Sometimes, there is a problem with route propagation and
	some sites are unable to connect.  Perhaps the most useful
	command for trying to figure out where routing is breaking
	down is <command>traceroute</command>.  It is useful when
	<command>ping</command> fails.</para>

      <para>When using <command>traceroute</command>, include the
	address of the remote host to connect to.  The output 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.  For more information, refer
	to &man.traceroute.8;.</para>
    </sect2>

    <sect2 xml:id="network-routing-multicast">
      <title>Multicast Considerations</title>

      <indexterm>
	<primary>multicast routing</primary>
      </indexterm>
      <indexterm>
	<primary>kernel options</primary>
	<secondary>MROUTING</secondary>
      </indexterm>

      <para>&os; natively supports both multicast applications and
	multicast routing.  Multicast applications do not require any
	special configuration in order to run on &os;.  Support for
	multicast routing requires that the following option be
	compiled into a custom kernel:</para>

      <programlisting>options MROUTING</programlisting>

      <para>The multicast routing daemon,
	<application>mrouted</application> can be installed using the
	<package>net/mrouted</package> package or port.  This daemon
	implements the <acronym>DVMRP</acronym> multicast routing
	protocol and is configured by editing
	<filename>/usr/local/etc/mrouted.conf</filename> in order to
	set up the tunnels and <acronym>DVMRP</acronym>.  The
	installation of <application>mrouted</application> also
	installs <application>map-mbone</application> and
	<application>mrinfo</application>, as well as their associated
	man pages.  Refer to these for configuration examples.</para>

      <note>
	<para><acronym>DVMRP</acronym> has largely been replaced by
	  the <acronym>PIM</acronym> protocol in many multicast
	  installations.  Refer to &man.pim.4; for more
	  information.</para>
      </note>
    </sect2>
  </sect1>

  <sect1 xml:id="network-wireless">
    <info>
      <title>Wireless Networking</title>

      <authorgroup>
	<author>
	  <personname>
	    <othername>Loader</othername>
	  </personname>
	</author>
	<author>
	  <personname>
	    <firstname>Marc</firstname>
	    <surname>Fonvieille</surname>
	  </personname>
	</author>
	<author>
	  <personname>
	    <firstname>Murray</firstname>
	    <surname>Stokely</surname>
	  </personname>
	</author>
      </authorgroup>
    </info>

    <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 <acronym>BSS</acronym>, and the master
	station is termed an access point (<acronym>AP</acronym>).
	In a <acronym>BSS</acronym>, all communication passes through
	the <acronym>AP</acronym>; even when one station wants to
	communicate with another wireless station, messages must go
	through the <acronym>AP</acronym>.  In the second form of
	network, there is no master and stations communicate directly.
	This form of network is termed an <acronym>IBSS</acronym>
	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 and the <acronym>MAC</acronym> layer
	characteristics, including framing and transmission rates,
	as communication can occur at various rates.  Later, the
	802.11a standard defined operation in the 5GHz band, including
	different signaling mechanisms and higher transmission rates.
	Still later, the 802.11g standard defined the use of 802.11a
	signaling 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 <acronym>WEP</acronym>.  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 data communication.  Cryptographic keys
	are periodically refreshed and there are mechanisms for
	detecting and countering intrusion attempts.  Another
	security protocol specification commonly used in wireless
	networks is termed <acronym>WPA</acronym>, which was a
	precursor to 802.11i.  <acronym>WPA</acronym> specifies a
	subset of the requirements found in 802.11i and is designed
	for implementation on legacy hardware.  Specifically,
	<acronym>WPA</acronym> requires only the
	<acronym>TKIP</acronym> cipher that is derived from the
	original <acronym>WEP</acronym> cipher.  802.11i permits use
	of <acronym>TKIP</acronym> but also requires support for a
	stronger cipher, AES-CCM, for encrypting data.  The
	<acronym>AES</acronym> cipher was not required in
	<acronym>WPA</acronym> because it was deemed too
	computationally costly to be implemented on legacy
	hardware.</para>

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

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

    <sect2 xml:id="network-wireless-quick-start">
      <title>Quick Start</title>

      <para>Connecting a computer to an existing wireless network is
	a very common situation.  This procedure shows the steps
	required.</para>

      <procedure>
	<step>
	  <para>Obtain the <acronym>SSID</acronym> (Service Set
	    Identifier) and <acronym>PSK</acronym> (Pre-Shared Key)
	    for the wireless network from the network
	    administrator.</para>
	</step>

	<step>
	  <para>Identify the wireless adapter.  The &os;
	    <filename>GENERIC</filename> kernel includes drivers for
	    many common wireless adapters.  If the wireless adapter is
	    one of those models, it will be shown in the output from
	    &man.ifconfig.8;:</para>

	  <screen>&prompt.user; <userinput>ifconfig | grep -B3 -i wireless</userinput></screen>

	  <para>On &os;&nbsp;11 or higher, use this command
	    instead:</para>

	  <screen>&prompt.user; <userinput>sysctl net.wlan.devices</userinput></screen>

	  <para>If a wireless adapter is not listed, an additional
	    kernel module might be required, or it might be a model
	    not supported by &os;.</para>
	  <!-- WB: refer to section that shows how to identify a
	  wireless adapter and load the kernel modules for it. -->

	  <para>This example shows the Atheros <literal>ath0</literal>
	    wireless adapter.</para>
	</step>

	<step>
	  <para>Add an entry for this network to
	    <filename>/etc/wpa_supplicant.conf</filename>.  If the
	    file does not exist, create it.  Replace
	    <replaceable>myssid</replaceable> and
	    <replaceable>mypsk</replaceable> with the
	    <acronym>SSID</acronym> and <acronym>PSK</acronym>
	    provided by the network administrator.</para>

	  <programlisting>network={
	ssid="<replaceable>myssid</replaceable>"
	psk="<replaceable>mypsk</replaceable>"
}</programlisting>
	</step>

	<step>
	  <para>Add entries to <filename>/etc/rc.conf</filename> to
	    configure the network on startup:</para>

	  <programlisting>wlans_<replaceable>ath0</replaceable>="wlan0"
ifconfig_wlan0="WPA SYNCDHCP"</programlisting>
	</step>

	<step>
	  <para>Restart the computer, or restart the network service
	    to connect to the network:</para>

	  <screen>&prompt.root; <userinput>service netif restart</userinput></screen>
	</step>
      </procedure>
    </sect2>

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

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

	<para>To use wireless networking, a wireless networking card
	  is needed and the kernel needs to be configured with the
	  appropriate wireless networking support.  The kernel is
	  separated into multiple modules so that only the required
	  support needs to be configured.</para>

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

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

	<para>The Atheros driver is split up into three separate
	  pieces: the driver (&man.ath.4;), the hardware support
	  layer that handles chip-specific functions
	  (&man.ath.hal.4;), and an algorithm for selecting the
	  rate for transmitting frames.  When this support is loaded
	  as kernel modules, any dependencies are automatically
	  handled.  To load support for a different type of wireless
	  device, specify the module for that device.  This example
	  is for devices based on the Intersil Prism parts
	  (&man.wi.4;) driver:</para>

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

	<note>
	  <para>The examples in this section use an &man.ath.4;
	    device and the device name in the examples must be
	    changed according to the configuration.  A list of
	    available wireless drivers and supported adapters can be
	    found in the &os; Hardware Notes, available on
	    the <link
	      xlink:href="http://www.FreeBSD.org/releases/index.html">Release
	      Information</link> page of the &os; website.  If a
	    native &os; driver for the wireless device does not
	    exist, it may be possible to use the &windows; driver
	    with the help of the <link
	      linkend="config-network-ndis">NDIS</link> driver
	    wrapper.</para>
	</note>

	<para>In addition, the modules that implement cryptographic
	  support for the security protocols to use must be loaded.
	  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;.
	  The &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are
	  only needed when using the <acronym>WPA</acronym> or
	  802.11i security protocols.  If the network does not use
	  encryption, &man.wlan.wep.4; support is not needed.  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>Once this information has been added to
	  <filename>/boot/loader.conf</filename>, reboot the &os;
	  box.  Alternately, load the modules by hand using
	  &man.kldload.8;.</para>

	<note>
	  <para>For users who do not want to use modules, it is
	    possible to compile these drivers into the kernel by
	    adding the following lines to a custom kernel
	    configuration file:</para>

	  <programlisting>device wlan              # 802.11 support
device wlan_wep          # 802.11 WEP support
device wlan_ccmp         # 802.11 CCMP support
device wlan_tkip         # 802.11 TKIP support
device wlan_amrr         # AMRR transmit rate control algorithm
device ath               # Atheros pci/cardbus NIC's
device ath_hal           # pci/cardbus chip support
options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors
device ath_rate_sample   # SampleRate tx rate control for ath</programlisting>

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

	<para>Information about the wireless device should appear
	  in the boot messages, like this:</para>

	<screen>ath0: &lt;Atheros 5212&gt; mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1
ath0: [ITHREAD]
ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen>
      </sect3>
    </sect2>

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

      <para>Infrastructure (<acronym>BSS</acronym>) 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, called the
	<acronym>SSID</acronym>.  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 available networks, use &man.ifconfig.8;.
	    This request may take a few moments to complete as it
	    requires the system to switch to each available wireless
	    frequency and probe for available access points.  Only
	    the superuser can initiate a scan:</para>

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
dlinkap         00:13:46:49:41:76   11   54M -90:96   100 EPS  WPA WME
freebsdap       00:11:95:c3:0d:ac    1   54M -83:96   100 EPS  WPA</screen>

	  <note>
	    <para>The interface must be <option>up</option> before
	      it can scan.  Subsequent scan requests do not require
	      the interface to be marked as up again.</para>
	  </note>

	  <para>The output of a scan request lists each
	    <acronym>BSS</acronym>/<acronym>IBSS</acronym> network
	    found.  Besides listing the name of the network, the
	    <literal>SSID</literal>, the output also shows the
	    <literal>BSSID</literal>, which is the
	    <acronym>MAC</acronym> 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>

	  <table frame="none" pgwide="0">
	    <title>Station Capability Codes</title>

	    <tgroup cols="2">
	      <thead>
		<row>
		  <entry>Capability Code</entry>
		  <entry>Meaning</entry>
		</row>
	      </thead>

	      <tbody>
		<row>
		  <entry><literal>E</literal></entry>
		  <entry>Extended Service Set
		    (<acronym>ESS</acronym>).  Indicates that
		    the station is part of an infrastructure network
		    rather than an <acronym>IBSS</acronym>/ad-hoc
		    network.</entry>
		</row>

		<row>
		  <entry><literal>I</literal></entry>
		  <entry><acronym>IBSS</acronym>/ad-hoc network.
		    Indicates that the station is part of an ad-hoc
		    network rather than an <acronym>ESS</acronym>
		    network.</entry>
		</row>

		<row>
		  <entry><literal>P</literal></entry>
		  <entry>Privacy.  Encryption is required for all
		    data frames exchanged within the
		    <acronym>BSS</acronym> using cryptographic means
		    such as <acronym>WEP</acronym>,
		    <acronym>TKIP</acronym> or
		    <acronym>AES</acronym>-<acronym>CCMP</acronym>.</entry>
		</row>

		<row>
		  <entry><literal>S</literal></entry>
		  <entry>Short Preamble.  Indicates that the network
		    is using short preambles, defined in 802.11b High
		    Rate/DSSS PHY, and utilizes a 56 bit sync field
		    rather than the 128 bit field used in long
		    preamble mode.</entry>
		</row>

		<row>
		  <entry><literal>s</literal></entry>
		  <entry>Short slot time.  Indicates that the 802.11g
		    network is using a short slot time because there
		    are no legacy (802.11b) stations present.</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>

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

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</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.  Once familiar with these concepts, it is
	    strongly recommend to use <link
	      linkend="network-wireless-wpa">WPA</link> to set up
	    the wireless network.</para>

	  <para>There are three basic steps to configure a wireless
	    network: select an access point, authenticate the
	    station, and configure an <acronym>IP</acronym> address.
	    The following sections discuss each step.</para>

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

	    <para>Most of the time, it is sufficient to let the system
	      choose an access point using the builtin heuristics.
	      This is the default behavior when an interface is
	      marked as up or it is listed in
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="DHCP"</programlisting>

	    <para>If there are multiple access points, a specific
	      one can be selected by its
	      <acronym>SSID</acronym>:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>

	    <para>In an environment where there are multiple access
	      points with the same <acronym>SSID</acronym>, which
	      is often done to simplify roaming, it may be necessary
	      to associate to one specific device.  In this case, the
	      <acronym>BSSID</acronym> of the access point can be
	      specified, with or without the
	      <acronym>SSID</acronym>:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="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 for a
	      multi-band wireless card as scanning all the possible
	      channels can be time-consuming.  To limit operation to a
	      specific band, use the <option>mode</option>
	      parameter:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>

	    <para>This example 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.  This can
	      also be achieved with the
	      <option>channel</option> parameter, which locks
	      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 &man.ifconfig.8;.</para>
	  </sect5>

	  <sect5>
	    <title>Authentication</title>

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

	    <note>
	      <para>If using an &apple; &airport; Extreme base
		station for an access point, shared-key authentication
		together with a <acronym>WEP</acronym> key needs to
		be configured.  This can be configured in
		<filename>/etc/rc.conf</filename> or by using
		&man.wpa.supplicant.8;.  For a single &airport; base
		station, access can be configured with:</para>

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

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

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

	    <para>Once an access point is selected and the
	      authentication parameters are set, an
	      <acronym>IP</acronym> address must be obtained in
	      order to communicate.  Most of the time, the
	      <acronym>IP</acronym> address is obtained via
	      <acronym>DHCP</acronym>.  To achieve that, edit
	      <filename>/etc/rc.conf</filename> and add
	      <literal>DHCP</literal> to the configuration for the
	      device:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="DHCP"</programlisting>

	    <para>The
	      wireless interface is now ready to bring up:</para>

	    <screen>&prompt.root; <userinput>service netif start</userinput></screen>

	    <para>Once the interface is running, use &man.ifconfig.8;
	      to see the status of the interface
	      <filename>ath0</filename>:</para>

	    <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
        ether 00:11:95:d5:43:62
        inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
        media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
        status: associated
        ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76
        country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
        scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
        roam:rate 5 protmode CTS wme burst</screen>

	    <para>The <literal>status: associated</literal> line means
	      that it is connected to the wireless network.  The
	      <literal>bssid 00:13:46:49:41:76</literal> is the
	      <acronym>MAC</acronym> address of the access point and
	      <literal>authmode OPEN</literal> indicates that the
	      communication is not encrypted.</para>
	  </sect5>

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

	    <para>If an <acronym>IP</acronym> address cannot be
	      obtained from a <acronym>DHCP</acronym> server, set a
	      fixed <acronym>IP</acronym> address.  Replace the
	      <literal>DHCP</literal> keyword shown above with the
	      address information.  Be sure to retain any other
	      parameters for selecting the access point:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting>
	  </sect5>
	</sect4>

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

	  <para>Wi-Fi Protected Access (<acronym>WPA</acronym>) is a
	    security protocol used together with 802.11 networks to
	    address the lack of proper authentication and the weakness
	    of <acronym>WEP</acronym>.  WPA leverages the 802.1X
	    authentication protocol and uses one of several ciphers
	    instead of <acronym>WEP</acronym> for data integrity.
	    The only cipher required by <acronym>WPA</acronym> is the
	    Temporary Key Integrity Protocol
	    (<acronym>TKIP</acronym>).  <acronym>TKIP</acronym> is a
	    cipher that extends the basic RC4 cipher used by
	    <acronym>WEP</acronym> by adding integrity checking,
	    tamper detection, and measures for responding to detected
	    intrusions.  <acronym>TKIP</acronym> 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.
	    <acronym>WPA</acronym> also specifies the
	    <acronym>AES-CCMP</acronym> cipher as an alternative to
	    <acronym>TKIP</acronym>, and that is preferred when
	    possible.  For this specification, the term
	    <acronym>WPA2</acronym> or <acronym>RSN</acronym> is
	    commonly used.</para>

	  <para><acronym>WPA</acronym> 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 <acronym>RADIUS</acronym>,
	    or by a minimal handshake between the station and the
	    access point using a pre-shared secret.  The former is
	    commonly termed <acronym>WPA</acronym> Enterprise and the
	    latter is known as <acronym>WPA</acronym> Personal.  Since
	    most people will not set up a <acronym>RADIUS</acronym>
	    backend server for their wireless network,
	    <acronym>WPA-PSK</acronym> is by far the most commonly
	    encountered configuration for
	    <acronym>WPA</acronym>.</para>

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

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

	    <para><acronym>WPA-PSK</acronym>, also known as
	      <acronym>WPA</acronym> Personal, is based on a
	      pre-shared key (<acronym>PSK</acronym>) which is
	      generated from a given password and used as the master
	      key in the wireless network.  This means every wireless
	      user will share the same key.
	      <acronym>WPA-PSK</acronym> 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 that they will
		not be easily guessed or attacked.</para>
	    </warning>

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

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

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

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>

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

	    <screen>&prompt.root; <userinput>service netif start</userinput>
Starting wpa_supplicant.
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6
DHCPOFFER from 192.168.0.1
DHCPREQUEST on wlan0 to 255.255.255.255 port 67
DHCPACK from 192.168.0.1
bound to 192.168.0.254 -- renewal in 300 seconds.
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      ether 00:11:95:d5:43:62
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
      status: associated
      ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
      country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
      AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
      bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
      wme burst roaming MANUAL</screen>

	    <para>Or, try to configure the interface manually using
	      the information in
	      <filename>/etc/wpa_supplicant.conf</filename>:</para>

	    <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</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=CCMP GTK=CCMP]
CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=]</screen>

	    <para>The next operation is to launch &man.dhclient.8;
	      to get the <acronym>IP</acronym> address from the
	      <acronym>DHCP</acronym> server:</para>

	    <screen>&prompt.root; <userinput>dhclient <replaceable>wlan0</replaceable></userinput>
DHCPREQUEST on wlan0 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>wlan0</replaceable></userinput>
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      ether 00:11:95:d5:43:62
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
      status: associated
      ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
      country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
      AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
      bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
      wme burst roaming MANUAL</screen>

	    <note>
	      <para>If <filename>/etc/rc.conf</filename> has an
		<literal>ifconfig_wlan0="DHCP"</literal> entry,
		&man.dhclient.8; will be launched automatically after
		&man.wpa.supplicant.8; associates with the access
		point.</para>
	    </note>

	    <para>If <acronym>DHCP</acronym> is not possible or
	      desired, set a static <acronym>IP</acronym> address
	      after &man.wpa.supplicant.8; has authenticated the
	      station:</para>

	    <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      ether 00:11:95:d5:43:62
      inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255
      media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
      status: associated
      ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
      country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
      AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
      bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
      wme burst roaming MANUAL</screen>

	    <para>When <acronym>DHCP</acronym> is not used, the
	      default gateway and the nameserver also have to be
	      manually set:</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 xml:id="network-wireless-wpa-eap-tls">
	    <title><acronym>WPA</acronym> with
	      <acronym>EAP-TLS</acronym></title>

	    <para>The second way to use <acronym>WPA</acronym> is with
	      an 802.1X backend authentication server.  In this case,
	      <acronym>WPA</acronym> is called
	      <acronym>WPA</acronym> Enterprise to differentiate it
	      from the less secure <acronym>WPA</acronym> Personal.
	      Authentication in <acronym>WPA</acronym> Enterprise is
	      based on the Extensible Authentication Protocol
	      (<acronym>EAP</acronym>).</para>

	    <para><acronym>EAP</acronym> does not come with an
	      encryption method.  Instead, <acronym>EAP</acronym> is
	      embedded inside an encrypted tunnel.  There are many
	      <acronym>EAP</acronym> authentication methods, but
	      <acronym>EAP-TLS</acronym>, <acronym>EAP-TTLS</acronym>,
	      and <acronym>EAP-PEAP</acronym> are the most
	      common.</para>

	    <para>EAP with Transport Layer Security
	      (<acronym>EAP-TLS</acronym>) is a well-supported
	      wireless authentication protocol since it was the
	      first <acronym>EAP</acronym> method to be certified
	      by the <link
		xlink:href="http://www.wi-fi.org/">Wi-Fi
		Alliance</link>.  <acronym>EAP-TLS</acronym> requires
	      three certificates to run: the certificate of the
	      Certificate Authority (<acronym>CA</acronym>) installed
	      on all machines, the server certificate for the
	      authentication server, and one client certificate for
	      each wireless client.  In this <acronym>EAP</acronym>
	      method, both the authentication server and wireless
	      client authenticate each other by presenting their
	      respective certificates, and then verify that these
	      certificates were signed by the organization's
	      <acronym>CA</acronym>.</para>

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

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

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

	      <callout arearefs="co-tls-proto">
		<para>This example uses the <acronym>RSN</acronym>
		  &ieee; 802.11i protocol, also known as
		  <acronym>WPA2</acronym>.</para>
	      </callout>

	      <callout arearefs="co-tls-kmgmt">
		<para>The <literal>key_mgmt</literal> line refers to
		  the key management protocol to use.  In this
		  example, it is <acronym>WPA</acronym> using
		  <acronym>EAP</acronym> authentication.</para>
	      </callout>

	      <callout arearefs="co-tls-eap">
		<para>This field indicates the <acronym>EAP</acronym>
		  method for the connection.</para>
	      </callout>

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

	      <callout arearefs="co-tls-cacert">
		<para>The <literal>ca_cert</literal> field indicates
		  the pathname of the <acronym>CA</acronym>
		  certificate file.  This file is needed to verify
		  the server certificate.</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 lines to
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>

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

	    <screen>&prompt.root; <userinput>service netif start</userinput>
Starting wpa_supplicant.
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      ether 00:11:95:d5:43:62
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
      status: associated
      ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
      country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
      AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
      bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
      wme burst roaming MANUAL</screen>

	    <para>It is also possible to bring up the interface
	      manually using &man.wpa.supplicant.8; and
	      &man.ifconfig.8;.</para>
	  </sect5>

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

	    <para>With <acronym>EAP-TLS</acronym>, both the
	      authentication server and the client need a certificate.
	      With <acronym>EAP-TTLS</acronym>, a client certificate
	      is optional.  This method is similar to a web server
	      which creates a secure <acronym>SSL</acronym> tunnel
	      even if visitors do not have client-side certificates.
	      <acronym>EAP-TTLS</acronym> uses an encrypted
	      <acronym>TLS</acronym> tunnel for safe transport of
	      the authentication data.</para>

	    <para>The required configuration can be added to
	      <filename>/etc/wpa_supplicant.conf</filename>:</para>

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

	    <calloutlist>
	      <callout arearefs="co-ttls-eap">
		<para>This field specifies the <acronym>EAP</acronym>
		  method for the connection.</para>
	      </callout>

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

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

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

	      <callout arearefs="co-ttls-pha2">
		<para>This field specifies the authentication
		  method used in the encrypted <acronym>TLS</acronym>
		  tunnel.  In this example,
		  <acronym>EAP</acronym> with MD5-Challenge is used.
		  The <quote>inner authentication</quote> phase is
		  often called <quote>phase2</quote>.</para>
	      </callout>
	    </calloutlist>

	    <para>Next, add the following lines to
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>

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

	    <screen>&prompt.root; <userinput>service netif start</userinput>
Starting wpa_supplicant.
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      ether 00:11:95:d5:43:62
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
      status: associated
      ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
      country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
      AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
      bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
      wme burst roaming MANUAL</screen>
	  </sect5>

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

	    <note>
	      <para><acronym>PEAPv0/EAP-MSCHAPv2</acronym> is the most
		common <acronym>PEAP</acronym> method.  In this
		chapter, the term <acronym>PEAP</acronym> is used to
		refer to that method.</para>
	    </note>

	    <para>Protected EAP (<acronym>PEAP</acronym>) is designed
	      as an alternative to <acronym>EAP-TTLS</acronym> and
	      is the most used <acronym>EAP</acronym> standard after
	      <acronym>EAP-TLS</acronym>.  In a network with mixed
	      operating systems, <acronym>PEAP</acronym> should be
	      the most supported standard after
	      <acronym>EAP-TLS</acronym>.</para>

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

	    <para>Add the following lines to
	      <filename>/etc/wpa_supplicant.conf</filename> to
	      configure the <acronym>EAP-PEAP</acronym> related
	      settings:</para>

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

	    <calloutlist>
	      <callout arearefs="co-peap-eap">
		<para>This field specifies the <acronym>EAP</acronym>
		  method for the connection.</para>
	      </callout>

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

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

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

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

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

	    <para>Add the following to
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>wlans_ath0="wlan0"
ifconfig_wlan0="WPA DHCP"</programlisting>

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

	    <screen>&prompt.root; <userinput>service netif start</userinput>
Starting wpa_supplicant.
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21
DHCPACK from 192.168.0.20
bound to 192.168.0.254 -- renewal in 300 seconds.
wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
      ether 00:11:95:d5:43:62
      inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
      media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
      status: associated
      ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
      country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
      AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
      bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
      wme burst roaming MANUAL</screen>
	  </sect5>
	</sect4>

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

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

	  <para><acronym>WEP</acronym> can be set up using
	    &man.ifconfig.8;:</para>

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

	  <itemizedlist>
	    <listitem>

	      <para>The <literal>weptxkey</literal> specifies which
		<acronym>WEP</acronym> key will be used in the
		transmission.  This example uses the third key.
		This must match the setting on the access point.
		When unsure which key is used by the access point,
		try <literal>1</literal> (the first key) for this
		value.</para>
	    </listitem>

	    <listitem>
	      <para>The <literal>wepkey</literal> selects one of the
		<acronym>WEP</acronym> keys.  It should be in the
		format <replaceable>index:key</replaceable>.  Key
		<literal>1</literal> is used by default; the index
		only needs to be set when using a key other than the
		first key.</para>

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

	  <para>Refer to &man.ifconfig.8; for further
	    information.</para>

	  <para>The &man.wpa.supplicant.8; facility can be used to
	    configure a wireless interface with
	    <acronym>WEP</acronym>.  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>wlan0</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><acronym>IBSS</acronym> mode, also called ad-hoc mode, is
	designed for point to point connections.  For example, to
	establish an ad-hoc network between the machines
	<systemitem>A</systemitem> and <systemitem>B</systemitem>,
	choose two <acronym>IP</acronym> addresses and a
	<acronym>SSID</acronym>.</para>

      <para>On <systemitem>A</systemitem>:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
  wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	  ether 00:11:95:c3:0d:ac
	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;adhoc&gt;
	  status: running
	  ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
	  country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
	  protmode CTS wme burst</screen>

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

      <para><systemitem>B</systemitem> should now be able to detect
	<systemitem>A</systemitem>:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
  SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
  freebsdap       02:11:95:c3:0d:ac    2   54M -64:-96  100 IS   WME</screen>

      <para>The <literal>I</literal> in the output confirms that
	<systemitem>A</systemitem> is in ad-hoc mode.  Now, configure
	<systemitem>B</systemitem> with a different
	<acronym>IP</acronym> address:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
  wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	  ether 00:11:95:d5:43:62
	  inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;adhoc&gt;
	  status: running
	  ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
	  country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
	  protmode CTS wme burst</screen>

      <para>Both <systemitem>A</systemitem> and
	<systemitem>B</systemitem> are now ready to exchange
	information.</para>
    </sect2>

    <sect2 xml:id="network-wireless-ap">
      <title>&os; Host Access Points</title>

      <para>&os; can act as an Access Point (<acronym>AP</acronym>)
	which eliminates the need to buy a hardware
	<acronym>AP</acronym> or run an ad-hoc network.  This can
	be particularly useful when a &os; machine is acting as a
	gateway to another network such as the Internet.</para>

      <sect3 xml:id="network-wireless-ap-basic">
	<title>Basic Settings</title>

	<para>Before configuring a &os; machine as an
	  <acronym>AP</acronym>, the kernel must be configured with
	  the appropriate networking support for the wireless card
	  as well as the security protocols being used.  For more
	  details, see <xref
	    linkend="network-wireless-basic"/>.</para>

	<note>
	  <para>The <acronym>NDIS</acronym> driver wrapper for
	    &windows; drivers does not currently support
	    <acronym>AP</acronym> operation.  Only native &os;
	    wireless drivers support <acronym>AP</acronym>
	    mode.</para>
	</note>

	<para>Once wireless networking support is loaded, check if
	  the wireless device supports the host-based access point
	  mode, also known as hostap mode:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput>
drivercaps=6f85edc1&lt;STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG&gt;
cryptocaps=1f&lt;WEP,TKIP,AES,AES_CCM,TKIPMIC&gt;</screen>

	<para>This output displays the card's capabilities.  The
	  <literal>HOSTAP</literal> word confirms that this wireless
	  card can act as an <acronym>AP</acronym>.  Various supported
	  ciphers are also listed: <acronym>WEP</acronym>,
	  <acronym>TKIP</acronym>, and <acronym>AES</acronym>.  This
	  information indicates which security protocols can be used
	  on the <acronym>AP</acronym>.</para>

	<para>The wireless device can only be put into hostap mode
	  during the creation of the network pseudo-device, so a
	  previously created device must be destroyed first:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> destroy</userinput></screen>

	<para>then regenerated with the correct option before setting
	  the other parameters:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen>

	<para>Use &man.ifconfig.8; again to see the status of the
	  <filename>wlan0</filename> interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
  wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	  ether 00:11:95:c3:0d:ac
	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;hostap&gt;
	  status: running
	  ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	  country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
	  protmode CTS wme burst dtimperiod 1 -dfs</screen>

	<para>The <literal>hostap</literal> parameter indicates the
	  interface is running in the host-based access point
	  mode.</para>

	<para>The interface configuration can be done automatically at
	  boot time by adding the following lines to
	  <filename>/etc/rc.conf</filename>:</para>

	<programlisting>wlans_ath0="wlan0"
create_args_wlan0="wlanmode hostap"
ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel <replaceable>1</replaceable>"</programlisting>
      </sect3>

      <sect3>
	<title>Host-based Access Point Without Authentication or
	  Encryption</title>

	<para>Although it is not recommended to run an
	  <acronym>AP</acronym> without any authentication or
	  encryption, this is a simple way to check if the
	  <acronym>AP</acronym> is working.  This configuration is
	  also important for debugging client issues.</para>

	<para>Once the <acronym>AP</acronym> is configured, initiate
	  a scan from another wireless machine to find the
	  <acronym>AP</acronym>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
freebsdap       00:11:95:c3:0d:ac    1   54M -66:-96  100 ES   WME</screen>

	<para>The client machine found the <acronym>AP</acronym> and
	  can be associated with it:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
  wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	  ether 00:11:95:d5:43:62
	  inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
	  media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
	  status: associated
	  ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
	  country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
	  scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
	  roam:rate 5 protmode CTS wme burst</screen>
      </sect3>

      <sect3 xml:id="network-wireless-ap-wpa">
	<title><acronym>WPA2</acronym> Host-based Access Point</title>

	<para>This section focuses on setting up a &os;
	  access point using the <acronym>WPA2</acronym>
	  security protocol.  More details regarding
	  <acronym>WPA</acronym> and the configuration of
	  <acronym>WPA</acronym>-based wireless clients can be found
	  in <xref linkend="network-wireless-wpa"/>.</para>

	<para>The &man.hostapd.8; daemon is used to deal with client
	  authentication and key management on the
	  <acronym>WPA2</acronym>-enabled
	  <acronym>AP</acronym>.</para>

	<para>The following configuration operations are performed
	  on the &os; machine acting as the <acronym>AP</acronym>.
	  Once the <acronym>AP</acronym> is correctly working,
	  &man.hostapd.8; can be automatically started at boot
	  with this line in
	  <filename>/etc/rc.conf</filename>:</para>

	<programlisting>hostapd_enable="YES"</programlisting>

	<para>Before trying to configure &man.hostapd.8;, first
	  configure the basic settings introduced in <xref
	    linkend="network-wireless-ap-basic"/>.</para>

	<sect4>
	  <title><acronym>WPA2-PSK</acronym></title>

	  <para><acronym>WPA2-PSK</acronym> is intended for small
	    networks where the use of a backend authentication server
	    is not possible or desired.</para>

	  <para>The configuration is done in
	    <filename>/etc/hostapd.conf</filename>:</para>

	  <programlisting>interface=wlan0                  <co xml:id="co-ap-wpapsk-iface"/>
debug=1                          <co xml:id="co-ap-wpapsk-dbug"/>
ctrl_interface=/var/run/hostapd  <co xml:id="co-ap-wpapsk-ciface"/>
ctrl_interface_group=wheel       <co xml:id="co-ap-wpapsk-cifacegrp"/>
ssid=freebsdap                   <co xml:id="co-ap-wpapsk-ssid"/>
wpa=2                            <co xml:id="co-ap-wpapsk-wpa"/>
wpa_passphrase=freebsdmall       <co xml:id="co-ap-wpapsk-pass"/>
wpa_key_mgmt=WPA-PSK             <co xml:id="co-ap-wpapsk-kmgmt"/>
wpa_pairwise=CCMP                <co xml:id="co-ap-wpapsk-pwise"/></programlisting>

	  <calloutlist>
	    <callout arearefs="co-ap-wpapsk-iface">
	      <para>Wireless interface used
		for the access point.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-dbug">
	      <para>Level of verbosity used during the
		execution of &man.hostapd.8;.  A value of
		<literal>1</literal> represents the minimal
		level.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-ciface">
	      <para>Pathname of the directory used by &man.hostapd.8;
		to store domain socket files for communication
		with external programs such as &man.hostapd.cli.8;.
		The default value is used in this example.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-cifacegrp">
	      <para>The group allowed to access the control
		interface files.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-ssid">
	      <para>The wireless network name, or
		<acronym>SSID</acronym>, that will appear in wireless
		scans.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-wpa">
	      <para>Enable
		<acronym>WPA</acronym> and specify which
		<acronym>WPA</acronym> authentication protocol will
		be required.  A value of <literal>2</literal>
		configures the <acronym>AP</acronym> for
		<acronym>WPA2</acronym> and is recommended.
		Set to <literal>1</literal> only if the obsolete
		<acronym>WPA</acronym> is required.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-pass">
	      <para>ASCII passphrase for
		<acronym>WPA</acronym> authentication.</para>

	      <warning>
		<para>Always use strong passwords that are at least
		  8 characters long and made from a rich alphabet so
		  that they will not be easily guessed or
		  attacked.</para>
	      </warning>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-kmgmt">
	      <para>The
		key management protocol to use.  This example
		sets <acronym>WPA-PSK</acronym>.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-pwise">
	      <para>Encryption algorithms accepted by
		the access point.  In this example, only
		the
		<acronym>CCMP</acronym> (<acronym>AES</acronym>)
		cipher is accepted.  <acronym>CCMP</acronym>
		is an alternative to <acronym>TKIP</acronym>
		and is strongly preferred when possible.
		<acronym>TKIP</acronym> should be allowed only when
		there are stations incapable of using
		<acronym>CCMP</acronym>.</para>
	    </callout>
	  </calloutlist>

	  <para>The next step is to start &man.hostapd.8;:</para>

	  <screen>&prompt.root; <userinput>service hostapd forcestart</userinput></screen>

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
wlan0: flags=8943&lt;UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	ether 04:f0:21:16:8e:10
	inet6 fe80::6f0:21ff:fe16:8e10%wlan0 prefixlen 64 scopeid 0x9
	nd6 options=21&lt;PERFORMNUD,AUTO_LINKLOCAL&gt;
	media: IEEE 802.11 Wireless Ethernet autoselect mode 11na &lt;hostap&gt;
	status: running
	ssid No5ignal channel 36 (5180 MHz 11a ht/40+) bssid 04:f0:21:16:8e:10
	country US ecm authmode WPA2/802.11i privacy MIXED deftxkey 2
	AES-CCM 2:128-bit AES-CCM 3:128-bit txpower 17 mcastrate 6 mgmtrate 6
	scanvalid 60 ampdulimit 64k ampdudensity 8 shortgi wme burst
	dtimperiod 1 -dfs
	groups: wlan</screen>

	  <para>Once the <acronym>AP</acronym> is running, the
	    clients can associate with it.  See <xref
	      linkend="network-wireless-wpa"/> for more details.  It
	    is possible to see the stations associated with the
	    <acronym>AP</acronym> using <command>ifconfig
	      <replaceable>wlan0</replaceable> list
	      sta</command>.</para>
	</sect4>
      </sect3>

      <sect3>
	<title><acronym>WEP</acronym> Host-based Access Point</title>

	<para>It is not recommended to use <acronym>WEP</acronym> for
	  setting up an <acronym>AP</acronym> since there is no
	  authentication mechanism and the encryption is easily
	  cracked.  Some legacy wireless cards only support
	  <acronym>WEP</acronym> and these cards will only support
	  an <acronym>AP</acronym> without authentication or
	  encryption.</para>

	<para>The wireless device can now be put into hostap mode and
	  configured with the correct <acronym>SSID</acronym> and
	  <acronym>IP</acronym> address:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
	ssid <replaceable>freebsdap</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable> mode 11g</userinput></screen>

	<itemizedlist>
	  <listitem>
	    <para>The <literal>weptxkey</literal> indicates which
	      <acronym>WEP</acronym> key will be used in the
	      transmission.  This example uses the third key as key
	      numbering starts with <literal>1</literal>.  This
	      parameter must be specified in order to encrypt the
	      data.</para>
	  </listitem>

	  <listitem>
	    <para>The <literal>wepkey</literal> sets the selected
	      <acronym>WEP</acronym> key.  It should be in the format
	      <replaceable>index:key</replaceable>.  If the index is
	      not given, key <literal>1</literal> is set.  The index
	      needs to be set when using keys other than the first
	      key.</para>
	  </listitem>
	</itemizedlist>

	<para>Use &man.ifconfig.8; to see the status of the
	  <filename>wlan0</filename> interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
  wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	  ether 00:11:95:c3:0d:ac
	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;hostap&gt;
	  status: running
	  ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac
	  country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit
	  txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs</screen>

	<para>From another wireless machine, it is now possible to
	  initiate a scan to find the <acronym>AP</acronym>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
SSID            BSSID              CHAN RATE  S:N   INT CAPS
freebsdap       00:11:95:c3:0d:ac    1   54M 22:1   100 EPS</screen>

	<para>In this example, the client machine found the
	  <acronym>AP</acronym> and can associate with it using the
	  correct parameters.  See <xref
	    linkend="network-wireless-wep"/> for more details.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Using Both Wired and Wireless Connections</title>

      <para>A wired connection provides better performance and
	reliability, while a wireless connection provides flexibility
	and mobility.  Laptop users typically want to roam seamlessly
	between the two types of connections.</para>

      <para>On &os;, it is possible to combine two or even more
	network interfaces together in a <quote>failover</quote>
	fashion.  This type of configuration uses the most preferred
	and available connection from a group of network interfaces,
	and the operating system switches automatically when the link
	state changes.</para>

      <para>Link aggregation and failover is covered in <xref
	  linkend="network-aggregation"/> and an example for using
	both wired and wireless connections is provided at <xref
	  linkend="networking-lagg-wired-and-wireless"/>.</para>
    </sect2>

    <sect2>
      <title>Troubleshooting</title>

      <para>This section describes
	a number of steps to help troubleshoot common wireless
	networking problems.</para>

      <itemizedlist>
	<listitem>
	  <para>If the access point is not listed when scanning,
	    check that the configuration has not limited the wireless
	    device to a limited set of channels.</para>
	</listitem>

	<listitem>
	  <para>If the device cannot associate with an access point,
	    verify that the configuration matches the settings on the
	    access point.  This includes the authentication scheme and
	    any security protocols.  Simplify the configuration as
	    much as possible.  If using a security protocol such as
	    <acronym>WPA</acronym> or <acronym>WEP</acronym>,
	    configure the access point for open authentication and
	    no security to see if traffic will pass.</para>

	  <para>Debugging support is provided by
	    &man.wpa.supplicant.8;.  Try running this utility manually
	    with <option>-dd</option> and look at the
	    system logs.</para>
	</listitem>

	<listitem>
	  <para>Once the system can associate with the access point,
	    diagnose the network configuration using tools like
	    &man.ping.8;.</para>
	</listitem>

	<listitem>
	  <para>There are many lower-level debugging tools.
	    Debugging messages can be enabled in the 802.11 protocol
	    support layer using &man.wlandebug.8;.
	    For example, to enable console messages related to
	    scanning for access points and the 802.11 protocol
	    handshakes required to arrange communication:</para>

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

	  <para>Many useful statistics are maintained by the 802.11
	    layer and <command>wlanstats</command>, found in <filename
	      >/usr/src/tools/tools/net80211</filename>,
	    will dump this information.  These statistics should
	    display all errors identified by the 802.11 layer.
	    However, 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, refer to the
	    drivers' documentation.</para>
	</listitem>
      </itemizedlist>

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

  <sect1 xml:id="network-usb-tethering">
    <info>
      <title>USB Tethering</title>
    </info>

    <indexterm>
      <primary>tether</primary>
    </indexterm>

    <para>Many cellphones provide the option to share their data
      connection over USB (often called "tethering").  This feature
      uses either the <acronym>RNDIS</acronym>, <acronym>CDC</acronym>
      or a custom &apple; &iphone;/&ipad;
      protocol.</para>

    <itemizedlist>
      <listitem>
	<para>&android; devices generally use the &man.urndis.4;
	  driver.</para>
      </listitem>

      <listitem>
	<para>&apple; devices use the &man.ipheth.4; driver.</para>
      </listitem>

      <listitem>
	<para>Older devices will often use the &man.cdce.4;
	  driver.</para>
      </listitem>
    </itemizedlist>

    <para>Before attaching a device, load the appropriate driver
      into the kernel:</para>

    <screen>&prompt.root; <userinput>kldload if_urndis
&prompt.root; kldload if_cdce
&prompt.root; kldload if_ipheth</userinput></screen>

    <para>Once the device is attached
      <literal>ue</literal><replaceable>0</replaceable> will be
      available for use like a normal network device.  Be sure that
      the <quote>USB tethering</quote> option is enabled on the
      device.</para>
  </sect1>

  <sect1 xml:id="network-bluetooth">
    <info>
      <title>Bluetooth</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Pav</firstname>
	    <surname>Lucistnik</surname>
	  </personname>
	  <contrib>Written by </contrib>
	  <email>pav@FreeBSD.org</email>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>Bluetooth</primary>
    </indexterm>

    <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 Wi-Fi wireless technology, Bluetooth offers
      higher level service profiles, such as
      <acronym>FTP</acronym>-like file servers, file pushing, voice
      transport, serial line emulation, and more.</para>

    <para>This section describes the use of a <acronym>USB</acronym>
      Bluetooth dongle on a &os; system.  It then describes the
      various Bluetooth protocols and utilities.</para>

    <sect2>
      <title>Loading Bluetooth Support</title>

      <para>The Bluetooth stack in &os; is implemented using the
	&man.netgraph.4; framework.  A broad variety of Bluetooth
	<acronym>USB</acronym> dongles is supported by &man.ng.ubt.4;.
	Broadcom BCM2033 based Bluetooth devices are supported by 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 by &man.sio.4;, &man.ng.h4.4;, and
	&man.hcseriald.8;.</para>

      <para>Before attaching a device, determine which of the above
	drivers it uses, then load the driver.  For example, if the
	device uses the &man.ng.ubt.4; driver:</para>

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

      <para>If the Bluetooth device will be attached to the system
	during system startup, the system can be configured to load
	the module at boot time by adding the driver to
	<filename>/boot/loader.conf</filename>:</para>

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

      <para>Once the driver is loaded, plug in the
	<acronym>USB</acronym> dongle.  If the driver load was
	successful, output similar to the following should appear on
	the console and in
	<filename>/var/log/messages</filename>:</para>

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

      <para>To start and stop the Bluetooth stack, use its startup
	script.  It is a good idea to stop the stack before unplugging
	the device.  When starting the stack, the output should be
	similar to the following:</para>

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

    <sect2>
      <title>Finding Other Bluetooth Devices</title>

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

      <para>The Host Controller Interface (<acronym>HCI</acronym>)
	provides a uniform method for accessing Bluetooth baseband
	capabilities.  In &os;, a netgraph <acronym>HCI</acronym> node
	is created for each Bluetooth device.  For more details, refer
	to &man.ng.hci.4;.</para>

      <para>One of the most common tasks is discovery of Bluetooth
	devices within <acronym>RF</acronym> proximity.  This
	operation is called <emphasis>inquiry</emphasis>.  Inquiry and
	other <acronym>HCI</acronym> related operations are done using
	&man.hccontrol.8;.  The example below shows how to find out
	which Bluetooth devices are in range.  The list of devices
	should be displayed in a few seconds.  Note that a remote
	device will only answer the inquiry if it is set to
	<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>The <literal>BD_ADDR</literal> is the unique address of a
	Bluetooth device, similar to the <acronym>MAC</acronym>
	address of a network card.  This address is needed for further
	communication with a device and it is possible to assign a
	human readable name to a BD_ADDR.  Information regarding the
	known Bluetooth hosts is contained in
	<filename>/etc/bluetooth/hosts</filename>.  The following
	example shows how to obtain the 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 an inquiry is performed on a remote Bluetooth device,
	it will find the 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
	between two Bluetooth units, or a point-to-multipoint
	connection which 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, though
	it is normally not required to do this 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>Type <command>hccontrol help</command> for a complete
	listing of available <acronym>HCI</acronym> commands.  Most
	of the <acronym>HCI</acronym> commands do not require
	superuser privileges.</para>
    </sect2>

    <sect2>
      <title>Device Pairing</title>

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

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

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

      <para>The only limitation on <acronym>PIN</acronym> codes is
	length.  Some devices, such as Bluetooth headsets, may have
	a fixed <acronym>PIN</acronym> code built in.  The
	<option>-d</option> switch forces &man.hcsecd.8; 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 indicate that pairing was accepted and request the
	<acronym>PIN</acronym> code.  Enter the same
	<acronym>PIN</acronym> code listed in
	<filename>hcsecd.conf</filename>.  Now the computer and the
	remote device are paired.  Alternatively, pairing can be
	initiated on the remote device.</para>

      <para>The following line can be added to
	<filename>/etc/rc.conf</filename> to configure &man.hcsecd.8;
	to start automatically on system start:</para>

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

      <para>The following is a sample of the &man.hcsecd.8; 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>Network Access with
	<acronym>PPP</acronym> Profiles</title>

      <para>A Dial-Up Networking (<acronym>DUN</acronym>) profile can
	be used to configure a cellular phone as a wireless modem for
	connecting to a dial-up Internet access server.  It can also
	be used to configure a computer to receive data calls from a
	cellular phone.</para>

      <para>Network access with a <acronym>PPP</acronym> profile can
	be used to provide <acronym>LAN</acronym> access for a single
	Bluetooth device or multiple Bluetooth devices.  It can also
	provide <acronym>PC</acronym> to <acronym>PC</acronym>
	connection using <acronym>PPP</acronym> networking over serial
	cable emulation.</para>

      <para>In &os;, these profiles are implemented with &man.ppp.8;
	and the &man.rfcomm.pppd.8; wrapper which converts a
	Bluetooth connection into something
	<acronym>PPP</acronym> can use.  Before a profile can be used,
	a new <acronym>PPP</acronym> label must be created in
	<filename>/etc/ppp/ppp.conf</filename>.  Consult
	&man.rfcomm.pppd.8; for examples.</para>

      <para>In this example, &man.rfcomm.pppd.8; is used to open a
	connection to a remote device with a
	<literal>BD_ADDR</literal> of
	<literal>00:80:37:29:19:a4</literal> on a
	<acronym>DUN</acronym> <acronym>RFCOMM</acronym>
	channel:</para>

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

      <para>The actual channel number will be obtained from the remote
	device using the <acronym>SDP</acronym> protocol.  It is
	possible to specify the <acronym>RFCOMM</acronym> channel by
	hand, and in this case &man.rfcomm.pppd.8; will not perform
	the <acronym>SDP</acronym> query.  Use &man.sdpcontrol.8; to
	find out the <acronym>RFCOMM</acronym> channel on the remote
	device.</para>

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

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

    <sect2>
      <title>Bluetooth Protocols</title>

      <para>This section provides an overview of the various Bluetooth
	protocols, their function, and associated utilities.</para>

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

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

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

	<para><acronym>L2CAP</acronym> is based around the concept of
	  <emphasis>channels</emphasis>.  A channel is a logical
	  connection on top of a baseband connection, where 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 <acronym>L2CAP</acronym> packet received on
	  a channel is directed to the appropriate higher level
	  protocol.  Multiple channels can share the same baseband
	  connection.</para>

	<para>In &os;, a netgraph <acronym>L2CAP</acronym> node is
	  created for each Bluetooth device.  This node is normally
	  connected to the downstream Bluetooth <acronym>HCI</acronym>
	  node and upstream Bluetooth socket nodes.  The default name
	  for the <acronym>L2CAP</acronym> node is
	  <quote>devicel2cap</quote>.  For more details refer to
	  &man.ng.l2cap.4;.</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 <acronym>L2CAP</acronym> 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 is
	  similar to &man.netstat.1;, 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>
      </sect3>

      <sect3>
	<title>Radio Frequency Communication
	  (<acronym>RFCOMM</acronym>)</title>

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

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

	<para><acronym>RFCOMM</acronym> 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.
	  <acronym>RFCOMM</acronym> 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;, <acronym>RFCOMM</acronym> is implemented at the
	  Bluetooth sockets layer.</para>
      </sect3>

      <sect3>
	<title>Service Discovery Protocol
	  (<acronym>SDP</acronym>)</title>

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

	<para>The Service Discovery Protocol (<acronym>SDP</acronym>)
	  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><acronym>SDP</acronym> involves communication between a
	  <acronym>SDP</acronym> server and a <acronym>SDP</acronym>
	  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 <acronym>SDP</acronym>
	  server by issuing a <acronym>SDP</acronym> 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.
	  <acronym>SDP</acronym> provides a mechanism for discovering
	  services and their attributes, but it does not provide a
	  mechanism for utilizing those services.</para>

	<para>Normally, a <acronym>SDP</acronym> 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
	  <acronym>SDP</acronym> server's service records without any
	  prior information about the services.  This process of
	  looking for any offered services is called
	  <emphasis>browsing</emphasis>.</para>

	<para>The Bluetooth <acronym>SDP</acronym> 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
	  <acronym>SDP</acronym> 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>Note that each service has a list of attributes, such
	  as the <acronym>RFCOMM</acronym> channel.  Depending on the
	  service, the user might need to make 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
	  <acronym>OBEX</acronym> Object Push
	  (<acronym>OPUSH</acronym>) 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.  The following line can be
	  added to <filename>/etc/rc.conf</filename>:</para>

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

	<para>Then the &man.sdpd.8; daemon can be started with:</para>

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

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

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

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

      <sect3>
	<title><acronym>OBEX</acronym> Object Push
	  (<acronym>OPUSH</acronym>)</title>

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

	<para>Object Exchange (<acronym>OBEX</acronym>) 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
	  <acronym>PDA</acronym>s, and for sending business cards or
	  calendar entries between cellular phones and other devices
	  with Personal Information Manager (<acronym>PIM</acronym>)
	  applications.</para>

	<para>The <acronym>OBEX</acronym> server and client are
	  implemented by <application>obexapp</application>, which can
	  be installed using the <package>comms/obexapp</package>
	  package or port.</para>

	<para>The <acronym>OBEX</acronym> client is used to push
	  and/or pull objects from the <acronym>OBEX</acronym> server.
	  An example object is a business card or an appointment.
	  The <acronym>OBEX</acronym> client can obtain the
	  <acronym>RFCOMM</acronym> channel number from the remote
	  device via <acronym>SDP</acronym>.  This can be done by
	  specifying the service name instead of the
	  <acronym>RFCOMM</acronym> channel number.  Supported service
	  names are: <literal>IrMC</literal>, <literal>FTRN</literal>,
	  and <literal>OPUSH</literal>.  It is also possible to
	  specify the <acronym>RFCOMM</acronym> channel as a number.
	  Below is an example of an <acronym>OBEX</acronym> session
	  where the device information object is pulled from the
	  cellular phone, and a new object, the 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 the <acronym>OPUSH</acronym>
	  service, &man.sdpd.8; must be running and 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 the
	  <acronym>OBEX</acronym> server on a valid
	  <acronym>RFCOMM</acronym> channel number.  The
	  <acronym>OBEX</acronym> server will automatically register
	  the <acronym>OPUSH</acronym> service with the local
	  <acronym>SDP</acronym> daemon.  The example below shows how
	  to start the <acronym>OBEX</acronym> server.</para>

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

      <sect3>
	<title>Serial Port Profile (<acronym>SPP</acronym>)</title>

	<para>The Serial Port Profile (<acronym>SPP</acronym>) allows
	  Bluetooth devices to perform serial cable emulation.  This
	  profile allows legacy applications to use Bluetooth as a
	  cable replacement, through a virtual serial port
	  abstraction.</para>

	<para>In &os;, &man.rfcomm.sppd.1; implements
	  <acronym>SPP</acronym> and a pseudo tty is used as a virtual
	  serial port abstraction.  The example below shows how to
	  connect to a remote device's serial port service.  A
	  <acronym>RFCOMM</acronym> channel does not have to be
	  specified as &man.rfcomm.sppd.1; can obtain it from the
	  remote device via <acronym>SDP</acronym>.  To override this,
	  specify a <acronym>RFCOMM</acronym> channel on the command
	  line.</para>

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

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

	<screen>&prompt.root; <userinput>cu -l /dev/pts/6</userinput></screen>

	<para>The pseudo tty is printed on stdout and can be read by
	  wrapper scripts:</para>

	<programlisting>PTS=`rfcomm_sppd -a 00:07:E0:00:0B:CA -t`
cu -l $PTS</programlisting>
      </sect3>
    </sect2>

    <sect2>
      <title>Troubleshooting</title>

      <para>By default, when &os; is accepting a new connection, it
	tries to perform a role switch and become master.  Some older
	Bluetooth devices which do not support role switching will not
	be able to connect.  Since role switching is performed when a
	new connection is being established, it is not possible to ask
	the remote device if it supports role switching.  However,
	there is a <acronym>HCI</acronym> option to disable role
	switching on the local side:</para>

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

      <para>To display Bluetooth packets, use the third-party package
	<application>hcidump</application>, which can be installed
	using the <package>comms/hcidump</package> package or port.
	This utility is similar to &man.tcpdump.1; and can be used to
	display the contents of Bluetooth packets on the terminal and
	to dump the Bluetooth packets to a file.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="network-bridging">
    <info>
      <title>Bridging</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Andrew</firstname>
	    <surname>Thompson</surname>
	  </personname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary><acronym>IP</acronym> subnet</primary>
    </indexterm>
    <indexterm>
      <primary>bridge</primary>
    </indexterm>

    <para>It is sometimes useful to divide a network, such as an
      Ethernet segment, into network segments without having to
      create <acronym>IP</acronym> 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>.</para>

    <para>A bridge works by learning the <acronym>MAC</acronym>
      addresses of the devices on each of its network interfaces.  It
      forwards traffic between networks only when the source and
      destination <acronym>MAC</acronym> addresses are on different
      networks.  In many respects, a bridge is like an Ethernet switch
      with very few ports.    A &os; system with multiple network
      interfaces can be configured to act as a bridge.</para>

    <para>Bridging can be useful in the following situations:</para>

    <variablelist>
      <varlistentry>
	<term>Connecting Networks</term>
	<listitem>
	  <para>The basic operation of a bridge is to join two or more
	    network segments.  There are many reasons to use a
	    host-based bridge instead of networking equipment, such as
	    cabling constraints or firewalling.  A bridge can also
	    connect a wireless interface running in hostap mode to a
	    wired network and act as an access point.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Filtering/Traffic Shaping Firewall</term>
	<listitem>
	  <para>A bridge can be used when firewall functionality is
	    needed without routing or Network Address Translation
	    (<acronym>NAT</acronym>).</para>

	  <para>An example is a small company that is connected via
	    <acronym>DSL</acronym> or <acronym>ISDN</acronym> to an
	    <acronym>ISP</acronym>.  There are thirteen public
	    <acronym>IP</acronym> addresses from the
	    <acronym>ISP</acronym> and ten computers on the network.
	    In this situation, using a router-based firewall is
	    difficult because of subnetting issues.  A bridge-based
	    firewall can be configured without any
	    <acronym>IP</acronym> addressing issues.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Network Tap</term>
	<listitem>
	  <para>A bridge can join two network segments in order to
	    inspect all Ethernet frames that pass between them using
	    &man.bpf.4; and &man.tcpdump.1; on the bridge interface or
	    by sending a copy of all frames out an additional
	    interface known as a span port.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Layer 2 <acronym>VPN</acronym></term>
	<listitem>
	  <para>Two Ethernet networks can be joined across an
	    <acronym>IP</acronym> link by bridging the networks to an
	    EtherIP tunnel or a &man.tap.4; based solution such as
	    <application>OpenVPN</application>.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>Layer 2 Redundancy</term>
	<listitem>
	  <para>A network can be connected together with multiple
	    links and use the Spanning Tree Protocol
	    (<acronym>STP</acronym>) to block redundant paths.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>This section describes how to configure a &os; system as a
      bridge using &man.if.bridge.4;.  A netgraph bridging driver is
      also available, and is described in &man.ng.bridge.4;.</para>

    <note>
      <para>Packet filtering can be used with any firewall package
	that hooks into the &man.pfil.9; framework.  The bridge can be
	used as a traffic shaper with &man.altq.4; or
	&man.dummynet.4;.</para>
    </note>

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

      <para>In &os;, &man.if.bridge.4; is a kernel module which is
	automatically loaded by &man.ifconfig.8; when creating a
	bridge interface.  It is also possible to compile bridge
	support into a custom kernel by adding
	<literal>device if_bridge</literal> to the custom kernel
	configuration file.</para>

      <para>The bridge is created using interface cloning.  To create
	the bridge interface:</para>

      <screen>&prompt.root; <userinput>ifconfig bridge create</userinput>
bridge0
&prompt.root; <userinput>ifconfig bridge0</userinput>
bridge0: flags=8802&lt;BROADCAST,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
        ether 96:3d:4b:f1:79:7a
        id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15
        maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
        root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0</screen>

      <para>When a bridge interface is created, it is automatically
	assigned a randomly generated Ethernet address.  The
	<literal>maxaddr</literal> and <literal>timeout</literal>
	parameters control how many <acronym>MAC</acronym> addresses
	the bridge will keep in its forwarding table and how many
	seconds before each entry is removed after it is last seen.
	The other parameters control how <acronym>STP</acronym>
	operates.</para>

      <para>Next, specify which network interfaces to add as members
	of the bridge.  For the bridge to forward packets, all member
	interfaces and the bridge need to be up:</para>

      <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 up</userinput>
&prompt.root; <userinput>ifconfig fxp0 up</userinput>
&prompt.root; <userinput>ifconfig fxp1 up</userinput></screen>

      <para>The bridge can now forward Ethernet frames between
	<filename>fxp0</filename> and <filename>fxp1</filename>.  Add
	the following lines to <filename>/etc/rc.conf</filename> so
	the bridge is created at startup:</para>

      <programlisting>cloned_interfaces="bridge0"
ifconfig_bridge0="addm fxp0 addm fxp1 up"
ifconfig_fxp0="up"
ifconfig_fxp1="up"</programlisting>

      <para>If the bridge host needs an <acronym>IP</acronym>
	address, set it on the bridge interface, not on the member
	interfaces.  The address can be set statically or via
	<acronym>DHCP</acronym>.  This example sets a static
	<acronym>IP</acronym> address:</para>

      <screen>&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>

      <para>It is also possible to assign an <acronym>IPv6</acronym>
	address to a bridge interface.  To make the changes permanent,
	add the addressing information to
	<filename>/etc/rc.conf</filename>.</para>

      <note>
	<para>When packet filtering is enabled, bridged packets will
	  pass through the filter inbound on the originating interface
	  on the bridge interface, and outbound on the appropriate
	  interfaces.  Either stage can be disabled.  When direction
	  of the packet flow is important, it is best to firewall on
	  the member interfaces rather than the bridge itself.</para>

	<para>The bridge has several configurable settings for passing
	  non-<acronym>IP</acronym> and <acronym>IP</acronym> packets,
	  and layer2 firewalling with &man.ipfw.8;.  See
	  &man.if.bridge.4; for more information.</para>
      </note>
    </sect2>

    <sect2>
      <title>Enabling Spanning Tree</title>

      <para>For an Ethernet network to function properly, only one
	active path can exist between two devices.  The
	<acronym>STP</acronym> protocol detects loops and puts
	redundant links into a blocked state.  Should one of the
	active links fail, <acronym>STP</acronym> calculates a
	different tree and enables one of the blocked paths to restore
	connectivity to all points in the network.</para>

      <para>The Rapid Spanning Tree Protocol (<acronym>RSTP</acronym>
	or 802.1w) provides backwards compatibility with legacy
	<acronym>STP</acronym>.  <acronym>RSTP</acronym> provides
	faster convergence and exchanges information with neighboring
	switches to quickly transition to forwarding mode without
	creating loops.  &os; supports <acronym>RSTP</acronym> and
	<acronym>STP</acronym> as operating modes, with
	<acronym>RSTP</acronym> being the default mode.</para>

      <para><acronym>STP</acronym> can be enabled on member interfaces
	using &man.ifconfig.8;.  For a bridge with
	<filename>fxp0</filename> and <filename>fxp1</filename> as the
	current interfaces, enable <acronym>STP</acronym> with:</para>

      <screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput>
bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
        ether d6:cf:d5:a0:94:6d
        id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15
        maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
        root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0
        member: fxp0 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
                port 3 priority 128 path cost 200000 proto rstp
                role designated state forwarding
        member: fxp1 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
                port 4 priority 128 path cost 200000 proto rstp
                role designated state forwarding</screen>

      <para>This bridge has a spanning tree ID of
	<literal>00:01:02:4b:d4:50</literal> and a priority of
	<literal>32768</literal>.  As the <literal>root id</literal>
	is the same, it indicates that this is the root bridge for the
	tree.</para>

      <para>Another bridge on the network also has
	<acronym>STP</acronym> enabled:</para>

      <screen>bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
        ether 96:3d:4b:f1:79:7a
        id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15
        maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
        root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4
        member: fxp0 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
                port 4 priority 128 path cost 200000 proto rstp
                role root state forwarding
        member: fxp1 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
                port 5 priority 128 path cost 200000 proto rstp
                role designated state forwarding</screen>

      <para>The line <literal>root id 00:01:02:4b:d4:50 priority 32768
	  ifcost 400000 port 4</literal> shows that the root bridge is
	<literal>00:01:02:4b:d4:50</literal> and has a path cost of
	<literal>400000</literal> from this bridge.  The path to the
	root bridge is via <literal>port 4</literal> which is
	<filename>fxp0</filename>.</para>
    </sect2>

    <sect2>
      <title>Bridge Interface Parameters</title>

      <para>Several <command>ifconfig</command> parameters are unique
	to bridge interfaces.  This section summarizes some common
	uses for these parameters.  The complete list of available
	parameters is described in &man.ifconfig.8;.</para>

      <variablelist>
	<varlistentry>
	  <term>private</term>
	  <listitem>
	    <para>A private interface does not forward any traffic to
	      any other port that is also designated as a private
	      interface.  The traffic is blocked unconditionally so no
	      Ethernet frames will be forwarded, including
	      <acronym>ARP</acronym> packets.  If traffic needs to be
	      selectively blocked, a firewall should be used
	      instead.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>span</term>
	  <listitem>
	    <para>A span port transmits a copy of every Ethernet frame
	      received by the bridge.  The number of span ports
	      configured on a bridge is unlimited, but if an
	      interface is designated as a span port, it cannot also
	      be used as a regular bridge port.  This is most useful
	      for snooping a bridged network passively on another host
	      connected to one of the span ports of the bridge.  For
	      example, to send a copy of all frames out the interface
	      named <filename>fxp4</filename>:</para>

	    <screen>&prompt.root; <userinput>ifconfig bridge0 span fxp4</userinput></screen>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>sticky</term>
	  <listitem>
	    <para>If a bridge member interface is marked as sticky,
	      dynamically learned address entries are treated as
	      static entries in the forwarding cache.  Sticky entries
	      are never aged out of the cache or replaced, even if the
	      address is seen on a different interface.  This gives
	      the benefit of static address entries without the need
	      to pre-populate the forwarding table.  Clients learned
	      on a particular segment of the bridge cannot roam to
	      another segment.</para>

	    <para>An example of using sticky addresses is to combine
	      the bridge with <acronym>VLAN</acronym>s in order to
	      isolate customer networks without wasting
	      <acronym>IP</acronym> address space.  Consider that
	      <systemitem class="fqdomainname">CustomerA</systemitem>
	      is on <literal>vlan100</literal>, <systemitem
		class="fqdomainname">CustomerB</systemitem> is on
	      <literal>vlan101</literal>, and the bridge has the
	      address <systemitem
		class="ipaddress">192.168.0.1</systemitem>:</para>

	    <screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput>
&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>

	    <para>In this example, both clients see <systemitem
		class="ipaddress">192.168.0.1</systemitem> as their
	      default gateway.  Since the bridge cache is sticky, one
	      host cannot spoof the <acronym>MAC</acronym> address of
	      the other customer in order to intercept their
	      traffic.</para>

	    <para>Any communication between the
	      <acronym>VLAN</acronym>s can be blocked using a firewall
	      or, as seen in this example, private interfaces:</para>

	    <screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen>

	    <para>The customers are completely isolated from each
	      other and the full <systemitem
		class="netmask">/24</systemitem> address range can be
	      allocated without subnetting.</para>

	    <para>The number of unique source <acronym>MAC</acronym>
	      addresses behind an interface can be limited.  Once the
	      limit is reached, packets with unknown source addresses
	      are dropped until an existing host cache entry expires
	      or is removed.</para>

	    <para>The following example sets the maximum number of
	      Ethernet devices for <systemitem
		class="fqdomainname">CustomerA</systemitem> on
	      <literal>vlan100</literal> to 10:</para>

	    <screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>Bridge interfaces also support monitor mode, where the
	packets are discarded after &man.bpf.4; processing and are not
	processed or forwarded further.  This can be used to
	multiplex the input of two or more interfaces into a single
	&man.bpf.4; stream.  This is useful for reconstructing the
	traffic for network taps that transmit the RX/TX signals out
	through two separate interfaces.  For example, to read the
	input from four network interfaces as one stream:</para>

      <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up</userinput>
&prompt.root; <userinput>tcpdump -i bridge0</userinput></screen>
    </sect2>

    <sect2>
      <title><acronym>SNMP</acronym> Monitoring</title>

      <para>The bridge interface and <acronym>STP</acronym>
	parameters can be monitored via &man.bsnmpd.1; which is
	included in the &os; base system.  The exported bridge
	<acronym>MIB</acronym>s conform to <acronym>IETF</acronym>
	standards so any <acronym>SNMP</acronym> client or monitoring
	package can be used to retrieve the data.</para>

      <para>To enable monitoring on the bridge, uncomment this line in
	<filename>/etc/snmpd.config</filename> by removing the
	beginning <literal>#</literal> symbol:</para>

      <programlisting>begemotSnmpdModulePath."bridge" = "/usr/lib/snmp_bridge.so"</programlisting>

      <para>Other configuration settings, such as community names and
	access lists, may need to be modified in this file.  See
	&man.bsnmpd.1; and &man.snmp.bridge.3; for more information.
	Once these edits are saved, add this line to
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>bsnmpd_enable="YES"</programlisting>

      <para>Then, start  &man.bsnmpd.1;:</para>

      <screen>&prompt.root; <userinput>service bsnmpd start</userinput></screen>

      <para>The following examples use the
	<application>Net-SNMP</application> software
	(<package>net-mgmt/net-snmp</package>) to query a bridge
	from a client system.  The
	<package>net-mgmt/bsnmptools</package> port can also be used.
	From the <acronym>SNMP</acronym> client which is running
	<application>Net-SNMP</application>, add the following lines
	to <filename>$HOME/.snmp/snmp.conf</filename> in order to
	import the bridge <acronym>MIB</acronym> definitions:</para>

      <programlisting>mibdirs +/usr/share/snmp/mibs
mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB</programlisting>

      <para>To monitor a single bridge using the IETF BRIDGE-MIB
	(RFC4188):</para>

      <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge</userinput>
BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44
BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports
BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds
BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2
BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50
...
BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5)
BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1)
BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000
BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0
BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80
BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1
RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)</screen>

      <para>The <literal>dot1dStpTopChanges.0</literal> value is two,
	indicating that the <acronym>STP</acronym> bridge topology has
	changed twice.  A topology change means that one or more links
	in the network have changed or failed and a new tree has been
	calculated.  The
	<literal>dot1dStpTimeSinceTopologyChange.0</literal> value
	will show when this happened.</para>

      <para>To monitor multiple bridge interfaces, the private
	BEGEMOT-BRIDGE-MIB can be used:</para>

      <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com</userinput>
enterprises.fokus.begemot.begemotBridge
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1
BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1
...
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1
BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1
BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31
BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9</screen>

      <para>To change the bridge interface being monitored via the
	<literal>mib-2.dot1dBridge</literal> subtree:</para>

      <screen>&prompt.user; <userinput>snmpset -v 2c -c private bridge1.example.com</userinput>
BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
    </sect2>
  </sect1>

  <sect1 xml:id="network-aggregation">
    <info>
      <title>Link Aggregation and Failover</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Andrew</firstname>
	    <surname>Thompson</surname>
	  </personname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary>lagg</primary>
    </indexterm>
    <indexterm>
      <primary>failover</primary>
    </indexterm>
    <indexterm>
      <primary><acronym>FEC</acronym></primary>
    </indexterm>
    <indexterm>
      <primary><acronym>LACP</acronym></primary>
    </indexterm>
    <indexterm>
      <primary>loadbalance</primary>
    </indexterm>
    <indexterm>
      <primary>roundrobin</primary>
    </indexterm>

    <para>&os; provides the &man.lagg.4; interface which can be used
      to aggregate multiple network interfaces into one virtual
      interface in order to provide failover and link aggregation.
      Failover allows traffic to continue to flow as long as at least
      one aggregated network interface has an established link.  Link
      aggregation works best on switches which support
      <acronym>LACP</acronym>, as this protocol distributes traffic
      bi-directionally while responding to the failure of individual
      links.</para>

    <para>The aggregation protocols supported by the lagg interface
      determine which ports are used for outgoing traffic and whether
      or not a specific port accepts incoming traffic.  The following
      protocols are supported by &man.lagg.4;:</para>

    <variablelist>
      <varlistentry>
	<term>failover</term>
	<listitem>
	  <para>This mode sends and receives traffic only through
	    the master port.  If the master port becomes
	    unavailable, the next active port is used.  The first
	    interface added to the virtual interface is the master
	    port and all subsequently added interfaces are used as
	    failover devices.  If failover to a non-master port
	    occurs, the original port becomes master once it
	    becomes available again.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>fec / loadbalance</term>
	<listitem>
	  <para>&cisco; Fast &etherchannel; (<acronym>FEC</acronym>)
	    is found on older &cisco; switches.  It provides a
	    static setup and does not negotiate aggregation with the
	    peer or exchange frames to monitor the link.  If the
	    switch supports <acronym>LACP</acronym>, that should be
	    used instead.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><acronym>lacp</acronym></term>
	<listitem>
	  <para>The &ieee; 802.3ad Link Aggregation Control Protocol
	    (<acronym>LACP</acronym>) negotiates a set of
	    aggregable links with the peer into one or more Link
	    Aggregated Groups (<acronym>LAG</acronym>s).  Each
	    <acronym>LAG</acronym> is composed of ports of the same
	    speed, set to full-duplex operation, and traffic is
	    balanced across the ports in the
	    <acronym>LAG</acronym> with the greatest total speed.
	    Typically, there is only one <acronym>LAG</acronym>
	    which contains all the ports.  In the event of changes
	    in physical connectivity,
	    <acronym>LACP</acronym> will quickly converge to a new
	    configuration.</para>

	  <para><acronym>LACP</acronym> balances outgoing traffic
	    across the active ports based on hashed protocol header
	    information and accepts incoming traffic from any active
	    port.  The hash includes the Ethernet source and
	    destination address and, if available, the
	    <acronym>VLAN</acronym> tag, and the
	    <acronym>IPv4</acronym> or <acronym>IPv6</acronym>
	    source and destination address.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>roundrobin</term>
	<listitem>
	  <para>This mode distributes outgoing traffic using a
	    round-robin scheduler through all active ports and
	    accepts incoming traffic from any active port.  Since
	    this mode violates Ethernet frame ordering, it should be
	    used with caution.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <sect2>
      <title>Configuration Examples</title>

      <para>This section demonstrates how to configure a &cisco;
	switch and a &os; system for <acronym>LACP</acronym> load
	balancing.  It then shows how to configure two Ethernet
	interfaces in failover mode as well as how to configure
	failover mode between an Ethernet and a wireless
	interface.</para>

      <example xml:id="networking-lacp-aggregation-cisco">
	<title><acronym>LACP</acronym> Aggregation with a &cisco;
	  Switch</title>

	<para>This example connects two &man.fxp.4; Ethernet
	  interfaces on a &os; machine to the first two Ethernet ports
	  on a &cisco; switch as a single load balanced and fault
	  tolerant link.  More interfaces can be added to increase
	  throughput and fault tolerance.  Replace the names of the
	  &cisco; ports, Ethernet devices, channel group number, and
	  <acronym>IP</acronym> address shown in the example to match
	  the local configuration.</para>

	<para>Frame ordering is mandatory on Ethernet links and any
	  traffic between two stations always flows over the same
	  physical link, limiting the maximum speed to that of one
	  interface.  The transmit algorithm attempts to use as much
	  information as it can to distinguish different traffic flows
	  and balance the flows across the available
	  interfaces.</para>

	<para>On the &cisco; switch, add the
	  <replaceable>FastEthernet0/1</replaceable> and
	  <replaceable>FastEthernet0/2</replaceable> interfaces to
	  channel group <replaceable>1</replaceable>:</para>

	<screen><userinput>interface <replaceable>FastEthernet0/1</replaceable>
 channel-group <replaceable>1</replaceable> mode active
 channel-protocol lacp</userinput>
!
<userinput>interface <replaceable>FastEthernet0/2</replaceable>
 channel-group <replaceable>1</replaceable> mode active
 channel-protocol lacp</userinput></screen>

	<para>On the &os; system, create the &man.lagg.4; interface
	  using the physical interfaces
	  <replaceable>fxp0</replaceable> and
	  <replaceable>fxp1</replaceable> and bring the interfaces up
	  with an <acronym>IP</acronym> address of
	  <replaceable>10.0.0.3/24</replaceable>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create </userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable></userinput></screen>

	<para>Next, verify the status of the virtual interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
        options=8&lt;VLAN_MTU&gt;
        ether 00:05:5d:71:8d:b8
        media: Ethernet autoselect
        status: active
        laggproto lacp
        laggport: fxp1 flags=1c&lt;ACTIVE,COLLECTING,DISTRIBUTING&gt;
        laggport: fxp0 flags=1c&lt;ACTIVE,COLLECTING,DISTRIBUTING&gt;</screen>

	<para>Ports
	  marked as <literal>ACTIVE</literal> are part of the
	  <acronym>LAG</acronym> that has been negotiated with the
	  remote switch.  Traffic will be transmitted and received
	  through these active ports.  Add <option>-v</option> to the
	  above command to view the <acronym>LAG</acronym>
	  identifiers.</para>

	<para>To see the port status on the &cisco; switch:</para>

	<screen>switch# <userinput>show lacp neighbor</userinput>
Flags:  S - Device is requesting Slow LACPDUs
        F - Device is requesting Fast LACPDUs
        A - Device is in Active mode       P - Device is in Passive mode

Channel group 1 neighbors

Partner's information:

                  LACP port                        Oper    Port     Port
Port      Flags   Priority  Dev ID         Age     Key     Number   State
Fa0/1     SA      32768     0005.5d71.8db8  29s    0x146   0x3      0x3D
Fa0/2     SA      32768     0005.5d71.8db8  29s    0x146   0x4      0x3D</screen>

	<para>For more detail, type <userinput>show lacp neighbor
	  detail</userinput>.</para>

	<para>To retain this configuration across reboots, add the
	  following entries to
	  <filename>/etc/rc.conf</filename> on the &os; system:</para>

	<programlisting>ifconfig_<replaceable>fxp0</replaceable>="up"
ifconfig_<replaceable>fxp1</replaceable>="up"
cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting>
      </example>

      <example xml:id="networking-lagg-failover">
	<title>Failover Mode</title>

	<para>Failover mode can be used to switch over to a secondary
	  interface if the link is lost on the master interface.  To
	  configure failover, make sure that the underlying physical
	  interfaces are up, then create the &man.lagg.4; interface.
	  In this example, <replaceable>fxp0</replaceable> is the
	  master interface, <replaceable>fxp1</replaceable> is the
	  secondary interface, and the virtual interface is assigned
	  an <acronym>IP</acronym> address of
	  <replaceable>10.0.0.15/24</replaceable>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen>

	<para>The virtual interface should look something like
	  this:</para>

	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
        options=8&lt;VLAN_MTU&gt;
        ether 00:05:5d:71:8d:b8
        inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255
        media: Ethernet autoselect
        status: active
        laggproto failover
        laggport: fxp1 flags=0&lt;&gt;
        laggport: fxp0 flags=5&lt;MASTER,ACTIVE&gt;</screen>

	<para>Traffic will be transmitted and received on
	  <replaceable>fxp0</replaceable>.  If the link is lost on
	  <replaceable>fxp0</replaceable>,
	  <replaceable>fxp1</replaceable> will become the active link.
	  If the link is restored on the master interface, it will
	  once again become the active link.</para>

	<para>To retain this configuration across reboots, add the
	  following entries to
	  <filename>/etc/rc.conf</filename>:</para>

	<programlisting>ifconfig_<replaceable>fxp0</replaceable>="up"
ifconfig_<replaceable>fxp1</replaceable>="up"
cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>"</programlisting>
      </example>

      <example xml:id="networking-lagg-wired-and-wireless">
	<title>Failover Mode Between Ethernet and Wireless
	  Interfaces</title>

	<para>For laptop users, it is usually desirable to configure
	  the wireless device as a secondary which is only used when
	  the Ethernet connection is not available.  With
	  &man.lagg.4;, it is possible to configure a failover which
	  prefers the Ethernet connection for both performance and
	  security reasons, while maintaining the ability to transfer
	  data over the wireless connection.</para>

	<para>This is achieved by overriding the physical wireless
	  interface's <acronym>MAC</acronym> address with that of the
	  Ethernet interface.</para>

	<para>In this example, the Ethernet interface,
	  <replaceable>bge0</replaceable>, is the master and the
	  wireless interface, <replaceable>wlan0</replaceable>, is
	  the failover.  The <replaceable>wlan0</replaceable> device
	  was created from <replaceable>iwn0</replaceable> wireless
	  interface, which will be configured with the
	  <acronym>MAC</acronym> address of the Ethernet interface.
	  First, determine the <acronym>MAC</acronym> address of the
	  Ethernet interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput>
bge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
	options=19b&lt;RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4&gt;
	ether 00:21:70:da:ae:37
	inet6 fe80::221:70ff:feda:ae37%bge0 prefixlen 64 scopeid 0x2
	nd6 options=29&lt;PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL&gt;
	media: Ethernet autoselect (1000baseT &lt;full-duplex&gt;)
	status: active</screen>

	<para>Replace <replaceable>bge0</replaceable> to match the
	  system's Ethernet interface name.  The
	  <literal>ether</literal> line will contain the
	  <acronym>MAC</acronym> address of the specified interface.
	  Now, change the <acronym>MAC</acronym> address of the
	  underlying wireless interface:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen>

	<para>Bring the wireless interface up, but do not set an
	  <acronym>IP</acronym> address:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen>

	<para>Make sure the <replaceable>bge0</replaceable> interface
	  is up, then create the &man.lagg.4; interface with
	  <replaceable>bge0</replaceable> as master with failover to
	  <replaceable>wlan0</replaceable>:</para>

	<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen>

	<para>The virtual interface should look something like
	  this:</para>

	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
        options=8&lt;VLAN_MTU&gt;
        ether 00:21:70:da:ae:37
        media: Ethernet autoselect
        status: active
        laggproto failover
        laggport: wlan0 flags=0&lt;&gt;
        laggport: bge0 flags=5&lt;MASTER,ACTIVE&gt;</screen>

	<para>Then, start the <acronym>DHCP</acronym> client to
	  obtain an <acronym>IP</acronym> address:</para>

	<screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen>

	<para>To retain this configuration across reboots, add the
	  following entries to
	  <filename>/etc/rc.conf</filename>:</para>

	<programlisting>ifconfig_bge0="up"
wlans_<replaceable>iwn0</replaceable>="wlan0"
ifconfig_wlan0="WPA"
create_args_wlan0="<replaceable>wlanaddr 00:21:70:da:ae:37</replaceable>"
cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="up laggproto failover laggport bge0 laggport wlan0 DHCP"</programlisting>
      </example>
    </sect2>
  </sect1>

  <sect1 xml:id="network-diskless">
    <info>
      <title>Diskless Operation with <acronym>PXE</acronym></title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Jean-Fran&ccedil;ois</firstname>
	    <surname>Dock&egrave;s</surname>
	  </personname>
	  <contrib>Updated by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <personname>
	    <firstname>Alex</firstname>
	    <surname>Dupre</surname>
	  </personname>
	  <contrib>Reorganized and enhanced by </contrib>
	</author>
      </authorgroup>
    </info>

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

    <para>The &intel; Preboot eXecution Environment
      (<acronym>PXE</acronym>) allows an operating system to boot over
      the network.  For example, a &os; system can boot over the
      network and operate without a local disk, using file systems
      mounted from an <acronym>NFS</acronym> server.
      <acronym>PXE</acronym> support is usually available in the
      <acronym>BIOS</acronym>.  To use <acronym>PXE</acronym> when the
      machine starts, select the <literal>Boot from network</literal>
      option in the <acronym>BIOS</acronym> setup or type a function
      key during system initialization.</para>

    <para>In order to provide the files needed for an operating system
      to boot over the network, a <acronym>PXE</acronym> setup also
      requires properly configured <acronym>DHCP</acronym>,
      <acronym>TFTP</acronym>, and <acronym>NFS</acronym> servers,
      where:</para>

    <itemizedlist>
      <listitem>
	<para>Initial parameters, such as an <acronym>IP</acronym>
	  address, executable boot filename and location, server name,
	  and root path are obtained from the
	  <acronym>DHCP</acronym> server.</para>
      </listitem>

      <listitem>
	<para>The operating system loader file is booted using
	  <acronym>TFTP</acronym>.</para>
      </listitem>

      <listitem>
	<para>The file systems are loaded using
	  <acronym>NFS</acronym>.</para>
      </listitem>
    </itemizedlist>

    <para>When a computer <acronym>PXE</acronym> boots, it receives
      information over <acronym>DHCP</acronym> about where to obtain
      the initial boot loader file.  After the host computer receives
      this information, it downloads the boot loader via
      <acronym>TFTP</acronym> and then executes the boot loader.  In
      &os;, the boot loader file is
      <filename>/boot/pxeboot</filename>.  After
      <filename>/boot/pxeboot</filename> executes, the &os; kernel is
      loaded and the rest of the &os; bootup sequence proceeds, as
      described in <xref linkend="boot"/>.</para>

    <para>This section describes how to configure these services on a
      &os; system so that other systems can <acronym>PXE</acronym>
      boot into &os;.  Refer to &man.diskless.8; for more
      information.</para>

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

    <sect2 xml:id="network-pxe-nfs">
      <info>
	<title>Setting Up the <acronym>PXE</acronym>
	  Environment</title>

	<authorgroup>
	  <author>
	    <personname>
	      <firstname>Craig</firstname>
	      <surname>Rodrigues</surname>
	    </personname>
	    <affiliation>
	      <address>rodrigc@FreeBSD.org</address>
	    </affiliation>
	    <contrib>Written by </contrib>
	  </author>
	</authorgroup>
      </info>

      <para>The steps shown in this section configure the built-in
	<acronym>NFS</acronym> and <acronym>TFTP</acronym> servers.
	The next section demonstrates how to install and configure the
	<acronym>DHCP</acronym> server.  In this example, the
	directory which will contain the files used by
	<acronym>PXE</acronym> users is
	<filename>/b/tftpboot/FreeBSD/install</filename>.  It is
	important that this directory exists and that the same
	directory name is set in both
	<filename>/etc/inetd.conf</filename> and
	<filename>/usr/local/etc/dhcpd.conf</filename>.</para>

      <procedure>
	<step>
	  <para>Create the root directory which will contain a &os;
	    installation to be <acronym>NFS</acronym> mounted:</para>

	  <screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput>
&prompt.root; <userinput>mkdir -p ${NFSROOTDIR}</userinput></screen>
	</step>

	<step>
	  <para>Enable the <acronym>NFS</acronym> server by adding
	    this line to <filename>/etc/rc.conf</filename>:</para>

	  <programlisting>nfs_server_enable="YES"</programlisting>
	</step>

	<step>
	  <para>Export the diskless root directory via
	    <acronym>NFS</acronym> by adding the following to
	    <filename>/etc/exports</filename>:</para>

	  <programlisting>/b -ro -alldirs</programlisting>
	</step>

	<step>
	  <para>Start the <acronym>NFS</acronym> server:</para>

	  <screen>&prompt.root; <userinput>service nfsd start</userinput></screen>
	</step>

	<step>
	  <para>Enable &man.inetd.8; by adding the following line to
	    <filename>/etc/rc.conf</filename>:</para>

	  <programlisting>inetd_enable="YES"</programlisting>
	</step>

	<step>
	  <para>Uncomment the following line in
	    <filename>/etc/inetd.conf</filename> by making sure it
	    does not start with a <literal>#</literal> symbol:</para>

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

	  <note>
	    <para>Some <acronym>PXE</acronym> versions require the
	      <acronym>TCP</acronym> version of
	      <acronym>TFTP</acronym>.  In this case, uncomment the
	      second <literal>tftp</literal> line which contains
	      <literal>stream tcp</literal>.</para>
	  </note>
	</step>

	<step>
	  <para>Start &man.inetd.8;:</para>

	  <screen>&prompt.root; <userinput>service inetd start</userinput></screen>
	</step>

	<step>
	  <para>Rebuild the &os; kernel and userland (refer to <xref
	      linkend="makeworld"/> for more detailed
	    instructions):</para>

	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildworld</userinput>
&prompt.root; <userinput>make buildkernel</userinput></screen>
	</step>

	<step>
	  <para>Install &os; into the directory mounted over
	    <acronym>NFS</acronym>:</para>

	  <screen>&prompt.root; <userinput>make installworld DESTDIR=${NFSROOTDIR}</userinput>
&prompt.root; <userinput>make installkernel DESTDIR=${NFSROOTDIR}</userinput>
&prompt.root; <userinput>make distribution DESTDIR=${NFSROOTDIR}</userinput></screen>
	</step>

	<step>
	  <para>Test that the <acronym>TFTP</acronym> server works and
	    can download the boot loader which will be obtained via
	    <acronym>PXE</acronym>:</para>

	  <screen>&prompt.root; <userinput>tftp localhost</userinput>
tftp&gt; <userinput>get FreeBSD/install/boot/pxeboot</userinput>
Received 264951 bytes in 0.1 seconds</screen>
	</step>

	<step>
	  <para>Edit <filename>${NFSROOTDIR}/etc/fstab</filename> and
	    create an entry to mount the root file system over
	    <acronym>NFS</acronym>:</para>

	  <programlisting># Device                                         Mountpoint    FSType   Options  Dump Pass
<replaceable>myhost.example.com</replaceable>:/b/tftpboot/FreeBSD/install       /         nfs      ro        0    0</programlisting>

	  <para>Replace <replaceable>myhost.example.com</replaceable>
	    with the hostname or <acronym>IP</acronym> address of the
	    <acronym>NFS</acronym> server.  In this example, the root
	    file system is mounted read-only in order to prevent
	    <acronym>NFS</acronym> clients from potentially deleting
	    the contents of the root file system.</para>
	</step>

	<step>
	  <para>Set the root password in the <acronym>PXE</acronym>
	    environment for client machines which are
	    <acronym>PXE</acronym> booting :</para>

	  <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
&prompt.root; <userinput>passwd</userinput></screen>
	</step>

	<step>
	  <para>If needed, enable &man.ssh.1; root logins for client
	    machines which are <acronym>PXE</acronym> booting by
	    editing
	    <filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename> and
	    enabling <literal>PermitRootLogin</literal>.  This option
	    is documented in &man.sshd.config.5;.</para>
	</step>

	<step>
	  <para>Perform any other needed customizations of the
	    <acronym>PXE</acronym> environment in
	    <filename>${NFSROOTDIR}</filename>.  These customizations
	    could include things like installing packages or editing
	    the password file with &man.vipw.8;.</para>
	</step>
      </procedure>

      <para>When booting from an <acronym>NFS</acronym> root volume,
	<filename>/etc/rc</filename> detects the
	<acronym>NFS</acronym> boot and runs
	<filename>/etc/rc.initdiskless</filename>.  In this case,
	<filename>/etc</filename> and <filename>/var</filename> need
	to be memory backed file systems so that these directories are
	writable but the <acronym>NFS</acronym> root directory is
	read-only:</para>

      <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
&prompt.root; <userinput>mkdir -p conf/base</userinput>
&prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput>
&prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen>

      <para>When the system boots, memory file systems for
	<filename>/etc</filename> and <filename>/var</filename> will
	be created and mounted and the contents of the
	<filename>cpio.gz</filename> files will be copied into
	them.</para>
    </sect2>

    <sect2 xml:id="network-pxe-setting-up-dhcp">
      <title>Configuring the <acronym>DHCP</acronym> Server</title>

      <indexterm>
	<primary>DHCP</primary>
	<secondary>diskless operation</secondary>
      </indexterm>

      <para>The <acronym>DHCP</acronym> server does not need to be the
	same machine as the <acronym>TFTP</acronym> and
	<acronym>NFS</acronym> server, but it needs to be accessible
	in the network.</para>

      <para><acronym>DHCP</acronym> is not part of the &os; base
	system but can be installed using the
	<package>net/isc-dhcp43-server</package> port or
	package.</para>

      <para>Once installed, edit the configuration file,
	<filename>/usr/local/etc/dhcpd.conf</filename>.  Configure
	the <literal>next-server</literal>,
	<literal>filename</literal>, and
	<literal>root-path</literal> settings as seen in this
	example:</para>

      <programlisting>subnet 192.168.0.0 netmask 255.255.255.0 {
   range 192.168.0.2 192.168.0.3 ;
   option subnet-mask 255.255.255.0 ;
   option routers 192.168.0.1 ;
   option broadcast-address 192.168.0.255 ;
   option domain-name-servers 192.168.35.35, 192.168.35.36 ;
   option domain-name "example.com";

   # IP address of TFTP server
   next-server <replaceable>192.168.0.1</replaceable> ;

   # path of boot loader obtained via tftp
     filename "<replaceable>FreeBSD/install/boot/pxeboot</replaceable>" ;

   # pxeboot boot loader will try to NFS mount this directory for root FS
   option root-path "<replaceable>192.168.0.1:/b/tftpboot/FreeBSD/install/</replaceable>" ;

}</programlisting>

<!--
 This option still needed?
 host corbieres {
      <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>corbieres</replaceable></literal>
	inside the <literal>host</literal> declarations.</para>
-->

      <para>The <literal>next-server</literal> directive is used to
	specify the <acronym>IP</acronym> address of the
	<acronym>TFTP</acronym> server.</para>

      <para>The <literal>filename</literal> directive defines the path
	to <filename>/boot/pxeboot</filename>.  A relative filename is
	used, meaning that <filename>/b/tftpboot</filename> is not
	included in the path.</para>

      <para>The <literal>root-path</literal> option defines the path
	to the <acronym>NFS</acronym> root file system.</para>

      <para>Once the edits are saved, enable <acronym>DHCP</acronym>
	at boot time by adding the following line to
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>dhcpd_enable="YES"</programlisting>

      <para>Then start the <acronym>DHCP</acronym> service:</para>

      <screen>&prompt.root; <userinput>service isc-dhcpd start</userinput></screen>
    </sect2>
<!--
Are these sections still needed?
    <sect2>
      <title>Preparing the Root File System</title>

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

      <para>When using <acronym>PXE</acronym>, building a custom
	kernel with the following options is not strictly necessary.
	These options 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
	is that the host name will be set.  Otherwise, set the
	host name in a client-specific
	<filename>/etc/rc.conf</filename>.</para>

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

      <para>The custom kernel can also include
	<literal>BOOTP_NFSV3</literal>,
	<literal>BOOT_COMPAT</literal> and
	<literal>BOOTP_WIRED_TO</literal>.  Refer to
	<filename>NOTES</filename> for descriptions of these
	options.</para>

      <para>These option names are historical and slightly
	misleading as they actually enable indifferent use of
	<acronym>DHCP</acronym> and <acronym>BOOTP</acronym>
	inside the kernel.</para>

      <para>Build the custom kernel, using the instructions in
	<xref linkend="kernelconfig"/>, and copy it to the place
	specified in
	<filename>/usr/local/etc/dhcpd.conf</filename>.</para>

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

      <para>Create a root file system for the diskless
	workstations in the location listed as
	<literal>root-path</literal> in
	<filename>/usr/local/etc/dhcpd.conf</filename>.</para>

      <para>Using <command>make world</command> to populate root is
	quick and will install a complete virgin system, not just
	the root file system, into <envar>DESTDIR</envar>.  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
make installworld &amp;&amp; make installkernel
cd /usr/src/etc; make distribution</programlisting>

      <para>Once done, customize
	<filename>/etc/rc.conf</filename> and
	<filename>/etc/fstab</filename> placed into
	<envar>DESTDIR</envar> according to the system's
	requirements.</para>
    </sect2>

    <sect2>
      <title>Configuring Swap</title>

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

      <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:</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 the swap file, add the following line to
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting>
    </sect2>

    <sect2>
      <title>Miscellaneous Issues</title>

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

      <para>If the diskless workstation is configured to run
	<application>&xorg;</application> and is running with a
	read-only <filename>/usr</filename>, adjust the
	<application>XDM</application> configuration file as it puts
	the error log on <filename>/usr</filename> by
	default.</para>

      <para>When the server for the root file system is not
	running &os;, create the root file system on a &os;
	machine, then copy it to its destination, using
	&man.tar.1; or &man.cpio.1;.</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-&os; server,
	mount this directory onto a &os; machine, and use
	&man.devfs.5; to allocate device nodes transparently for
	the user.</para>
    </sect2>
-->

    <sect2>
      <title>Debugging <acronym>PXE</acronym> Problems</title>

      <para>Once all of the services are configured and started,
	<acronym>PXE</acronym> clients should be able to
	automatically load &os; over the network.  If a particular
	client is unable to connect, when that client machine boots
	up, enter the <acronym>BIOS</acronym> configuration menu and
	confirm that it is set to boot from the network.</para>

      <para>This section describes some troubleshooting tips for
	isolating the source of the configuration problem should no
	clients be able to <acronym>PXE</acronym> boot.</para>

      <procedure>
	<step>
	  <para>Use the <package>net/wireshark</package> package or
	    port to debug the network traffic involved during the
	    <acronym>PXE</acronym> booting process, which is
	    illustrated in the diagram below.</para>

	  <figure>
	    <title><acronym>PXE</acronym> Booting Process with
	      <acronym>NFS</acronym> Root Mount</title>

	    <mediaobject>
	      <imageobjectco>
		<areaspec units="calspair">
		  <area
		    xml:id="co-pxenfs1" coords="2873,8133 3313,7266"/>
		  <area
		    xml:id="co-pxenfs2" coords="3519,6333 3885,5500"/>
		  <area
		    xml:id="co-pxenfs3" coords="4780,5866 5102,5200"/>
		  <area
		    xml:id="co-pxenfs4" coords="4794,4333 5102,3600"/>
		  <area
		    xml:id="co-pxenfs5" coords="3108,2666 3519,1800"/>
		</areaspec>
		<imageobject>
		  <imagedata fileref="advanced-networking/pxe-nfs"/>
		</imageobject>
		<calloutlist>
		  <callout arearefs="co-pxenfs1">
		    <para>Client broadcasts a
		      <literal>DHCPDISCOVER</literal> message.</para>
		  </callout>
		  <callout arearefs="co-pxenfs2">
		    <para>The <acronym>DHCP</acronym> server responds
		      with the <acronym>IP</acronym> address,
		      <literal>next-server</literal>,
		      <literal>filename</literal>, and
		      <literal>root-path</literal> values.</para>
		  </callout>
		  <callout arearefs="co-pxenfs3">
		    <para>The client sends a <acronym>TFTP</acronym>
		      request to <literal>next-server</literal>,
		      asking to retrieve
		      <literal>filename</literal>.</para>
		  </callout>
		  <callout arearefs="co-pxenfs4">
		    <para>The <acronym>TFTP</acronym> server responds
		      and sends <literal>filename</literal> to
		      client.</para>
		  </callout>
		  <callout arearefs="co-pxenfs5">
		    <para>The client executes
		      <literal>filename</literal>, which is
		      &man.pxeboot.8;, which then loads the kernel.
		      When the kernel executes, the root file system
		      specified by <literal>root-path</literal> is
		      mounted over <acronym>NFS</acronym>.</para>
		  </callout>
		</calloutlist>
	      </imageobjectco>
	    </mediaobject>
	  </figure>
	</step>

	<step>
	  <para>On the
	    <acronym>TFTP</acronym> server, read
	    <filename>/var/log/xferlog</filename> to ensure that
	    <filename>pxeboot</filename> is being retrieved from
	    the correct location.  To test this example
	    configuration:</para>

	  <screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput>
tftp&gt; <userinput>get FreeBSD/install/boot/pxeboot</userinput>
Received 264951 bytes in 0.1 seconds</screen>

	  <para>The <literal>BUGS</literal> sections in &man.tftpd.8;
	    and &man.tftp.1; document some limitations with
	    <acronym>TFTP</acronym>.</para>
	</step>

	<step>
	  <para>Make sure that the root file system can be mounted
	    via <acronym>NFS</acronym>.  To test this example
	    configuration:</para>

	  <screen>&prompt.root; <userinput>mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt</userinput></screen>
	</step>
      </procedure>
    </sect2>
  </sect1>

  <sect1 xml:id="network-ipv6">
    <info>
      <title><acronym>IPv6</acronym></title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Aaron</firstname>
	    <surname>Kaplan</surname>
	  </personname>
	  <contrib>Originally Written by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <personname>
	    <firstname>Tom</firstname>
	    <surname>Rhodes</surname>
	  </personname>
	  <contrib>Restructured and Added by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <personname>
	    <firstname>Brad</firstname>
	    <surname>Davis</surname>
	  </personname>
	  <contrib>Extended by </contrib>
	</author>
      </authorgroup>
    </info>

    <para><acronym>IPv6</acronym> is the new version of the well known
      <acronym>IP</acronym> protocol, also known as
      <acronym>IPv4</acronym>.  <acronym>IPv6</acronym> provides
      several advantages over <acronym>IPv4</acronym> as well as many
      new features:</para>

    <itemizedlist>
      <listitem>
	<para>Its 128-bit address space allows for
	  340,282,366,920,938,463,463,374,607,431,768,211,456
	  addresses.  This addresses the <acronym>IPv4</acronym>
	  address shortage and eventual <acronym>IPv4</acronym>
	  address exhaustion.</para>
      </listitem>

      <listitem>
	<para>Routers only store network aggregation addresses in
	  their routing tables, thus reducing the average space of a
	  routing table to 8192 entries.  This addresses the
	  scalability issues associated with <acronym>IPv4</acronym>,
	  which required every allocated block of
	  <acronym>IPv4</acronym> addresses to be exchanged between
	  Internet routers, causing their routing tables to become too
	  large to allow efficient routing.</para>
      </listitem>
    </itemizedlist>

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

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

      <listitem>
	<para>Built-in <acronym>IPsec</acronym> (<acronym>IP</acronym>
	  security).</para>
      </listitem>

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

      <listitem>
	<para>Support for mobile <acronym>IP</acronym>.</para>
      </listitem>

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

    <para>&os; includes the <link
	xlink:href="http://www.kame.net/">http://www.kame.net/</link>
      <acronym>IPv6</acronym> reference implementation and comes
      with everything needed to use <acronym>IPv6</acronym>.  This
      section focuses on getting <acronym>IPv6</acronym> configured
      and running.</para>

    <sect2>
      <title>Background on <acronym>IPv6</acronym> Addresses</title>

      <para>There are three different types of <acronym>IPv6</acronym>
	addresses:</para>

      <variablelist>
	<varlistentry>
	  <term>Unicast</term>
	  <listitem>
	    <para>A packet sent to a unicast address arrives at the
	      interface belonging to the address.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Anycast</term>
	  <listitem>
	    <para>These 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 router interface.  Anycast
	      addresses are only used by routers.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Multicast</term>
	  <listitem>
	    <para>These addresses identify a group of interfaces.  A
	      packet destined for a multicast address will arrive at
	      all interfaces belonging to the multicast group.  The
	      <acronym>IPv4</acronym> broadcast address, usually
	      <systemitem
		class="ipaddress">xxx.xxx.xxx.255</systemitem>, is
	      expressed by multicast addresses in
	      <acronym>IPv6</acronym>.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>When reading an <acronym>IPv6</acronym> address, the
	canonical form is represented as
	<systemitem>x:x:x:x:x:x:x:x</systemitem>, where each
	<literal>x</literal> represents a 16 bit hex value.  An
	example is
	<systemitem>FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</systemitem>.</para>

      <para>Often, an address will have long substrings of all zeros.
	A <literal>::</literal> (double colon) can be used to replace
	one substring per address.  Also, up to three leading
	<literal>0</literal>s per hex value can be omitted.  For
	example, <systemitem>fe80::1</systemitem> corresponds to the
	canonical form
	<systemitem>fe80:0000:0000:0000:0000:0000:0000:0001</systemitem>.</para>

      <para>A third form is to write the last 32 bits using the well
	known <acronym>IPv4</acronym> notation.  For example,
	<systemitem>2002::10.0.0.1</systemitem> corresponds to the
	hexadecimal canonical representation
	<systemitem>2002:0000:0000:0000:0000:0000:0a00:0001</systemitem>,
	which in turn is equivalent to
	<systemitem>2002::a00:1</systemitem>.</para>

      <para>To view a &os; system's <acronym>IPv6 </acronym> address,
	use &man.ifconfig.8;:</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>In this example, the <filename>rl0</filename> interface is
	using <systemitem>fe80::200:21ff:fe03:8e1%rl0</systemitem>, an
	auto-configured link-local address which was automatically
	generated from the <acronym>MAC</acronym> address.</para>

      <para>Some <acronym>IPv6</acronym> addresses are reserved.  A
	summary of these reserved addresses is seen in <xref
	  linkend="reservedip6"/>:</para>

      <table xml:id="reservedip6" frame="none">
	<title>Reserved <acronym>IPv6</acronym> Addresses</title>

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

	  <tbody>
	    <row>
	      <entry><systemitem>::</systemitem></entry>
	      <entry>128 bits</entry>
	      <entry>unspecified</entry>
	      <entry>Equivalent to <systemitem
		  class="ipaddress">0.0.0.0</systemitem> in
		<acronym>IPv4</acronym>.</entry>
	    </row>

	    <row>
	      <entry><systemitem>::1</systemitem></entry>
	      <entry>128 bits</entry>
	      <entry>loopback address</entry>
	      <entry>Equivalent to <systemitem
		  class="ipaddress">127.0.0.1</systemitem> in
		<acronym>IPv4</acronym>.</entry>
	    </row>

	    <row>
	      <entry><systemitem>::00:xx:xx:xx:xx</systemitem></entry>
	      <entry>96 bits</entry>
	      <entry>embedded <acronym>IPv4</acronym></entry>
	      <entry>The lower 32 bits are the compatible
		<acronym>IPv4</acronym> address.</entry>
	    </row>

	    <row>
	      <entry><systemitem>::ff:xx:xx:xx:xx</systemitem></entry>
	      <entry>96 bits</entry>
	      <entry><acronym>IPv4</acronym> mapped
		<acronym>IPv6</acronym> address</entry>
	      <entry>The lower 32 bits are the <acronym>IPv4</acronym>
		address for hosts which do not support
		<acronym>IPv6</acronym>.</entry>
	    </row>

	    <row>
	      <entry><systemitem>fe80::/10</systemitem></entry>
	      <entry>10 bits</entry>
	      <entry>link-local</entry>
	      <entry>Equivalent to 169.254.0.0/16 in
		<acronym>IPv4</acronym>.</entry>
	    </row>

	    <row>
	      <entry><systemitem>fc00::/7</systemitem></entry>
	      <entry>7 bits</entry>
	      <entry>unique-local</entry>
	      <entry>Unique local addresses are intended for local
		communication and are only routable within a set of
		cooperating sites.</entry>
	    </row>

	    <row>
	      <entry><systemitem>ff00::</systemitem></entry>
	      <entry>8 bits</entry>
	      <entry>multicast</entry>
	      <entry>&nbsp;</entry>
	    </row>

	    <row>
	      <entry><systemitem>2000::-3fff:: </systemitem></entry>
	      <entry>3 bits</entry>
	      <entry>global unicast</entry>
	      <entry>All global unicast addresses are assigned from
		this pool.  The first 3 bits are
		<literal>001</literal>.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>

      <para>For further information on the structure of
	<acronym>IPv6</acronym> addresses, refer to <link
	  xlink:href="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</link>.</para>
    </sect2>

    <sect2>
      <title>Configuring <acronym>IPv6</acronym></title>

      <para>To configure a &os; system as an <acronym>IPv6</acronym>
	client, add these two lines to
	<filename>rc.conf</filename>:</para>

      <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 accept_rtadv"
rtsold_enable="YES"</programlisting>

      <para>The first line enables the specified interface to receive
	router solicitation messages.  The second line enables the
	router solicitation daemon, &man.rtsol.8;.</para>

      <para>If the interface needs a statically assigned
	<acronym>IPv6</acronym> address, add an entry to specify the
	static address and associated prefix length:</para>

      <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 <replaceable>2001:db8:4672:6565:2026:5043:2d42:5344</replaceable> prefixlen <replaceable>64</replaceable>"</programlisting>

      <para>To assign a default router, specify its address:</para>

      <programlisting>ipv6_defaultrouter="<replaceable>2001:db8:4672:6565::1</replaceable>"</programlisting>
    </sect2>

    <sect2>
      <title>Connecting to a Provider</title>

      <para>In order to connect to other <acronym>IPv6</acronym>
	networks, one must have a provider or a tunnel that supports
	<acronym>IPv6</acronym>:</para>

      <itemizedlist>
	<listitem>
	  <para>Contact an Internet Service Provider to see if they
	    offer <acronym>IPv6</acronym>.</para>
	</listitem>

	<listitem>
	  <para><link
	      xlink:href="http://www.tunnelbroker.net">Hurricane
	      Electric</link> offers tunnels with end-points all
	    around the globe.</para>
	</listitem>
      </itemizedlist>

      <note>
	<para>Install the <package>net/freenet6</package> package or
	  port for a dial-up connection.</para>
      </note>

      <para>This section demonstrates how to take the directions from
	a tunnel provider and convert them into
	<filename>/etc/rc.conf</filename> settings that will persist
	through reboots.</para>

      <para>The first <filename>/etc/rc.conf</filename> entry creates
	the generic tunneling interface
	<filename><replaceable>gif0</replaceable></filename>:</para>

      <programlisting>cloned_interfaces="gif<replaceable>0</replaceable>"</programlisting>

      <para>Next, configure that interface with the
	<acronym>IPv4</acronym> addresses of the local and remote
	endpoints.  Replace <replaceable>MY_IPv4_ADDR</replaceable>
	and <replaceable>REMOTE_IPv4_ADDR</replaceable> with the
	actual <acronym>IPv4</acronym> addresses:</para>

      <programlisting>create_args_gif0="tunnel <replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>

      <para>To apply the <acronym>IPv6</acronym> address that has been
	assigned for use as the <acronym>IPv6</acronym> tunnel
	endpoint, add this line, replacing
	<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>
	with the assigned address:</para>

      <programlisting>ifconfig_gif0_ipv6="inet6 <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>

      <para>Then, set the default route for the other side of the
	<acronym>IPv6</acronym> tunnel.  Replace
	<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>
	with the default gateway address assigned by the
	provider:</para>

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

      <para>If the &os; system will route <acronym>IPv6</acronym>
	packets between the rest of the network and the world, enable
	the gateway using this line:</para>

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

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

      <para>This section demonstrates how to setup &man.rtadvd.8; to
	advertise the <acronym>IPv6</acronym> default route.</para>

      <para>To enable &man.rtadvd.8;, add the following to
	<filename>/etc/rc.conf</filename>:</para>

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

      <para>It is important to specify the interface on which to
	do <acronym>IPv6</acronym> router solicitation.  For example,
	to tell &man.rtadvd.8; to use
	<filename>rl0</filename>:</para>

      <programlisting>rtadvd_interfaces="rl0"</programlisting>

      <para>Next, create the configuration file,
	<filename>/etc/rtadvd.conf</filename> as seen in this
	example:</para>

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

      <para>Replace <filename>rl0</filename> with the interface
	to be used and <systemitem>2001:db8:1f11:246::</systemitem>
	with the prefix of the allocation.</para>

      <para>For a dedicated <systemitem
	  class="netmask">/64</systemitem> subnet, nothing else needs
	to be changed.  Otherwise, change the
	<literal>prefixlen#</literal> to the correct value.</para>
    </sect2>

    <sect2>
      <title><acronym>IPv6</acronym> and <acronym>IPv6</acronym>
	Address Mapping</title>

      <para>When <acronym>IPv6</acronym> is enabled on a server, there
	may be a need to enable <acronym>IPv4</acronym> mapped
	<acronym>IPv6</acronym> address communication.  This
	compatibility option allows for <acronym>IPv4</acronym>
	addresses to be represented as <acronym>IPv6</acronym>
	addresses.  Permitting <acronym>IPv6</acronym> applications
	to communicate with <acronym>IPv4</acronym> and vice versa
	may be a security issue.</para>

      <para>This option may not be required in most cases and is
	available only for compatibility.  This option will allow
	<acronym>IPv6</acronym>-only applications to work with
	<acronym>IPv4</acronym> in a dual stack environment.  This
	is most useful for third party applications which may not
	support an <acronym>IPv6</acronym>-only environment.  To
	enable this feature,
	add the following to <filename>/etc/rc.conf</filename>:</para>

      <programlisting>ipv6_ipv4mapping="YES"</programlisting>

      <para>Reviewing the information in <acronym>RFC</acronym> 3493,
	section 3.6 and 3.7 as well as <acronym>RFC</acronym> 4038
	section 4.2 may be useful to some administrators.</para>
    </sect2>
  </sect1>
<!--
  <sect1 xml:id="network-atm">
    <info><title>Asynchronous Transfer Mode (<acronym>ATM</acronym>)</title>
      <authorgroup>
	<author>
	  <personname>
	    <firstname>Harti</firstname>
	    <surname>Brandt</surname>
	  </personname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </info>
    <sect2>
      <title>Configuring Classical <acronym>IP</acronym> over
	<acronym>ATM</acronym></title>

      <para>Classical <acronym>IP</acronym> over
	<acronym>ATM</acronym> (<acronym>CLIP</acronym>) is the
	simplest method to use Asynchronous Transfer Mode
	(<acronym>ATM</acronym>) with <acronym>IP</acronym>.  It can
	be used with Switched Virtual Circuits
	(<acronym>SVC</acronym>s) and with Permanent Virtual Circuits
	(<acronym>PVC</acronym>s).  This section describes how to
	set up a network based on <acronym>PVC</acronym>s.</para>

      <sect3>
	<title>Fully Meshed Configurations</title>

	<para>The first method to set up a <acronym>CLIP</acronym>
	  with <acronym>PVC</acronym>s is to connect each machine
	  to each other machine in the network via a dedicated
	  <acronym>PVC</acronym>.  While this is simple to
	  configure, it becomes impractical for a large number of
	  machines.  The following example supposes 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
	  <acronym>IP</acronym> addresses and the <acronym role="Asynchronous Transfer Mode">ATM</acronym>
	  connections between the machines.  This example uses the
	  following:</para>

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

	    <tbody>
	      <row>
		<entry><systemitem>hostA</systemitem></entry>
		<entry><systemitem class="ipaddress">192.168.173.1</systemitem></entry>
	      </row>

	      <row>
		<entry><systemitem>hostB</systemitem></entry>
		<entry><systemitem class="ipaddress">192.168.173.2</systemitem></entry>
	      </row>

	      <row>
		<entry><systemitem>hostC</systemitem></entry>
		<entry><systemitem class="ipaddress">192.168.173.3</systemitem></entry>
	      </row>

	      <row>
		<entry><systemitem>hostD</systemitem></entry>
		<entry><systemitem class="ipaddress">192.168.173.4</systemitem></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</informaltable>

	<para>To build a fully meshed net, one <acronym>ATM</acronym>
	  connection is needed 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><systemitem>hostA</systemitem> -
		  <systemitem>hostB</systemitem></entry>
		<entry>0.100</entry>
	      </row>

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

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

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

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

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

	<para>The Virtual Path Identifier <acronym>VPI</acronym> and
	  Virtual Channel Identifier <acronym>VCI</acronym> values
	  at each end of the connection may differ, but for
	  simplicity, this example assumes they are the same.  Next,
	  configure the <acronym>ATM</acronym> 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>This example assumes that the <acronym>ATM</acronym>
	  interface is <filename>hatm0</filename> on all hosts.
	  Next, the <acronym>PVC</acronym>s need to be configured on
	  <systemitem>hostA</systemitem>.  This should already be
	  configured on the <acronym>ATM</acronym> switch; 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>Other traffic contracts besides <literal>ubr</literal>
	  can be used if the <acronym>ATM</acronym> adapter supports
	  it.  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>Refer to &man.atmconfig.8; for more information.</para>

	<para>The same configuration can also be done via
	  <filename>/etc/rc.conf</filename>.  These lines configure
	  <systemitem>hostA</systemitem>:</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 xml:id="carp">
    <info>
      <title>Common Address Redundancy Protocol
	(<acronym>CARP</acronym>)</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Tom</firstname>
	    <surname>Rhodes</surname>
	  </personname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <personname>
	    <firstname>Allan</firstname>
	    <surname>Jude</surname>
	  </personname>
	  <contrib>Updated by </contrib>
	</author>
      </authorgroup>
    </info>

    <indexterm>
      <primary><acronym>CARP</acronym></primary>
    </indexterm>
    <indexterm>
      <primary>Common Address Redundancy Protocol</primary>
    </indexterm>

    <para>The Common Address Redundancy Protocol
      (<acronym>CARP</acronym>) allows multiple hosts to share the
      same <acronym>IP</acronym> address and Virtual Host ID
      (<acronym>VHID</acronym>) in order to provide <firstterm>high
      availability</firstterm> for one or more services.  This means
      that one or more hosts can fail, and the other hosts will
      transparently take over so that users do not see a service
      failure.</para>

    <para>In addition to the shared <acronym>IP</acronym> address,
      each host has its own <acronym>IP</acronym> address for
      management and configuration.  All of the machines that share an
      <acronym>IP</acronym> address have the same
      <acronym>VHID</acronym>.  The <acronym>VHID</acronym> for each
      virtual <acronym>IP</acronym> address must be unique across the
      broadcast domain of the network interface.</para>

    <para>High availability using <acronym>CARP</acronym> is built
      into &os;, though the steps to configure it vary slightly
      depending upon the &os; version.  This section provides the same
      example configuration for versions before and equal to or after
      &os;&nbsp;10.</para>

    <para>This example configures failover support with three hosts,
      all with unique <acronym>IP</acronym> addresses, but providing
      the same web content.  It has two different masters named
      <systemitem>hosta.example.org</systemitem> and
      <systemitem>hostb.example.org</systemitem>, with a shared backup
      named <systemitem>hostc.example.org</systemitem>.</para>

    <para>These machines are load balanced with a Round Robin
      <acronym>DNS</acronym> configuration.  The master and backup
      machines are configured identically except for their hostnames
      and management <acronym>IP</acronym> addresses.  These servers
      must have the same configuration and run the same services.
      When the failover occurs, requests to the service on the shared
      <acronym>IP</acronym> address can only be answered correctly if
      the backup server has access to the same content.  The backup
      machine has two additional <acronym>CARP</acronym> interfaces,
      one for each of the master content server's
      <acronym>IP</acronym> addresses.  When a failure occurs, the
      backup server will pick up the failed master machine's
      <acronym>IP</acronym> address.</para>

    <sect2 xml:id="carp-10x">
      <title>Using <acronym>CARP</acronym> on &os;&nbsp;10 and
	Later</title>

      <para>Enable boot-time support for <acronym>CARP</acronym> by
	adding an entry for the <filename>carp.ko</filename> kernel
	module in <filename>/boot/loader.conf</filename>:</para>

      <programlisting>carp_load="YES"</programlisting>

      <para>To load the module now without rebooting:</para>

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

      <para>For users who prefer to use a custom kernel, include the
	following line in the custom kernel configuration file and
	compile the kernel as described in <xref
	  linkend="kernelconfig"/>:</para>

      <programlisting>device	carp</programlisting>

      <para>The hostname, management <acronym>IP</acronym> address and
	subnet mask, shared <acronym>IP</acronym> address, and
	<acronym>VHID</acronym> are all set by adding entries to
	<filename>/etc/rc.conf</filename>.  This example is for
	<systemitem>hosta.example.org</systemitem>:</para>

      <programlisting>hostname="<replaceable>hosta.example.org</replaceable>"
ifconfig_<replaceable>em0</replaceable>="inet <replaceable>192.168.1.3</replaceable> netmask <replaceable>255.255.255.0</replaceable>"
ifconfig_<replaceable>em0</replaceable>_alias0="inet vhid <replaceable>1</replaceable> pass <replaceable>testpass</replaceable> alias <replaceable>192.168.1.50</replaceable>/32"</programlisting>

      <para>The next set of entries are for
	<systemitem>hostb.example.org</systemitem>.  Since it
	represents a second master, it uses a different shared
	<acronym>IP</acronym> address and <acronym>VHID</acronym>.
	However, the passwords specified with <option>pass</option>
	must be identical as <acronym>CARP</acronym> will only listen
	to and accept advertisements from machines with the correct
	password.</para>

      <programlisting>hostname="<replaceable>hostb.example.org</replaceable>"
ifconfig_<replaceable>em0</replaceable>="inet <replaceable>192.168.1.4</replaceable> netmask <replaceable>255.255.255.0</replaceable>"
ifconfig_<replaceable>em0</replaceable>_alias0="inet vhid <replaceable>2</replaceable> pass <replaceable>testpass</replaceable> alias <replaceable>192.168.1.51</replaceable>/32"</programlisting>

      <para>The third machine,
	<systemitem>hostc.example.org</systemitem>, is configured to
	handle failover from either master.  This machine is
	configured with two <acronym>CARP</acronym>
	<acronym>VHID</acronym>s, one to handle the virtual
	<acronym>IP</acronym> address for each of the master hosts.
	The <acronym>CARP</acronym> advertising skew,
	<option>advskew</option>, is set to ensure that the backup
	host advertises later than the master, since
	<option>advskew</option> controls the order of precedence when
	there are multiple backup servers.</para>

      <programlisting>hostname="hostc.example.org"
ifconfig_<replaceable>em0</replaceable>="inet <replaceable>192.168.1.5</replaceable> netmask <replaceable>255.255.255.0</replaceable>"
ifconfig_<replaceable>em0</replaceable>_alias0="inet vhid <replaceable>1</replaceable> advskew <replaceable>100</replaceable> pass <replaceable>testpass</replaceable> alias <replaceable>192.168.1.50</replaceable>/32"
ifconfig_<replaceable>em0</replaceable>_alias1="inet vhid <replaceable>2</replaceable> advskew <replaceable>100</replaceable> pass <replaceable>testpass</replaceable> alias <replaceable>192.168.1.51</replaceable>/32"</programlisting>

      <para>Having two <acronym>CARP</acronym>
	<acronym>VHID</acronym>s configured means that
	<systemitem>hostc.example.org</systemitem> will notice if
	either of the master servers becomes unavailable.  If a master
	fails to advertise before the backup server, the backup server
	will pick up the shared <acronym>IP</acronym> address until
	the master becomes available again.</para>

      <note>
	<para>Preemption is disabled by default.  If preemption has
	  been enabled, <systemitem>hostc.example.org</systemitem>
	  might not release the virtual <acronym>IP</acronym> address
	  back to the original master server.  The administrator
	  can force the backup server to return the
	  <acronym>IP</acronym> address to the master with the
	  command:</para>

	<screen>&prompt.root; <userinput>ifconfig em0 vhid 1 state backup</userinput></screen>
      </note>

      <para>Once the configuration is complete, either restart
	networking or reboot each system.  High availability is now
	enabled.</para>

      <para><acronym>CARP</acronym> functionality can be controlled
	via several &man.sysctl.8; variables documented in the
	&man.carp.4; manual pages.  Other actions can be triggered
	from <acronym>CARP</acronym> events by using
	&man.devd.8;.</para>
    </sect2>

    <sect2 xml:id="carp-9x">
      <title>Using <acronym>CARP</acronym> on &os;&nbsp;9 and
	Earlier</title>

      <para>The configuration for these versions of &os; is similar to
	the one described in the previous section, except that a
	<acronym>CARP</acronym> device must first be created and
	referred to in the configuration.</para>

      <para>Enable boot-time support for <acronym>CARP</acronym> by
	loading the <filename>if_carp.ko</filename> kernel module in
	<filename>/boot/loader.conf</filename>:</para>

      <programlisting>if_carp_load="YES"</programlisting>

     <para>To load the module now without rebooting:</para>

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

      <para>For users who prefer to use a custom kernel, include the
	following line in the custom kernel configuration file and
	compile the kernel as described in <xref
	  linkend="kernelconfig"/>:</para>

      <programlisting>device	carp</programlisting>

      <para>Next, on each host, create a <acronym>CARP</acronym>
	device:</para>

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

      <para>Set the hostname, management <acronym>IP</acronym>
	address, the shared <acronym>IP</acronym> address, and
	<acronym>VHID</acronym> by adding the required lines to
	<filename>/etc/rc.conf</filename>.  Since a virtual
	<acronym>CARP</acronym> device is used instead of an alias,
	the actual subnet mask of <literal>/24</literal> is used
	instead of <literal>/32</literal>.  Here are the entries for
	<systemitem>hosta.example.org</systemitem>:</para>

      <programlisting>hostname="<replaceable>hosta.example.org</replaceable>"
ifconfig_<replaceable>fxp0</replaceable>="inet <replaceable>192.168.1.3</replaceable> netmask <replaceable>255.255.255.0</replaceable>"
cloned_interfaces="carp0"
ifconfig_carp0="vhid <replaceable>1</replaceable> pass <replaceable>testpass</replaceable> <replaceable>192.168.1.50/24</replaceable>"</programlisting>

      <para>On <systemitem>hostb.example.org</systemitem>:</para>

      <programlisting>hostname="<replaceable>hostb.example.org</replaceable>"
ifconfig_<replaceable>fxp0</replaceable>="inet <replaceable>192.168.1.4</replaceable> netmask <replaceable>255.255.255.0</replaceable>"
cloned_interfaces="carp0"
ifconfig_carp0="vhid <replaceable>2</replaceable> pass <replaceable>testpass</replaceable> <replaceable>192.168.1.51/24</replaceable>"</programlisting>

      <para>The third machine,
	<systemitem>hostc.example.org</systemitem>, is configured to
	handle failover from either of the master hosts:</para>

      <programlisting>hostname="<replaceable>hostc.example.org</replaceable>"
ifconfig_<replaceable>fxp0</replaceable>="inet <replaceable>192.168.1.5</replaceable> netmask <replaceable>255.255.255.0</replaceable>"
cloned_interfaces="carp0 carp1"
ifconfig_carp0="vhid <replaceable>1</replaceable> advskew <replaceable>100</replaceable> pass <replaceable>testpass</replaceable> <replaceable>192.168.1.50/24</replaceable>"
ifconfig_carp1="vhid <replaceable>2</replaceable> advskew <replaceable>100</replaceable> pass <replaceable>testpass</replaceable> <replaceable>192.168.1.51/24</replaceable>"</programlisting>

      <note>
	<para>Preemption is disabled in the GENERIC &os; kernel.  If
	  preemption has been enabled with a custom kernel,
	  <systemitem>hostc.example.org</systemitem> may not release
	  the <acronym>IP</acronym> address back to the original
	  content server.  The administrator can force the backup
	  server to return the <acronym>IP</acronym> address to the
	  master with the command:</para>

	<screen>&prompt.root; <userinput>ifconfig carp0 down &amp;&amp; ifconfig carp0 up</userinput></screen>

	<para>This should be done on the <filename>carp</filename>
	  interface which corresponds to the correct host.</para>
      </note>

      <para>Once the configuration is complete, either restart
	networking or reboot each system.  High availability is now
	enabled.</para>
    </sect2>
  </sect1>
  <sect1 xml:id="network-vlan">
    <info>
      <title>VLANs</title>
    </info>

    <indexterm>
      <primary><acronym>VLANs</acronym></primary>
    </indexterm>
    <indexterm>
      <primary>Virtual LANs</primary>
    </indexterm>

    <para><acronym>VLANs</acronym> are a way of virtually dividing up
      a network into many different subnetworks.  Each will have its
      own broadcast domain and be isolated from the rest of the
      <acronym>VLANs</acronym>.</para>

    <para>On &os;, <acronym>VLANs</acronym> must be supported by the
      network card driver.  To see which drivers support vlans, refer
      to the &man.vlan.4; manual page.</para>

    <para>When configuring a <acronym>VLAN</acronym>, a couple pieces
      of information must be known.  First, which network interface?
      Second, what is the <acronym>VLAN</acronym> tag?</para>

    <para>To configure <acronym>VLANs</acronym> at run time, with a
      <acronym>NIC</acronym> of <literal>em0</literal> and a
      <acronym>VLAN</acronym> tag of <systemitem>5</systemitem>.  The
      command would look like this:</para>

    <screen>&prompt.root; <userinput>ifconfig <replaceable>em0.5</replaceable> create vlan <replaceable>5</replaceable> vlandev <replaceable>em0</replaceable> inet 192.168.20.20/24</userinput></screen>

    <note>
      <para>See how the interface name includes the
	<acronym>NIC</acronym> driver name and the
	<acronym>VLAN</acronym> tag, separated by a period?  This is a
	best practice to make maintaining the <acronym>VLAN</acronym>
	configuration easy when many <acronym>VLANs</acronym> are
	present on a machine.</para>
    </note>

    <para>To configure <acronym>VLANs</acronym> at boot time,
      <filename>/etc/rc.conf</filename> must be updated.  To duplicate
      the configuration above, the following will need to be
      added:</para>

    <programlisting>vlans_<replaceable>em0</replaceable>="<replaceable>5</replaceable>"
ifconfig_<replaceable>em0</replaceable>_<replaceable>5</replaceable>="inet 192.168.20.20/24"</programlisting>

    <para>Additional <acronym>VLANs</acronym> may be added, by simply
      adding the tag to the
      <literal>vlans_<replaceable>em0</replaceable></literal>
      field and adding an additional line configuring the network on
      that <acronym>VLAN</acronym> tag's interface.</para>
  </sect1>
</chapter>

Return to bug 219966