handbook/advanced-networking/chapter.xml

<?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>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>ath0</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"
ifconfig_<replaceable>iwn0</replaceable>="<replaceable>ether 00:21:70:da:ae:37</replaceable>"
wlans_<replaceable>iwn0</replaceable>="wlan0"
ifconfig_wlan0="WPA"
cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="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-dhcp42-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.sixxs.net">SixXS</link>
            offers tunnels with end-points all around the
            globe.</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>