Attachment 184060 Details for Bug 219966 – Proposed patch

[patch] Proposed patch

r219966_patch (text/plain), 212.30 KB, created by Guangyuan Yang on 2017-07-04 19:53:05 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Guangyuan Yang

Created: 2017-07-04 19:53:05 UTC

Size: 212.30 KB

patch

obsolete

>diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
>index ee1383476b..2a023b04d8 100644
>--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
>+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
>@@ -1,5263 +1,5263 @@
> <?xml version="1.0" encoding="iso-8859-1"?>
> 
> <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>
>       
> 
>       <indexterm>
> 	<primary>dual homed hosts</primary>
>       </indexterm>
> 
>       <para>A &os; system can be configured as the default gateway, or
> 	router, for a network if it is a dual-homed system.  A
> 	dual-homed system is a host which resides on at least two
> 	different networks.  Typically, each network is connected to a
> 	separate network interface, though <acronym>IP</acronym>
> 	aliasing can be used to bind multiple addresses, each on a
> 	different subnet, to one physical interface.</para>
> 
>       <indexterm>
> 	<primary>router</primary>
>       </indexterm>
> 
>       <para>In order for the system to forward packets between
> 	interfaces, &os; must be configured as a router.  Internet
> 	standards and good engineering practice prevent the &os;
> 	Project from enabling this feature by default, but it can be
> 	configured to start at boot by adding this line to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>gateway_enable="YES"          # Set to YES if this host will be a gateway</programlisting>
> 
>       <para>To enable routing now, set the &man.sysctl.8; variable
> 	<varname>net.inet.ip.forwarding</varname> to
> 	<literal>1</literal>.  To stop routing, reset this variable to
> 	<literal>0</literal>.</para>
> 
>       <indexterm>
> 	<primary>BGP</primary>
>       </indexterm>
>       <indexterm>
> 	<primary>RIP</primary>
>       </indexterm>
>       <indexterm>
> 	<primary>OSPF</primary>
>       </indexterm>
> 
>       <para>The routing table of a router needs additional routes so
> 	it knows how to reach other networks.  Routes can be either
> 	added manually using static routes or routes can be
> 	automatically learned using a routing protocol.  Static routes
> 	are appropriate for small networks and this section describes
> 	how to add a static routing entry for a small network.</para>
> 
>       <note>
> 	<para>For large networks, static routes quickly become
> 	  unscalable.  &os; comes with the standard
> 	  <acronym>BSD</acronym> routing daemon &man.routed.8;, which
> 	  provides the routing protocols <acronym>RIP</acronym>,
> 	  versions 1 and 2, and <acronym>IRDP</acronym>.  Support for
> 	  the <acronym>BGP</acronym> and <acronym>OSPF</acronym>
> 	  routing protocols can be installed using the
> 	  <package>net/zebra</package> package or port.</para>
>       </note>
> 
>       <para>Consider the following network:</para>
> 
>       <mediaobject>
> 	<imageobject>
> 	  <imagedata fileref="advanced-networking/static-routes"/>
> 	</imageobject>
> 
> 	<textobject>
> 	<literallayout class="monospaced">
>     INTERNET
>       | (10.0.0.1/24) Default Router to Internet
>       |
>       |Interface xl0
>       |10.0.0.10/24
>    +------+
>    |      | RouterA
>    |      | (FreeBSD gateway)
>    +------+
>       | Interface xl1
>       | 192.168.1.1/24
>       |
>   +--------------------------------+
>    Internal Net 1      | 192.168.1.2/24
>                        |
>                    +------+
>                    |      | RouterB
>                    |      |
>                    +------+
>                        | 192.168.2.1/24
>                        |
>                      Internal Net 2</literallayout>
> 	</textobject>
>       </mediaobject>
> 
>       <para>In this scenario, <systemitem>RouterA</systemitem> is a
> 	&os; machine that is acting as a router to the rest of the
> 	Internet.  It has a default route set to <systemitem
> 	  class="ipaddress">10.0.0.1</systemitem> which allows it to
> 	connect with the outside world.
> 	<systemitem>RouterB</systemitem> is already configured to use
> 	<systemitem class="ipaddress">192.168.1.1</systemitem> as its
> 	default gateway.</para>
> 
>       <para>Before adding any static routes, the routing table on
> 	<systemitem>RouterA</systemitem> looks like this:</para>
> 
>       <screen>&prompt.user; <userinput>netstat -nr</userinput>
> Routing tables
> 
> Internet:
> Destination        Gateway            Flags    Refs      Use  Netif  Expire
> default            10.0.0.1           UGS         0    49378    xl0
> 127.0.0.1          127.0.0.1          UH          0        6    lo0
> 10.0.0.0/24        link#1             UC          0        0    xl0
> 192.168.1.0/24     link#2             UC          0        0    xl1</screen>
> 
>       <para>With the current routing table,
> 	<systemitem>RouterA</systemitem> does not have a route to the
> 	<systemitem class="ipaddress">192.168.2.0/24</systemitem>
> 	network.  The following command adds the <literal>Internal Net
> 	  2</literal> network to <systemitem>RouterA</systemitem>'s
> 	routing table using <systemitem
> 	  class="ipaddress">192.168.1.2</systemitem> as the next
> 	hop:</para>
> 
>       <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen>
> 
>       <para>Now, <systemitem>RouterA</systemitem> can reach any host
> 	on the <systemitem
> 	  class="ipaddress">192.168.2.0/24</systemitem> network.
> 	However, the routing information will not persist if the &os;
> 	system reboots.  If a static route needs to be persistent, add
> 	it to <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting># Add Internal Net 2 as a persistent static route
> static_routes="internalnet2"
> route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting>
> 
>       <para>The <literal>static_routes</literal> configuration
> 	variable is a list of strings separated by a space, where each
> 	string references a route name.  The variable
> 	<literal>route_<replaceable>internalnet2</replaceable></literal>
> 	contains the static route for that route name.</para>
> 
>       <para>Using more than one string in
> 	<literal>static_routes</literal> creates multiple static
> 	routes.  The following shows an example of adding static
> 	routes for the <systemitem
> 	  class="ipaddress">192.168.0.0/24</systemitem> and
> 	<systemitem class="ipaddress">192.168.1.0/24</systemitem>
> 	networks:</para>
> 
>       <programlisting>static_routes="net1 net2"
> route_net1="-net 192.168.0.0/24 192.168.0.1"
> route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting>
>     </sect2>
> 
>     <sect2 xml:id="network-routing-troubleshooting">
>       <title>Troubleshooting</title>
> 
>       <para>When an address space is assigned to a network, the
> 	service provider configures their routing tables so that all
> 	traffic for the network will be sent to the link for the site.
> 	But how do external sites know to send their packets to the
> 	network's <acronym>ISP</acronym>?</para>
> 
>       <para>There is a system that keeps track of all assigned
> 	address spaces and defines their point of connection to the
> 	Internet backbone, or the main trunk lines that carry Internet
> 	traffic across the country and around the world.  Each
> 	backbone machine has a copy of a master set of tables, which
> 	direct traffic for a particular network to a specific
> 	backbone carrier, and from there down the chain of service
> 	providers until it reaches a particular network.</para>
> 
>       <para>It is the task of the service provider to advertise to
> 	the backbone sites that they are the point of connection, and
> 	thus the path inward, for a site.  This is known as route
> 	propagation.</para>
> 
>       <indexterm>
> 	<primary>&man.traceroute.8;</primary>
>       </indexterm>
> 
>       <para>Sometimes, there is a problem with route propagation and
> 	some sites are unable to connect.  Perhaps the most useful
> 	command for trying to figure out where routing is breaking
> 	down is <command>traceroute</command>.  It is useful when
> 	<command>ping</command> fails.</para>
> 
>       <para>When using <command>traceroute</command>, include the
> 	address of the remote host to connect to.  The output will
> 	show the gateway hosts along the path of the attempt,
> 	eventually either reaching the target host, or terminating
> 	because of a lack of connection.  For more information, refer
> 	to &man.traceroute.8;.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-routing-multicast">
>       <title>Multicast Considerations</title>
> 
>       <indexterm>
> 	<primary>multicast routing</primary>
>       </indexterm>
>       <indexterm>
> 	<primary>kernel options</primary>
> 	<secondary>MROUTING</secondary>
>       </indexterm>
> 
>       <para>&os; natively supports both multicast applications and
> 	multicast routing.  Multicast applications do not require any
> 	special configuration in order to run on &os;.  Support for
> 	multicast routing requires that the following option be
> 	compiled into a custom kernel:</para>
> 
>       <programlisting>options MROUTING</programlisting>
> 
>       <para>The multicast routing daemon,
> 	<application>mrouted</application> can be installed using the
> 	<package>net/mrouted</package> package or port.  This daemon
> 	implements the <acronym>DVMRP</acronym> multicast routing
> 	protocol and is configured by editing
> 	<filename>/usr/local/etc/mrouted.conf</filename> in order to
> 	set up the tunnels and <acronym>DVMRP</acronym>.  The
> 	installation of <application>mrouted</application> also
> 	installs <application>map-mbone</application> and
> 	<application>mrinfo</application>, as well as their associated
> 	man pages.  Refer to these for configuration examples.</para>
> 
>       <note>
> 	<para><acronym>DVMRP</acronym> has largely been replaced by
> 	  the <acronym>PIM</acronym> protocol in many multicast
> 	  installations.  Refer to &man.pim.4; for more
> 	  information.</para>
>       </note>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-wireless">
>     <info>
>       <title>Wireless Networking</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <othername>Loader</othername>
> 	  </personname>
> 	</author>
> 	<author>
> 	  <personname>
> 	    <firstname>Marc</firstname>
> 	    <surname>Fonvieille</surname>
> 	  </personname>
> 	</author>
> 	<author>
> 	  <personname>
> 	    <firstname>Murray</firstname>
> 	    <surname>Stokely</surname>
> 	  </personname>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm>
>       <primary>wireless networking</primary>
>     </indexterm>
>     <indexterm>
>       <primary>802.11</primary>
>       <see>wireless networking</see>
>     </indexterm>
> 
>     <sect2>
>       <title>Wireless Networking Basics</title>
> 
>       <para>Most wireless networks are based on the &ieee; 802.11
> 	standards.  A basic wireless network consists of multiple
> 	stations communicating with radios that broadcast in either
> 	the 2.4GHz or 5GHz band, though this varies according to the
> 	locale and is also changing to enable communication in the
> 	2.3GHz and 4.9GHz ranges.</para>
> 
>       <para>802.11 networks are organized in two ways.  In
> 	<emphasis>infrastructure mode</emphasis>, one station acts as
> 	a
> 	master with all the other stations associating to it, the
> 	network is known as a <acronym>BSS</acronym>, and the master
> 	station is termed an access point (<acronym>AP</acronym>).
> 	In a <acronym>BSS</acronym>, all communication passes through
> 	the <acronym>AP</acronym>; even when one station wants to
> 	communicate with another wireless station, messages must go
> 	through the <acronym>AP</acronym>.  In the second form of
> 	network, there is no master and stations communicate directly.
> 	This form of network is termed an <acronym>IBSS</acronym>
> 	and is commonly known as an <emphasis>ad-hoc
> 	  network</emphasis>.</para>
> 
>       <para>802.11 networks were first deployed in the 2.4GHz band
> 	using protocols defined by the &ieee; 802.11 and 802.11b
> 	standard.  These specifications include the operating
> 	frequencies and the <acronym>MAC</acronym> layer
> 	characteristics, including framing and transmission rates,
> 	as communication can occur at various rates.  Later, the
> 	802.11a standard defined operation in the 5GHz band, including
> 	different signaling mechanisms and higher transmission rates.
> 	Still later, the 802.11g standard defined the use of 802.11a
> 	signaling and transmission mechanisms in the 2.4GHz band in
> 	such a way as to be backwards compatible with 802.11b
> 	networks.</para>
> 
>       <para>Separate from the underlying transmission techniques,
> 	802.11 networks have a variety of security mechanisms.  The
> 	original 802.11 specifications defined a simple security
> 	protocol called <acronym>WEP</acronym>.  This protocol uses a
> 	fixed pre-shared key and the RC4 cryptographic cipher to
> 	encode data transmitted on a network.  Stations must all
> 	agree on the fixed key in order to communicate.  This scheme
> 	was shown to be easily broken and is now rarely used except
> 	to discourage transient users from joining networks.  Current
> 	security practice is given by the &ieee; 802.11i specification
> 	that defines new cryptographic ciphers and an additional
> 	protocol to authenticate stations to an access point and
> 	exchange keys for data communication.  Cryptographic keys
> 	are periodically refreshed and there are mechanisms for
> 	detecting and countering intrusion attempts.  Another
> 	security protocol specification commonly used in wireless
> 	networks is termed <acronym>WPA</acronym>, which was a
> 	precursor to 802.11i.  <acronym>WPA</acronym> specifies a
> 	subset of the requirements found in 802.11i and is designed
> 	for implementation on legacy hardware.  Specifically,
> 	<acronym>WPA</acronym> requires only the
> 	<acronym>TKIP</acronym> cipher that is derived from the
> 	original <acronym>WEP</acronym> cipher.  802.11i permits use
> 	of <acronym>TKIP</acronym> but also requires support for a
> 	stronger cipher, AES-CCM, for encrypting data.  The
> 	<acronym>AES</acronym> cipher was not required in
> 	<acronym>WPA</acronym> because it was deemed too
> 	computationally costly to be implemented on legacy
> 	hardware.</para>
> 
>       <para>The other standard to be aware of is 802.11e.  It defines
> 	protocols for deploying multimedia applications, such as
> 	streaming video and voice over IP (<acronym>VoIP</acronym>),
> 	in an 802.11 network.  Like 802.11i, 802.11e also has a
> 	precursor specification termed <acronym>WME</acronym> (later
> 	renamed <acronym>WMM</acronym>) that has been defined by an
> 	industry group as a subset of 802.11e that can be deployed now
> 	to enable multimedia applications while waiting for the final
> 	ratification of 802.11e.  The most important thing to know
> 	about 802.11e and
> 	<acronym>WME</acronym>/<acronym>WMM</acronym> is that it
> 	enables prioritized traffic over a wireless network through
> 	Quality of Service (<acronym>QoS</acronym>) protocols and
> 	enhanced media access protocols.  Proper implementation of
> 	these protocols enables high speed bursting of data and
> 	prioritized traffic flow.</para>
> 
>       <para>&os; supports networks that operate using 802.11a,
> 	802.11b, and 802.11g.  The <acronym>WPA</acronym> and 802.11i
> 	security protocols are likewise supported (in conjunction with
> 	any of 11a, 11b, and 11g) and <acronym>QoS</acronym> and
> 	traffic prioritization required by the
> 	<acronym>WME</acronym>/<acronym>WMM</acronym> protocols are
> 	supported for a limited set of wireless devices.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-wireless-quick-start">
>       <title>Quick Start</title>
> 
>       <para>Connecting a computer to an existing wireless network is
> 	a very common situation.  This procedure shows the steps
> 	required.</para>
> 
>       <procedure>
> 	<step>
> 	  <para>Obtain the <acronym>SSID</acronym> (Service Set
> 	    Identifier) and <acronym>PSK</acronym> (Pre-Shared Key)
> 	    for the wireless network from the network
> 	    administrator.</para>
> 	</step>
> 
> 	<step>
> 	  <para>Identify the wireless adapter.  The &os;
> 	    <filename>GENERIC</filename> kernel includes drivers for
> 	    many common wireless adapters.  If the wireless adapter is
> 	    one of those models, it will be shown in the output from
> 	    &man.ifconfig.8;:</para>
> 
> 	  <screen>&prompt.user; <userinput>ifconfig | grep -B3 -i wireless</userinput></screen>
> 
> 	  <para>On &os;&nbsp;11 or higher, use this command
> 	    instead:</para>
> 
> 	  <screen>&prompt.user; <userinput>sysctl net.wlan.devices</userinput></screen>
> 
> 	  <para>If a wireless adapter is not listed, an additional
> 	    kernel module might be required, or it might be a model
> 	    not supported by &os;.</para>
> 	  
> 
> 	  <para>This example shows the Atheros <literal>ath0</literal>
> 	    wireless adapter.</para>
> 	</step>
> 
> 	<step>
> 	  <para>Add an entry for this network to
> 	    <filename>/etc/wpa_supplicant.conf</filename>.  If the
> 	    file does not exist, create it.  Replace
> 	    <replaceable>myssid</replaceable> and
> 	    <replaceable>mypsk</replaceable> with the
> 	    <acronym>SSID</acronym> and <acronym>PSK</acronym>
> 	    provided by the network administrator.</para>
> 
> 	  <programlisting>network={
> 	ssid="<replaceable>myssid</replaceable>"
> 	psk="<replaceable>mypsk</replaceable>"
> }</programlisting>
> 	</step>
> 
> 	<step>
> 	  <para>Add entries to <filename>/etc/rc.conf</filename> to
> 	    configure the network on startup:</para>
> 
> 	  <programlisting>wlans_<replaceable>ath0</replaceable>="wlan0"
> ifconfig_wlan0="WPA SYNCDHCP"</programlisting>
> 	</step>
> 
> 	<step>
> 	  <para>Restart the computer, or restart the network service
> 	    to connect to the network:</para>
> 
> 	  <screen>&prompt.root; <userinput>service netif restart</userinput></screen>
> 	</step>
>       </procedure>
>     </sect2>
> 
>     <sect2 xml:id="network-wireless-basic">
>       <title>Basic Setup</title>
> 
>       <sect3>
> 	<title>Kernel Configuration</title>
> 
> 	<para>To use wireless networking, a wireless networking card
> 	  is needed and the kernel needs to be configured with the
> 	  appropriate wireless networking support.  The kernel is
> 	  separated into multiple modules so that only the required
> 	  support needs to be configured.</para>
> 
> 	<para>The most
> 	  commonly used wireless devices are those that use parts made
> 	  by Atheros.  These devices are supported by &man.ath.4;
> 	  and require the following line to be added to
> 	  <filename>/boot/loader.conf</filename>:</para>
> 
> 	<programlisting>if_ath_load="YES"</programlisting>
> 
> 	<para>The Atheros driver is split up into three separate
> 	  pieces: the driver (&man.ath.4;), the hardware support
> 	  layer that handles chip-specific functions
> 	  (&man.ath.hal.4;), and an algorithm for selecting the
> 	  rate for transmitting frames.  When this support is loaded
> 	  as kernel modules, any dependencies are automatically
> 	  handled.  To load support for a different type of wireless
> 	  device, specify the module for that device.  This example
> 	  is for devices based on the Intersil Prism parts
> 	  (&man.wi.4;) driver:</para>
> 
> 	<programlisting>if_wi_load="YES"</programlisting>
> 
> 	<note>
> 	  <para>The examples in this section use an &man.ath.4;
> 	    device and the device name in the examples must be
> 	    changed according to the configuration.  A list of
> 	    available wireless drivers and supported adapters can be
> 	    found in the &os; Hardware Notes, available on
> 	    the <link
> 	      xlink:href="http://www.FreeBSD.org/releases/index.html">Release
> 	      Information</link> page of the &os; website.  If a
> 	    native &os; driver for the wireless device does not
> 	    exist, it may be possible to use the &windows; driver
> 	    with the help of the <link
> 	      linkend="config-network-ndis">NDIS</link> driver
> 	    wrapper.</para>
> 	</note>
> 
> 	<para>In addition, the modules that implement cryptographic
> 	  support for the security protocols to use must be loaded.
> 	  These are intended to be dynamically loaded on demand by
> 	  the &man.wlan.4; module, but for now they must be manually
> 	  configured.  The following modules are available:
> 	  &man.wlan.wep.4;, &man.wlan.ccmp.4;, and &man.wlan.tkip.4;.
> 	  The &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are
> 	  only needed when using the <acronym>WPA</acronym> or
> 	  802.11i security protocols.  If the network does not use
> 	  encryption, &man.wlan.wep.4; support is not needed.  To
> 	  load these modules at boot time, add the following lines to
> 	  <filename>/boot/loader.conf</filename>:</para>
> 
> 	<programlisting>wlan_wep_load="YES"
> wlan_ccmp_load="YES"
> wlan_tkip_load="YES"</programlisting>
> 
> 	<para>Once this information has been added to
> 	  <filename>/boot/loader.conf</filename>, reboot the &os;
> 	  box.  Alternately, load the modules by hand using
> 	  &man.kldload.8;.</para>
> 
> 	<note>
> 	  <para>For users who do not want to use modules, it is
> 	    possible to compile these drivers into the kernel by
> 	    adding the following lines to a custom kernel
> 	    configuration file:</para>
> 
> 	  <programlisting>device wlan              # 802.11 support
> device wlan_wep          # 802.11 WEP support
> device wlan_ccmp         # 802.11 CCMP support
> device wlan_tkip         # 802.11 TKIP support
> device wlan_amrr         # AMRR transmit rate control algorithm
> device ath               # Atheros pci/cardbus NIC's
> device ath_hal           # pci/cardbus chip support
> options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors
> device ath_rate_sample   # SampleRate tx rate control for ath</programlisting>
> 
> 	  <para>With this information in the kernel configuration
> 	    file, recompile the kernel and reboot the &os;
> 	    machine.</para>
> 	</note>
> 
> 	<para>Information about the wireless device should appear
> 	  in the boot messages, like this:</para>
> 
> 	<screen>ath0: &lt;Atheros 5212&gt; mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1
> ath0: [ITHREAD]
> ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Infrastructure Mode</title>
> 
>       <para>Infrastructure (<acronym>BSS</acronym>) mode is the
> 	mode that is typically used.  In this mode, a number of
> 	wireless access points are connected to a wired network.
> 	Each wireless network has its own name, called the
> 	<acronym>SSID</acronym>.  Wireless clients connect to the
> 	wireless access points.</para>
> 
>       <sect3>
> 	<title>&os; Clients</title>
> 
> 	<sect4>
> 	  <title>How to Find Access Points</title>
> 
> 	  <para>To scan for available networks, use &man.ifconfig.8;.
> 	    This request may take a few moments to complete as it
> 	    requires the system to switch to each available wireless
> 	    frequency and probe for available access points.  Only
> 	    the superuser can initiate a scan:</para>
> 
> 	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
> SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
> dlinkap         00:13:46:49:41:76   11   54M -90:96   100 EPS  WPA WME
> freebsdap       00:11:95:c3:0d:ac    1   54M -83:96   100 EPS  WPA</screen>
> 
> 	  <note>
> 	    <para>The interface must be <option>up</option> before
> 	      it can scan.  Subsequent scan requests do not require
> 	      the interface to be marked as up again.</para>
> 	  </note>
> 
> 	  <para>The output of a scan request lists each
> 	    <acronym>BSS</acronym>/<acronym>IBSS</acronym> network
> 	    found.  Besides listing the name of the network, the
> 	    <literal>SSID</literal>, the output also shows the
> 	    <literal>BSSID</literal>, which is the
> 	    <acronym>MAC</acronym> address of the access point.  The
> 	    <literal>CAPS</literal> field identifies the type of
> 	    each network and the capabilities of the stations
> 	    operating there:</para>
> 
> 	  <table frame="none" pgwide="0">
> 	    <title>Station Capability Codes</title>
> 
> 	    <tgroup cols="2">
> 	      <thead>
> 		<row>
> 		  <entry>Capability Code</entry>
> 		  <entry>Meaning</entry>
> 		</row>
> 	      </thead>
> 
> 	      <tbody>
> 		<row>
> 		  <entry><literal>E</literal></entry>
> 		  <entry>Extended Service Set
> 		    (<acronym>ESS</acronym>).  Indicates that
> 		    the station is part of an infrastructure network
> 		    rather than an <acronym>IBSS</acronym>/ad-hoc
> 		    network.</entry>
> 		</row>
> 
> 		<row>
> 		  <entry><literal>I</literal></entry>
> 		  <entry><acronym>IBSS</acronym>/ad-hoc network.
> 		    Indicates that the station is part of an ad-hoc
> 		    network rather than an <acronym>ESS</acronym>
> 		    network.</entry>
> 		</row>
> 
> 		<row>
> 		  <entry><literal>P</literal></entry>
> 		  <entry>Privacy.  Encryption is required for all
> 		    data frames exchanged within the
> 		    <acronym>BSS</acronym> using cryptographic means
> 		    such as <acronym>WEP</acronym>,
> 		    <acronym>TKIP</acronym> or
> 		    <acronym>AES</acronym>-<acronym>CCMP</acronym>.</entry>
> 		</row>
> 
> 		<row>
> 		  <entry><literal>S</literal></entry>
> 		  <entry>Short Preamble.  Indicates that the network
> 		    is using short preambles, defined in 802.11b High
> 		    Rate/DSSS PHY, and utilizes a 56 bit sync field
> 		    rather than the 128 bit field used in long
> 		    preamble mode.</entry>
> 		</row>
> 
> 		<row>
> 		  <entry><literal>s</literal></entry>
> 		  <entry>Short slot time.  Indicates that the 802.11g
> 		    network is using a short slot time because there
> 		    are no legacy (802.11b) stations present.</entry>
> 		</row>
> 	      </tbody>
> 	    </tgroup>
> 	  </table>
> 
> 	  <para>One can also display the current list of known
> 	    networks with:</para>
> 
> 	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list scan</userinput></screen>
> 
> 	  <para>This information may be updated automatically by the
> 	    adapter or manually with a <option>scan</option> request.
> 	    Old data is automatically removed from the cache, so over
> 	    time this list may shrink unless more scans are
> 	    done.</para>
> 	</sect4>
> 
> 	<sect4>
> 	  <title>Basic Settings</title>
> 
> 	  <para>This section provides a simple example of how to make
> 	    the wireless network adapter work in &os; without
> 	    encryption.  Once familiar with these concepts, it is
> 	    strongly recommend to use <link
> 	      linkend="network-wireless-wpa">WPA</link> to set up
> 	    the wireless network.</para>
> 
> 	  <para>There are three basic steps to configure a wireless
> 	    network: select an access point, authenticate the
> 	    station, and configure an <acronym>IP</acronym> address.
> 	    The following sections discuss each step.</para>
> 
> 	  <sect5>
> 	    <title>Selecting an Access Point</title>
> 
> 	    <para>Most of the time, it is sufficient to let the system
> 	      choose an access point using the builtin heuristics.
> 	      This is the default behavior when an interface is
> 	      marked as up or it is listed in
> 	      <filename>/etc/rc.conf</filename>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="DHCP"</programlisting>
> 
> 	    <para>If there are multiple access points, a specific
> 	      one can be selected by its
> 	      <acronym>SSID</acronym>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>
> 
> 	    <para>In an environment where there are multiple access
> 	      points with the same <acronym>SSID</acronym>, which
> 	      is often done to simplify roaming, it may be necessary
> 	      to associate to one specific device.  In this case, the
> 	      <acronym>BSSID</acronym> of the access point can be
> 	      specified, with or without the
> 	      <acronym>SSID</acronym>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting>
> 
> 	    <para>There are other ways to constrain the choice of an
> 	      access point, such as limiting the set of frequencies
> 	      the system will scan on.  This may be useful for a
> 	      multi-band wireless card as scanning all the possible
> 	      channels can be time-consuming.  To limit operation to a
> 	      specific band, use the <option>mode</option>
> 	      parameter:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting>
> 
> 	    <para>This example will force the card to operate in
> 	      802.11g, which is defined only for 2.4GHz frequencies
> 	      so any 5GHz channels will not be considered.  This can
> 	      also be achieved with the
> 	      <option>channel</option> parameter, which locks
> 	      operation to one specific frequency, and the
> 	      <option>chanlist</option> parameter, to specify a list
> 	      of channels for scanning.  More information about these
> 	      parameters can be found in &man.ifconfig.8;.</para>
> 	  </sect5>
> 
> 	  <sect5>
> 	    <title>Authentication</title>
> 
> 	    <para>Once an access point is selected, the station
> 	      needs to authenticate before it can pass data.
> 	      Authentication can happen in several ways.  The most
> 	      common scheme, open authentication, allows any station
> 	      to join the network and communicate.  This is the
> 	      authentication to use for test purposes the first time
> 	      a wireless network is setup.  Other schemes require
> 	      cryptographic handshakes to be completed before data
> 	      traffic can flow, either using pre-shared keys or
> 	      secrets, or more complex schemes that involve backend
> 	      services such as <acronym>RADIUS</acronym>.  Open
> 	      authentication is the default setting.  The next most
> 	      common setup is <acronym>WPA-PSK</acronym>, also
> 	      known as <acronym>WPA</acronym> Personal, which is
> 	      described in <xref
> 		linkend="network-wireless-wpa-wpa-psk"/>.</para>
> 
> 	    <note>
> 	      <para>If using an &apple; &airport; Extreme base
> 		station for an access point, shared-key authentication
> 		together with a <acronym>WEP</acronym> key needs to
> 		be configured.  This can be configured in
> 		<filename>/etc/rc.conf</filename> or by using
> 		&man.wpa.supplicant.8;.  For a single &airport; base
> 		station, access can be configured with:</para>
> 
> 	      <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting>
> 
> 	      <para>In general, shared key authentication should be
> 		avoided because it uses the <acronym>WEP</acronym> key
> 		material in a highly-constrained manner, making it
> 		even easier to crack the key.  If
> 		<acronym>WEP</acronym> must be used for compatibility
> 		with legacy devices, it is better to use
> 		<acronym>WEP</acronym> with <literal>open</literal>
> 		authentication.  More information regarding
> 		<acronym>WEP</acronym> can be found in <xref
> 		  linkend="network-wireless-wep"/>.</para>
> 	    </note>
> 	  </sect5>
> 
> 	  <sect5>
> 	    <title>Getting an <acronym>IP</acronym> Address with
> 	      <acronym>DHCP</acronym></title>
> 
> 	    <para>Once an access point is selected and the
> 	      authentication parameters are set, an
> 	      <acronym>IP</acronym> address must be obtained in
> 	      order to communicate.  Most of the time, the
> 	      <acronym>IP</acronym> address is obtained via
> 	      <acronym>DHCP</acronym>.  To achieve that, edit
> 	      <filename>/etc/rc.conf</filename> and add
> 	      <literal>DHCP</literal> to the configuration for the
> 	      device:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="DHCP"</programlisting>
> 
> 	    <para>The
> 	      wireless interface is now ready to bring up:</para>
> 
> 	    <screen>&prompt.root; <userinput>service netif start</userinput></screen>
> 
> 	    <para>Once the interface is running, use &man.ifconfig.8;
> 	      to see the status of the interface
> 	      <filename>ath0</filename>:</para>
> 
> 	    <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>         ether 00:11:95:d5:43:62
>         inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255
>         media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
>         status: associated
>         ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76
>         country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
>         scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
>         roam:rate 5 protmode CTS wme burst</screen>
> 
> 	    <para>The <literal>status: associated</literal> line means
> 	      that it is connected to the wireless network.  The
> 	      <literal>bssid 00:13:46:49:41:76</literal> is the
> 	      <acronym>MAC</acronym> address of the access point and
> 	      <literal>authmode OPEN</literal> indicates that the
> 	      communication is not encrypted.</para>
> 	  </sect5>
> 
> 	  <sect5>
> 	    <title>Static <acronym>IP</acronym> Address</title>
> 
> 	    <para>If an <acronym>IP</acronym> address cannot be
> 	      obtained from a <acronym>DHCP</acronym> server, set a
> 	      fixed <acronym>IP</acronym> address.  Replace the
> 	      <literal>DHCP</literal> keyword shown above with the
> 	      address information.  Be sure to retain any other
> 	      parameters for selecting the access point:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting>
> 	  </sect5>
> 	</sect4>
> 
> 	<sect4 xml:id="network-wireless-wpa">
> 	  <title><acronym>WPA</acronym></title>
> 
> 	  <para>Wi-Fi Protected Access (<acronym>WPA</acronym>) is a
> 	    security protocol used together with 802.11 networks to
> 	    address the lack of proper authentication and the weakness
> 	    of <acronym>WEP</acronym>.  WPA leverages the 802.1X
> 	    authentication protocol and uses one of several ciphers
> 	    instead of <acronym>WEP</acronym> for data integrity.
> 	    The only cipher required by <acronym>WPA</acronym> is the
> 	    Temporary Key Integrity Protocol
> 	    (<acronym>TKIP</acronym>).  <acronym>TKIP</acronym> is a
> 	    cipher that extends the basic RC4 cipher used by
> 	    <acronym>WEP</acronym> by adding integrity checking,
> 	    tamper detection, and measures for responding to detected
> 	    intrusions.  <acronym>TKIP</acronym> is designed to work
> 	    on legacy hardware with only software modification.  It
> 	    represents a compromise that improves security but is
> 	    still not entirely immune to attack.
> 	    <acronym>WPA</acronym> also specifies the
> 	    <acronym>AES-CCMP</acronym> cipher as an alternative to
> 	    <acronym>TKIP</acronym>, and that is preferred when
> 	    possible.  For this specification, the term
> 	    <acronym>WPA2</acronym> or <acronym>RSN</acronym> is
> 	    commonly used.</para>
> 
> 	  <para><acronym>WPA</acronym> defines authentication and
> 	    encryption protocols.  Authentication is most commonly
> 	    done using one of two techniques: by 802.1X and a backend
> 	    authentication service such as <acronym>RADIUS</acronym>,
> 	    or by a minimal handshake between the station and the
> 	    access point using a pre-shared secret.  The former is
> 	    commonly termed <acronym>WPA</acronym> Enterprise and the
> 	    latter is known as <acronym>WPA</acronym> Personal.  Since
> 	    most people will not set up a <acronym>RADIUS</acronym>
> 	    backend server for their wireless network,
> 	    <acronym>WPA-PSK</acronym> is by far the most commonly
> 	    encountered configuration for
> 	    <acronym>WPA</acronym>.</para>
> 
> 	  <para>The control of the wireless connection and the key
> 	    negotiation or authentication with a server is done using
> 	    &man.wpa.supplicant.8;.  This program requires a
> 	    configuration file,
> 	    <filename>/etc/wpa_supplicant.conf</filename>, to run.
> 	    More information regarding this file can be found in
> 	    &man.wpa.supplicant.conf.5;.</para>
> 
> 	  <sect5 xml:id="network-wireless-wpa-wpa-psk">
> 	    <title><acronym>WPA-PSK</acronym></title>
> 
> 	    <para><acronym>WPA-PSK</acronym>, also known as
> 	      <acronym>WPA</acronym> Personal, is based on a
> 	      pre-shared key (<acronym>PSK</acronym>) which is
> 	      generated from a given password and used as the master
> 	      key in the wireless network.  This means every wireless
> 	      user will share the same key.
> 	      <acronym>WPA-PSK</acronym> is intended for small
> 	      networks where the use of an authentication server is
> 	      not possible or desired.</para>
> 
> 	    <warning>
> 	      <para>Always use strong passwords that are sufficiently
> 		long and made from a rich alphabet so that they will
> 		not be easily guessed or attacked.</para>
> 	    </warning>
> 
> 	    <para>The first step is the configuration of
> 	      <filename>/etc/wpa_supplicant.conf</filename> with
> 	      the <acronym>SSID</acronym> and the pre-shared key of
> 	      the network:</para>
> 
> 	    <programlisting>network={
>   ssid="freebsdap"
>   psk="freebsdmall"
> }</programlisting>
> 
> 	    <para>Then, in <filename>/etc/rc.conf</filename>,
> 	      indicate that the wireless device configuration will be
> 	      done with <acronym>WPA</acronym> and the
> 	      <acronym>IP</acronym> address will be obtained with
> 	      <acronym>DHCP</acronym>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="WPA DHCP"</programlisting>
> 
> 	    <para>Then, bring up the interface:</para>
> 
> 	    <screen>&prompt.root; <userinput>service netif start</userinput>
> Starting wpa_supplicant.
> DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5
> DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6
> DHCPOFFER from 192.168.0.1
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67
> DHCPACK from 192.168.0.1
> bound to 192.168.0.254 -- renewal in 300 seconds.
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>       ether 00:11:95:d5:43:62
>       inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
>       media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
>       status: associated
>       ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
>       country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
>       AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
>       bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
>       wme burst roaming MANUAL</screen>
> 
> 	    <para>Or, try to configure the interface manually using
> 	      the information in
> 	      <filename>/etc/wpa_supplicant.conf</filename>:</para>
> 
> 	    <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
> Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz)
> Associated with 00:11:95:c3:0d:ac
> WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP]
> CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=]</screen>
> 
> 	    <para>The next operation is to launch &man.dhclient.8;
> 	      to get the <acronym>IP</acronym> address from the
> 	      <acronym>DHCP</acronym> server:</para>
> 
> 	    <screen>&prompt.root; <userinput>dhclient <replaceable>wlan0</replaceable></userinput>
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67
> DHCPACK from 192.168.0.1
> bound to 192.168.0.254 -- renewal in 300 seconds.
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>       ether 00:11:95:d5:43:62
>       inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
>       media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
>       status: associated
>       ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
>       country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
>       AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
>       bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
>       wme burst roaming MANUAL</screen>
> 
> 	    <note>
> 	      <para>If <filename>/etc/rc.conf</filename> has an
> 		<literal>ifconfig_wlan0="DHCP"</literal> entry,
> 		&man.dhclient.8; will be launched automatically after
> 		&man.wpa.supplicant.8; associates with the access
> 		point.</para>
> 	    </note>
> 
> 	    <para>If <acronym>DHCP</acronym> is not possible or
> 	      desired, set a static <acronym>IP</acronym> address
> 	      after &man.wpa.supplicant.8; has authenticated the
> 	      station:</para>
> 
> 	    <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>       ether 00:11:95:d5:43:62
>       inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255
>       media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g
>       status: associated
>       ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
>       country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
>       AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
>       bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
>       wme burst roaming MANUAL</screen>
> 
> 	    <para>When <acronym>DHCP</acronym> is not used, the
> 	      default gateway and the nameserver also have to be
> 	      manually set:</para>
> 
> 	    <screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput>
> &prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" &gt;&gt; /etc/resolv.conf</userinput></screen>
> 	  </sect5>
> 
> 	  <sect5 xml:id="network-wireless-wpa-eap-tls">
> 	    <title><acronym>WPA</acronym> with
> 	      <acronym>EAP-TLS</acronym></title>
> 
> 	    <para>The second way to use <acronym>WPA</acronym> is with
> 	      an 802.1X backend authentication server.  In this case,
> 	      <acronym>WPA</acronym> is called
> 	      <acronym>WPA</acronym> Enterprise to differentiate it
> 	      from the less secure <acronym>WPA</acronym> Personal.
> 	      Authentication in <acronym>WPA</acronym> Enterprise is
> 	      based on the Extensible Authentication Protocol
> 	      (<acronym>EAP</acronym>).</para>
> 
> 	    <para><acronym>EAP</acronym> does not come with an
> 	      encryption method.  Instead, <acronym>EAP</acronym> is
> 	      embedded inside an encrypted tunnel.  There are many
> 	      <acronym>EAP</acronym> authentication methods, but
> 	      <acronym>EAP-TLS</acronym>, <acronym>EAP-TTLS</acronym>,
> 	      and <acronym>EAP-PEAP</acronym> are the most
> 	      common.</para>
> 
> 	    <para>EAP with Transport Layer Security
> 	      (<acronym>EAP-TLS</acronym>) is a well-supported
> 	      wireless authentication protocol since it was the
> 	      first <acronym>EAP</acronym> method to be certified
> 	      by the <link
> 		xlink:href="http://www.wi-fi.org/">Wi-Fi
> 		Alliance</link>.  <acronym>EAP-TLS</acronym> requires
> 	      three certificates to run: the certificate of the
> 	      Certificate Authority (<acronym>CA</acronym>) installed
> 	      on all machines, the server certificate for the
> 	      authentication server, and one client certificate for
> 	      each wireless client.  In this <acronym>EAP</acronym>
> 	      method, both the authentication server and wireless
> 	      client authenticate each other by presenting their
> 	      respective certificates, and then verify that these
> 	      certificates were signed by the organization's
> 	      <acronym>CA</acronym>.</para>
> 
> 	    <para>As previously, the configuration is done via
> 	      <filename>/etc/wpa_supplicant.conf</filename>:</para>
> 
> 	    <programlisting>network={
>   ssid="freebsdap" <co xml:id="co-tls-ssid"/>
>   proto=RSN  <co xml:id="co-tls-proto"/>
>   key_mgmt=WPA-EAP <co xml:id="co-tls-kmgmt"/>
>   eap=TLS <co xml:id="co-tls-eap"/>
>   identity="loader" <co xml:id="co-tls-id"/>
>   ca_cert="/etc/certs/cacert.pem" <co xml:id="co-tls-cacert"/>
>   client_cert="/etc/certs/clientcert.pem" <co xml:id="co-tls-clientcert"/>
>   private_key="/etc/certs/clientkey.pem" <co xml:id="co-tls-pkey"/>
>   private_key_passwd="freebsdmallclient" <co xml:id="co-tls-pwd"/>
> }</programlisting>
> 
> 	    <calloutlist>
> 	      <callout arearefs="co-tls-ssid">
> 		<para>This field indicates the network name
> 		  (<acronym>SSID</acronym>).</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-proto">
> 		<para>This example uses the <acronym>RSN</acronym>
> 		  &ieee; 802.11i protocol, also known as
> 		  <acronym>WPA2</acronym>.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-kmgmt">
> 		<para>The <literal>key_mgmt</literal> line refers to
> 		  the key management protocol to use.  In this
> 		  example, it is <acronym>WPA</acronym> using
> 		  <acronym>EAP</acronym> authentication.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-eap">
> 		<para>This field indicates the <acronym>EAP</acronym>
> 		  method for the connection.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-id">
> 		<para>The <literal>identity</literal> field contains
> 		  the identity string for
> 		  <acronym>EAP</acronym>.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-cacert">
> 		<para>The <literal>ca_cert</literal> field indicates
> 		  the pathname of the <acronym>CA</acronym>
> 		  certificate file.  This file is needed to verify
> 		  the server certificate.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-clientcert">
> 		<para>The <literal>client_cert</literal> line gives
> 		  the pathname to the client certificate file.  This
> 		  certificate is unique to each wireless client of the
> 		  network.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-pkey">
> 		<para>The <literal>private_key</literal> field is the
> 		  pathname to the client certificate private key
> 		  file.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-tls-pwd">
> 		<para>The <literal>private_key_passwd</literal> field
> 		  contains the passphrase for the private key.</para>
> 	      </callout>
> 	    </calloutlist>
> 
> 	    <para>Then, add the following lines to
> 	      <filename>/etc/rc.conf</filename>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="WPA DHCP"</programlisting>
> 
> 	    <para>The next step is to bring up the interface:</para>
> 
> 	    <screen>&prompt.root; <userinput>service netif start</userinput>
> Starting wpa_supplicant.
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
> DHCPACK from 192.168.0.20
> bound to 192.168.0.254 -- renewal in 300 seconds.
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>       ether 00:11:95:d5:43:62
>       inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
>       media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
>       status: associated
>       ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
>       country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
>       AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
>       bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
>       wme burst roaming MANUAL</screen>
> 
> 	    <para>It is also possible to bring up the interface
> 	      manually using &man.wpa.supplicant.8; and
> 	      &man.ifconfig.8;.</para>
> 	  </sect5>
> 
> 	  <sect5 xml:id="network-wireless-wpa-eap-ttls">
> 	    <title><acronym>WPA</acronym> with
> 	      <acronym>EAP-TTLS</acronym></title>
> 
> 	    <para>With <acronym>EAP-TLS</acronym>, both the
> 	      authentication server and the client need a certificate.
> 	      With <acronym>EAP-TTLS</acronym>, a client certificate
> 	      is optional.  This method is similar to a web server
> 	      which creates a secure <acronym>SSL</acronym> tunnel
> 	      even if visitors do not have client-side certificates.
> 	      <acronym>EAP-TTLS</acronym> uses an encrypted
> 	      <acronym>TLS</acronym> tunnel for safe transport of
> 	      the authentication data.</para>
> 
> 	    <para>The required configuration can be added to
> 	      <filename>/etc/wpa_supplicant.conf</filename>:</para>
> 
> 	    <programlisting>network={
>   ssid="freebsdap"
>   proto=RSN
>   key_mgmt=WPA-EAP
>   eap=TTLS <co xml:id="co-ttls-eap"/>
>   identity="test" <co xml:id="co-ttls-id"/>
>   password="test" <co xml:id="co-ttls-passwd"/>
>   ca_cert="/etc/certs/cacert.pem" <co xml:id="co-ttls-cacert"/>
>   phase2="auth=MD5" <co xml:id="co-ttls-pha2"/>
> }</programlisting>
> 
> 	    <calloutlist>
> 	      <callout arearefs="co-ttls-eap">
> 		<para>This field specifies the <acronym>EAP</acronym>
> 		  method for the connection.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-ttls-id">
> 		<para>The <literal>identity</literal> field contains
> 		  the identity string for <acronym>EAP</acronym>
> 		  authentication inside the encrypted
> 		  <acronym>TLS</acronym> tunnel.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-ttls-passwd">
> 		<para>The <literal>password</literal> field contains
> 		  the passphrase for the <acronym>EAP</acronym>
> 		  authentication.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-ttls-cacert">
> 		<para>The <literal>ca_cert</literal> field indicates
> 		  the pathname of the <acronym>CA</acronym>
> 		  certificate file.  This file is needed to verify
> 		  the server certificate.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-ttls-pha2">
> 		<para>This field specifies the authentication
> 		  method used in the encrypted <acronym>TLS</acronym>
> 		  tunnel.  In this example,
> 		  <acronym>EAP</acronym> with MD5-Challenge is used.
> 		  The <quote>inner authentication</quote> phase is
> 		  often called <quote>phase2</quote>.</para>
> 	      </callout>
> 	    </calloutlist>
> 
> 	    <para>Next, add the following lines to
> 	      <filename>/etc/rc.conf</filename>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="WPA DHCP"</programlisting>
> 
> 	    <para>The next step is to bring up the interface:</para>
> 
> 	    <screen>&prompt.root; <userinput>service netif start</userinput>
> Starting wpa_supplicant.
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21
> DHCPACK from 192.168.0.20
> bound to 192.168.0.254 -- renewal in 300 seconds.
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>       ether 00:11:95:d5:43:62
>       inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
>       media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
>       status: associated
>       ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
>       country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
>       AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
>       bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
>       wme burst roaming MANUAL</screen>
> 	  </sect5>
> 
> 	  <sect5 xml:id="network-wireless-wpa-eap-peap">
> 	    <title><acronym>WPA</acronym> with
> 	      <acronym>EAP-PEAP</acronym></title>
> 
> 	    <note>
> 	      <para><acronym>PEAPv0/EAP-MSCHAPv2</acronym> is the most
> 		common <acronym>PEAP</acronym> method.  In this
> 		chapter, the term <acronym>PEAP</acronym> is used to
> 		refer to that method.</para>
> 	    </note>
> 
> 	    <para>Protected EAP (<acronym>PEAP</acronym>) is designed
> 	      as an alternative to <acronym>EAP-TTLS</acronym> and
> 	      is the most used <acronym>EAP</acronym> standard after
> 	      <acronym>EAP-TLS</acronym>.  In a network with mixed
> 	      operating systems, <acronym>PEAP</acronym> should be
> 	      the most supported standard after
> 	      <acronym>EAP-TLS</acronym>.</para>
> 
> 	    <para><acronym>PEAP</acronym> is similar to
> 	      <acronym>EAP-TTLS</acronym> as it uses a server-side
> 	      certificate to authenticate clients by creating an
> 	      encrypted <acronym>TLS</acronym> tunnel between the
> 	      client and the authentication server, which protects
> 	      the ensuing exchange of authentication information.
> 	      <acronym>PEAP</acronym> authentication differs from
> 	      <acronym>EAP-TTLS</acronym> as it broadcasts the
> 	      username in the clear and only the password is sent
> 	      in the encrypted <acronym>TLS</acronym> tunnel.
> 	      <acronym>EAP-TTLS</acronym> will use the
> 	      <acronym>TLS</acronym> tunnel for both the username
> 	      and password.</para>
> 
> 	    <para>Add the following lines to
> 	      <filename>/etc/wpa_supplicant.conf</filename> to
> 	      configure the <acronym>EAP-PEAP</acronym> related
> 	      settings:</para>
> 
> 	    <programlisting>network={
>   ssid="freebsdap"
>   proto=RSN
>   key_mgmt=WPA-EAP
>   eap=PEAP <co xml:id="co-peap-eap"/>
>   identity="test" <co xml:id="co-peap-id"/>
>   password="test" <co xml:id="co-peap-passwd"/>
>   ca_cert="/etc/certs/cacert.pem" <co xml:id="co-peap-cacert"/>
>   phase1="peaplabel=0" <co xml:id="co-peap-pha1"/>
>   phase2="auth=MSCHAPV2" <co xml:id="co-peap-pha2"/>
> }</programlisting>
> 
> 	    <calloutlist>
> 	      <callout arearefs="co-peap-eap">
> 		<para>This field specifies the <acronym>EAP</acronym>
> 		  method for the connection.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-peap-id">
> 		<para>The <literal>identity</literal> field contains
> 		  the identity string for <acronym>EAP</acronym>
> 		  authentication inside the encrypted
> 		  <acronym>TLS</acronym> tunnel.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-peap-passwd">
> 		<para>The <literal>password</literal> field contains
> 		  the passphrase for the <acronym>EAP</acronym>
> 		  authentication.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-peap-cacert">
> 		<para>The <literal>ca_cert</literal> field indicates
> 		  the pathname of the <acronym>CA</acronym>
> 		  certificate file.  This file is needed to verify
> 		  the server certificate.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-peap-pha1">
> 		<para>This field contains the parameters for the
> 		  first phase of authentication, the
> 		  <acronym>TLS</acronym> tunnel.  According to the
> 		  authentication server used, specify a specific
> 		  label for authentication.  Most of the time, the
> 		  label will be <quote>client <acronym>EAP</acronym>
> 		    encryption</quote> which is set by using
> 		  <literal>peaplabel=0</literal>.  More information
> 		  can be found in  &man.wpa.supplicant.conf.5;.</para>
> 	      </callout>
> 
> 	      <callout arearefs="co-peap-pha2">
> 		<para>This field specifies the authentication
> 		  protocol used in the encrypted
> 		  <acronym>TLS</acronym> tunnel.  In the
> 		  case of <acronym>PEAP</acronym>, it is
> 		  <literal>auth=MSCHAPV2</literal>.</para>
> 	      </callout>
> 	    </calloutlist>
> 
> 	    <para>Add the following to
> 	      <filename>/etc/rc.conf</filename>:</para>
> 
> 	    <programlisting>wlans_ath0="wlan0"
> ifconfig_wlan0="WPA DHCP"</programlisting>
> 
> 	    <para>Then, bring up the interface:</para>
> 
> 	    <screen>&prompt.root; <userinput>service netif start</userinput>
> Starting wpa_supplicant.
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15
> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21
> DHCPACK from 192.168.0.20
> bound to 192.168.0.254 -- renewal in 300 seconds.
> wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>       ether 00:11:95:d5:43:62
>       inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255
>       media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g
>       status: associated
>       ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
>       country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF
>       AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan
>       bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS
>       wme burst roaming MANUAL</screen>
> 	  </sect5>
> 	</sect4>
> 
> 	<sect4 xml:id="network-wireless-wep">
> 	  <title><acronym>WEP</acronym></title>
> 
> 	  <para>Wired Equivalent Privacy (<acronym>WEP</acronym>) is
> 	    part of the original 802.11 standard.  There is no
> 	    authentication mechanism, only a weak form of access
> 	    control which is easily cracked.</para>
> 
> 	  <para><acronym>WEP</acronym> can be set up using
> 	    &man.ifconfig.8;:</para>
> 
> 	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
> 	    ssid <replaceable>my_net</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable></userinput></screen>
> 
> 	  <itemizedlist>
> 	    <listitem>
> 
> 	      <para>The <literal>weptxkey</literal> specifies which
> 		<acronym>WEP</acronym> key will be used in the
> 		transmission.  This example uses the third key.
> 		This must match the setting on the access point.
> 		When unsure which key is used by the access point,
> 		try <literal>1</literal> (the first key) for this
> 		value.</para>
> 	    </listitem>
> 
> 	    <listitem>
> 	      <para>The <literal>wepkey</literal> selects one of the
> 		<acronym>WEP</acronym> keys.  It should be in the
> 		format <replaceable>index:key</replaceable>.  Key
> 		<literal>1</literal> is used by default; the index
> 		only needs to be set when using a key other than the
> 		first key.</para>
> 
> 	      <note>
> 		<para>Replace the <literal>0x3456789012</literal>
> 		  with the key configured for use on the access
> 		  point.</para>
> 	      </note>
> 	    </listitem>
> 	  </itemizedlist>
> 
> 	  <para>Refer to &man.ifconfig.8; for further
> 	    information.</para>
> 
> 	  <para>The &man.wpa.supplicant.8; facility can be used to
> 	    configure a wireless interface with
> 	    <acronym>WEP</acronym>.  The example above can be set up
> 	    by adding the following lines to
> 	    <filename>/etc/wpa_supplicant.conf</filename>:</para>
> 
> 	  <programlisting>network={
>   ssid="my_net"
>   key_mgmt=NONE
>   wep_key3=3456789012
>   wep_tx_keyidx=3
> }</programlisting>
> 
> 	  <para>Then:</para>
> 
> 	  <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput>
> Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz)
> Associated with 00:13:46:49:41:76</screen>
> 	</sect4>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Ad-hoc Mode</title>
> 
>       <para><acronym>IBSS</acronym> mode, also called ad-hoc mode, is
> 	designed for point to point connections.  For example, to
> 	establish an ad-hoc network between the machines
> 	<systemitem>A</systemitem> and <systemitem>B</systemitem>,
> 	choose two <acronym>IP</acronym> addresses and a
> 	<acronym>SSID</acronym>.</para>
> 
>       <para>On <systemitem>A</systemitem>:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
>   wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	  ether 00:11:95:c3:0d:ac
> 	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
> 	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;adhoc&gt;
> 	  status: running
> 	  ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
> 	  country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
> 	  protmode CTS wme burst</screen>
> 
>       <para>The <literal>adhoc</literal> parameter indicates that the
> 	interface is running in <acronym>IBSS</acronym> mode.</para>
> 
>       <para><systemitem>B</systemitem> should now be able to detect
> 	<systemitem>A</systemitem>:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
>   SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
>   freebsdap       02:11:95:c3:0d:ac    2   54M -64:-96  100 IS   WME</screen>
> 
>       <para>The <literal>I</literal> in the output confirms that
> 	<systemitem>A</systemitem> is in ad-hoc mode.  Now, configure
> 	<systemitem>B</systemitem> with a different
> 	<acronym>IP</acronym> address:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
>   wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	  ether 00:11:95:d5:43:62
> 	  inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
> 	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;adhoc&gt;
> 	  status: running
> 	  ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac
> 	  country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
> 	  protmode CTS wme burst</screen>
> 
>       <para>Both <systemitem>A</systemitem> and
> 	<systemitem>B</systemitem> are now ready to exchange
> 	information.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-wireless-ap">
>       <title>&os; Host Access Points</title>
> 
>       <para>&os; can act as an Access Point (<acronym>AP</acronym>)
> 	which eliminates the need to buy a hardware
> 	<acronym>AP</acronym> or run an ad-hoc network.  This can
> 	be particularly useful when a &os; machine is acting as a
> 	gateway to another network such as the Internet.</para>
> 
>       <sect3 xml:id="network-wireless-ap-basic">
> 	<title>Basic Settings</title>
> 
> 	<para>Before configuring a &os; machine as an
> 	  <acronym>AP</acronym>, the kernel must be configured with
> 	  the appropriate networking support for the wireless card
> 	  as well as the security protocols being used.  For more
> 	  details, see <xref
> 	    linkend="network-wireless-basic"/>.</para>
> 
> 	<note>
> 	  <para>The <acronym>NDIS</acronym> driver wrapper for
> 	    &windows; drivers does not currently support
> 	    <acronym>AP</acronym> operation.  Only native &os;
> 	    wireless drivers support <acronym>AP</acronym>
> 	    mode.</para>
> 	</note>
> 
> 	<para>Once wireless networking support is loaded, check if
> 	  the wireless device supports the host-based access point
> 	  mode, also known as hostap mode:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput>
> drivercaps=6f85edc1&lt;STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG&gt;
> cryptocaps=1f&lt;WEP,TKIP,AES,AES_CCM,TKIPMIC&gt;</screen>
> 
> 	<para>This output displays the card's capabilities.  The
> 	  <literal>HOSTAP</literal> word confirms that this wireless
> 	  card can act as an <acronym>AP</acronym>.  Various supported
> 	  ciphers are also listed: <acronym>WEP</acronym>,
> 	  <acronym>TKIP</acronym>, and <acronym>AES</acronym>.  This
> 	  information indicates which security protocols can be used
> 	  on the <acronym>AP</acronym>.</para>
> 
> 	<para>The wireless device can only be put into hostap mode
> 	  during the creation of the network pseudo-device, so a
> 	  previously created device must be destroyed first:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> destroy</userinput></screen>
> 
> 	<para>then regenerated with the correct option before setting
> 	  the other parameters:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen>
> 
> 	<para>Use &man.ifconfig.8; again to see the status of the
> 	  <filename>wlan0</filename> interface:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
>   wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	  ether 00:11:95:c3:0d:ac
> 	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
> 	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;hostap&gt;
> 	  status: running
> 	  ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
> 	  country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60
> 	  protmode CTS wme burst dtimperiod 1 -dfs</screen>
> 
> 	<para>The <literal>hostap</literal> parameter indicates the
> 	  interface is running in the host-based access point
> 	  mode.</para>
> 
> 	<para>The interface configuration can be done automatically at
> 	  boot time by adding the following lines to
> 	  <filename>/etc/rc.conf</filename>:</para>
> 
> 	<programlisting>wlans_ath0="wlan0"
> create_args_wlan0="wlanmode hostap"
> ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel <replaceable>1</replaceable>"</programlisting>
>       </sect3>
> 
>       <sect3>
> 	<title>Host-based Access Point Without Authentication or
> 	  Encryption</title>
> 
> 	<para>Although it is not recommended to run an
> 	  <acronym>AP</acronym> without any authentication or
> 	  encryption, this is a simple way to check if the
> 	  <acronym>AP</acronym> is working.  This configuration is
> 	  also important for debugging client issues.</para>
> 
> 	<para>Once the <acronym>AP</acronym> is configured, initiate
> 	  a scan from another wireless machine to find the
> 	  <acronym>AP</acronym>:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
> SSID/MESH ID    BSSID              CHAN RATE   S:N     INT CAPS
> freebsdap       00:11:95:c3:0d:ac    1   54M -66:-96  100 ES   WME</screen>
> 
> 	<para>The client machine found the <acronym>AP</acronym> and
> 	  can be associated with it:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
>   wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	  ether 00:11:95:d5:43:62
> 	  inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255
> 	  media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g
> 	  status: associated
> 	  ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac
> 	  country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7
> 	  scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7
> 	  roam:rate 5 protmode CTS wme burst</screen>
>       </sect3>
> 
>       <sect3 xml:id="network-wireless-ap-wpa">
> 	<title><acronym>WPA2</acronym> Host-based Access Point</title>
> 
> 	<para>This section focuses on setting up a &os;
> 	  access point using the <acronym>WPA2</acronym>
> 	  security protocol.  More details regarding
> 	  <acronym>WPA</acronym> and the configuration of
> 	  <acronym>WPA</acronym>-based wireless clients can be found
> 	  in <xref linkend="network-wireless-wpa"/>.</para>
> 
> 	<para>The &man.hostapd.8; daemon is used to deal with client
> 	  authentication and key management on the
> 	  <acronym>WPA2</acronym>-enabled
> 	  <acronym>AP</acronym>.</para>
> 
> 	<para>The following configuration operations are performed
> 	  on the &os; machine acting as the <acronym>AP</acronym>.
> 	  Once the <acronym>AP</acronym> is correctly working,
> 	  &man.hostapd.8; can be automatically started at boot
> 	  with this line in
> 	  <filename>/etc/rc.conf</filename>:</para>
> 
> 	<programlisting>hostapd_enable="YES"</programlisting>
> 
> 	<para>Before trying to configure &man.hostapd.8;, first
> 	  configure the basic settings introduced in <xref
> 	    linkend="network-wireless-ap-basic"/>.</para>
> 
> 	<sect4>
> 	  <title><acronym>WPA2-PSK</acronym></title>
> 
> 	  <para><acronym>WPA2-PSK</acronym> is intended for small
> 	    networks where the use of a backend authentication server
> 	    is not possible or desired.</para>
> 
> 	  <para>The configuration is done in
> 	    <filename>/etc/hostapd.conf</filename>:</para>
> 
> 	  <programlisting>interface=wlan0                  <co xml:id="co-ap-wpapsk-iface"/>
> debug=1                          <co xml:id="co-ap-wpapsk-dbug"/>
> ctrl_interface=/var/run/hostapd  <co xml:id="co-ap-wpapsk-ciface"/>
> ctrl_interface_group=wheel       <co xml:id="co-ap-wpapsk-cifacegrp"/>
> ssid=freebsdap                   <co xml:id="co-ap-wpapsk-ssid"/>
> wpa=2                            <co xml:id="co-ap-wpapsk-wpa"/>
> wpa_passphrase=freebsdmall       <co xml:id="co-ap-wpapsk-pass"/>
> wpa_key_mgmt=WPA-PSK             <co xml:id="co-ap-wpapsk-kmgmt"/>
> wpa_pairwise=CCMP                <co xml:id="co-ap-wpapsk-pwise"/></programlisting>
> 
> 	  <calloutlist>
> 	    <callout arearefs="co-ap-wpapsk-iface">
> 	      <para>Wireless interface used
> 		for the access point.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-dbug">
> 	      <para>Level of verbosity used during the
> 		execution of &man.hostapd.8;.  A value of
> 		<literal>1</literal> represents the minimal
> 		level.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-ciface">
> 	      <para>Pathname of the directory used by &man.hostapd.8;
> 		to store domain socket files for communication
> 		with external programs such as &man.hostapd.cli.8;.
> 		The default value is used in this example.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-cifacegrp">
> 	      <para>The group allowed to access the control
> 		interface files.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-ssid">
> 	      <para>The wireless network name, or
> 		<acronym>SSID</acronym>, that will appear in wireless
> 		scans.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-wpa">
> 	      <para>Enable
> 		<acronym>WPA</acronym> and specify which
> 		<acronym>WPA</acronym> authentication protocol will
> 		be required.  A value of <literal>2</literal>
> 		configures the <acronym>AP</acronym> for
> 		<acronym>WPA2</acronym> and is recommended.
> 		Set to <literal>1</literal> only if the obsolete
> 		<acronym>WPA</acronym> is required.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-pass">
> 	      <para>ASCII passphrase for
> 		<acronym>WPA</acronym> authentication.</para>
> 
> 	      <warning>
> 		<para>Always use strong passwords that are at least
> 		  8 characters long and made from a rich alphabet so
> 		  that they will not be easily guessed or
> 		  attacked.</para>
> 	      </warning>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-kmgmt">
> 	      <para>The
> 		key management protocol to use.  This example
> 		sets <acronym>WPA-PSK</acronym>.</para>
> 	    </callout>
> 
> 	    <callout arearefs="co-ap-wpapsk-pwise">
> 	      <para>Encryption algorithms accepted by
> 		the access point.  In this example, only
> 		the
> 		<acronym>CCMP</acronym> (<acronym>AES</acronym>)
> 		cipher is accepted.  <acronym>CCMP</acronym>
> 		is an alternative to <acronym>TKIP</acronym>
> 		and is strongly preferred when possible.
> 		<acronym>TKIP</acronym> should be allowed only when
> 		there are stations incapable of using
> 		<acronym>CCMP</acronym>.</para>
> 	    </callout>
> 	  </calloutlist>
> 
> 	  <para>The next step is to start &man.hostapd.8;:</para>
> 
> 	  <screen>&prompt.root; <userinput>service hostapd forcestart</userinput></screen>
> 
> 	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
> wlan0: flags=8943&lt;UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	ether 04:f0:21:16:8e:10
> 	inet6 fe80::6f0:21ff:fe16:8e10%wlan0 prefixlen 64 scopeid 0x9
> 	nd6 options=21&lt;PERFORMNUD,AUTO_LINKLOCAL&gt;
> 	media: IEEE 802.11 Wireless Ethernet autoselect mode 11na &lt;hostap&gt;
> 	status: running
> 	ssid No5ignal channel 36 (5180 MHz 11a ht/40+) bssid 04:f0:21:16:8e:10
> 	country US ecm authmode WPA2/802.11i privacy MIXED deftxkey 2
> 	AES-CCM 2:128-bit AES-CCM 3:128-bit txpower 17 mcastrate 6 mgmtrate 6
> 	scanvalid 60 ampdulimit 64k ampdudensity 8 shortgi wme burst
> 	dtimperiod 1 -dfs
> 	groups: wlan</screen>
> 
> 	  <para>Once the <acronym>AP</acronym> is running, the
> 	    clients can associate with it.  See <xref
> 	      linkend="network-wireless-wpa"/> for more details.  It
> 	    is possible to see the stations associated with the
> 	    <acronym>AP</acronym> using <command>ifconfig
> 	      <replaceable>wlan0</replaceable> list
> 	      sta</command>.</para>
> 	</sect4>
>       </sect3>
> 
>       <sect3>
> 	<title><acronym>WEP</acronym> Host-based Access Point</title>
> 
> 	<para>It is not recommended to use <acronym>WEP</acronym> for
> 	  setting up an <acronym>AP</acronym> since there is no
> 	  authentication mechanism and the encryption is easily
> 	  cracked.  Some legacy wireless cards only support
> 	  <acronym>WEP</acronym> and these cards will only support
> 	  an <acronym>AP</acronym> without authentication or
> 	  encryption.</para>
> 
> 	<para>The wireless device can now be put into hostap mode and
> 	  configured with the correct <acronym>SSID</acronym> and
> 	  <acronym>IP</acronym> address:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \
> 	ssid <replaceable>freebsdap</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable> mode 11g</userinput></screen>
> 
> 	<itemizedlist>
> 	  <listitem>
> 	    <para>The <literal>weptxkey</literal> indicates which
> 	      <acronym>WEP</acronym> key will be used in the
> 	      transmission.  This example uses the third key as key
> 	      numbering starts with <literal>1</literal>.  This
> 	      parameter must be specified in order to encrypt the
> 	      data.</para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para>The <literal>wepkey</literal> sets the selected
> 	      <acronym>WEP</acronym> key.  It should be in the format
> 	      <replaceable>index:key</replaceable>.  If the index is
> 	      not given, key <literal>1</literal> is set.  The index
> 	      needs to be set when using keys other than the first
> 	      key.</para>
> 	  </listitem>
> 	</itemizedlist>
> 
> 	<para>Use &man.ifconfig.8; to see the status of the
> 	  <filename>wlan0</filename> interface:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
>   wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	  ether 00:11:95:c3:0d:ac
> 	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
> 	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;hostap&gt;
> 	  status: running
> 	  ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac
> 	  country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit
> 	  txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs</screen>
> 
> 	<para>From another wireless machine, it is now possible to
> 	  initiate a scan to find the <acronym>AP</acronym>:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput>
> &prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput>
> SSID            BSSID              CHAN RATE  S:N   INT CAPS
> freebsdap       00:11:95:c3:0d:ac    1   54M 22:1   100 EPS</screen>
> 
> 	<para>In this example, the client machine found the
> 	  <acronym>AP</acronym> and can associate with it using the
> 	  correct parameters.  See <xref
> 	    linkend="network-wireless-wep"/> for more details.</para>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Using Both Wired and Wireless Connections</title>
> 
>       <para>A wired connection provides better performance and
> 	reliability, while a wireless connection provides flexibility
> 	and mobility.  Laptop users typically want to roam seamlessly
> 	between the two types of connections.</para>
> 
>       <para>On &os;, it is possible to combine two or even more
> 	network interfaces together in a <quote>failover</quote>
> 	fashion.  This type of configuration uses the most preferred
> 	and available connection from a group of network interfaces,
> 	and the operating system switches automatically when the link
> 	state changes.</para>
> 
>       <para>Link aggregation and failover is covered in <xref
> 	  linkend="network-aggregation"/> and an example for using
> 	both wired and wireless connections is provided at <xref
> 	  linkend="networking-lagg-wired-and-wireless"/>.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Troubleshooting</title>
> 
>       <para>This section describes
> 	a number of steps to help troubleshoot common wireless
> 	networking problems.</para>
> 
>       <itemizedlist>
> 	<listitem>
> 	  <para>If the access point is not listed when scanning,
> 	    check that the configuration has not limited the wireless
> 	    device to a limited set of channels.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para>If the device cannot associate with an access point,
> 	    verify that the configuration matches the settings on the
> 	    access point.  This includes the authentication scheme and
> 	    any security protocols.  Simplify the configuration as
> 	    much as possible.  If using a security protocol such as
> 	    <acronym>WPA</acronym> or <acronym>WEP</acronym>,
> 	    configure the access point for open authentication and
> 	    no security to see if traffic will pass.</para>
> 
> 	  <para>Debugging support is provided by
> 	    &man.wpa.supplicant.8;.  Try running this utility manually
> 	    with <option>-dd</option> and look at the
> 	    system logs.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para>Once the system can associate with the access point,
> 	    diagnose the network configuration using tools like
> 	    &man.ping.8;.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para>There are many lower-level debugging tools.
> 	    Debugging messages can be enabled in the 802.11 protocol
> 	    support layer using &man.wlandebug.8;.
> 	    For example, to enable console messages related to
> 	    scanning for access points and the 802.11 protocol
> 	    handshakes required to arrange communication:</para>
> 
> 	  <screen>&prompt.root; <userinput>wlandebug -i <replaceable>wlan0</replaceable> +scan+auth+debug+assoc</userinput>
>   net.wlan.0.debug: 0 =&gt; 0xc80000&lt;assoc,auth,scan&gt;</screen>
> 
> 	  <para>Many useful statistics are maintained by the 802.11
> 	    layer and <command>wlanstats</command>, found in <filename
> 	      >/usr/src/tools/tools/net80211</filename>,
> 	    will dump this information.  These statistics should
> 	    display all errors identified by the 802.11 layer.
> 	    However, some errors are identified in the device drivers
> 	    that lie below the 802.11 layer so they may not show up.
> 	    To diagnose device-specific problems, refer to the
> 	    drivers' documentation.</para>
> 	</listitem>
>       </itemizedlist>
> 
>       <para>If the above information does not help to clarify the
> 	problem, submit a problem report and include output from the
> 	above tools.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-usb-tethering">
>     <info>
>       <title>USB Tethering</title>
>     </info>
> 
>     <indexterm>
>       <primary>tether</primary>
>     </indexterm>
> 
>     <para>Many cellphones provide the option to share their data
>       connection over USB (often called "tethering").  This feature
>       uses either the <acronym>RNDIS</acronym>, <acronym>CDC</acronym>
>       or a custom &apple; &iphone;/&ipad;
>       protocol.</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para>&android; devices generally use the &man.urndis.4;
> 	  driver.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>&apple; devices use the &man.ipheth.4; driver.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Older devices will often use the &man.cdce.4;
> 	  driver.</para>
>       </listitem>
>     </itemizedlist>
> 
>     <para>Before attaching a device, load the appropriate driver
>       into the kernel:</para>
> 
>     <screen>&prompt.root; <userinput>kldload if_urndis
> &prompt.root; kldload if_cdce
> &prompt.root; kldload if_ipheth</userinput></screen>
> 
>     <para>Once the device is attached
>       <literal>ue</literal><replaceable>0</replaceable> will be
>       available for use like a normal network device.  Be sure that
>       the <quote>USB tethering</quote> option is enabled on the
>       device.</para>
>   </sect1>
> 
>   <sect1 xml:id="network-bluetooth">
>     <info>
>       <title>Bluetooth</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Pav</firstname>
> 	    <surname>Lucistnik</surname>
> 	  </personname>
> 	  <contrib>Written by </contrib>
> 	  <email>pav@FreeBSD.org</email>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm>
>       <primary>Bluetooth</primary>
>     </indexterm>
> 
>     <para>Bluetooth is a wireless technology for creating personal
>       networks operating in the 2.4 GHz unlicensed band, with a
>       range of 10 meters.  Networks are usually formed ad-hoc from
>       portable devices such as cellular phones, handhelds, and
>       laptops.  Unlike Wi-Fi wireless technology, Bluetooth offers
>       higher level service profiles, such as
>       <acronym>FTP</acronym>-like file servers, file pushing, voice
>       transport, serial line emulation, and more.</para>
> 
>     <para>This section describes the use of a <acronym>USB</acronym>
>       Bluetooth dongle on a &os; system.  It then describes the
>       various Bluetooth protocols and utilities.</para>
> 
>     <sect2>
>       <title>Loading Bluetooth Support</title>
> 
>       <para>The Bluetooth stack in &os; is implemented using the
> 	&man.netgraph.4; framework.  A broad variety of Bluetooth
> 	<acronym>USB</acronym> dongles is supported by &man.ng.ubt.4;.
> 	Broadcom BCM2033 based Bluetooth devices are supported by the
> 	&man.ubtbcmfw.4; and &man.ng.ubt.4; drivers.  The 3Com
> 	Bluetooth PC Card 3CRWB60-A is supported by the
> 	&man.ng.bt3c.4; driver.  Serial and UART based Bluetooth
> 	devices are supported by &man.sio.4;, &man.ng.h4.4;, and
> 	&man.hcseriald.8;.</para>
> 
>       <para>Before attaching a device, determine which of the above
> 	drivers it uses, then load the driver.  For example, if the
> 	device uses the &man.ng.ubt.4; driver:</para>
> 
>       <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen>
> 
>       <para>If the Bluetooth device will be attached to the system
> 	during system startup, the system can be configured to load
> 	the module at boot time by adding the driver to
> 	<filename>/boot/loader.conf</filename>:</para>
> 
>       <programlisting>ng_ubt_load="YES"</programlisting>
> 
>       <para>Once the driver is loaded, plug in the
> 	<acronym>USB</acronym> dongle.  If the driver load was
> 	successful, output similar to the following should appear on
> 	the console and in
> 	<filename>/var/log/messages</filename>:</para>
> 
>       <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2
> ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2
> ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
>       wMaxPacketSize=49, nframes=6, buffer size=294</screen>
> 
>       <para>To start and stop the Bluetooth stack, use its startup
> 	script.  It is a good idea to stop the stack before unplugging
> 	the device.  When starting the stack, the output should be
> 	similar to the following:</para>
> 
>       <screen>&prompt.root; <userinput>service bluetooth start ubt0</userinput>
> BD_ADDR: 00:02:72:00:d4:1a
> Features: 0xff 0xff 0xf 00 00 00 00 00
> &lt;3-Slot&gt; &lt;5-Slot&gt; &lt;Encryption&gt; &lt;Slot offset&gt;
> &lt;Timing accuracy&gt; &lt;Switch&gt; &lt;Hold mode&gt; &lt;Sniff mode&gt;
> &lt;Park mode&gt; &lt;RSSI&gt; &lt;Channel quality&gt; &lt;SCO link&gt;
> &lt;HV2 packets&gt; &lt;HV3 packets&gt; &lt;u-law log&gt; &lt;A-law log&gt; &lt;CVSD&gt;
> &lt;Paging scheme&gt; &lt;Power control&gt; &lt;Transparent SCO data&gt;
> Max. ACL packet size: 192 bytes
> Number of ACL packets: 8
> Max. SCO packet size: 64 bytes
> Number of SCO packets: 8</screen>
>     </sect2>
> 
>     <sect2>
>       <title>Finding Other Bluetooth Devices</title>
> 
>       <indexterm>
> 	<primary>HCI</primary>
>       </indexterm>
> 
>       <para>The Host Controller Interface (<acronym>HCI</acronym>)
> 	provides a uniform method for accessing Bluetooth baseband
> 	capabilities.  In &os;, a netgraph <acronym>HCI</acronym> node
> 	is created for each Bluetooth device.  For more details, refer
> 	to &man.ng.hci.4;.</para>
> 
>       <para>One of the most common tasks is discovery of Bluetooth
> 	devices within <acronym>RF</acronym> proximity.  This
> 	operation is called <emphasis>inquiry</emphasis>.  Inquiry and
> 	other <acronym>HCI</acronym> related operations are done using
> 	&man.hccontrol.8;.  The example below shows how to find out
> 	which Bluetooth devices are in range.  The list of devices
> 	should be displayed in a few seconds.  Note that a remote
> 	device will only answer the inquiry if it is set to
> 	<emphasis>discoverable</emphasis> mode.</para>
> 
>       <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput>
> Inquiry result, num_responses=1
> Inquiry result #0
>        BD_ADDR: 00:80:37:29:19:a4
>        Page Scan Rep. Mode: 0x1
>        Page Scan Period Mode: 00
>        Page Scan Mode: 00
>        Class: 52:02:04
>        Clock offset: 0x78ef
> Inquiry complete. Status: No error [00]</screen>
> 
>       <para>The <literal>BD_ADDR</literal> is the unique address of a
> 	Bluetooth device, similar to the <acronym>MAC</acronym>
> 	address of a network card.  This address is needed for further
> 	communication with a device and it is possible to assign a
> 	human readable name to a BD_ADDR.  Information regarding the
> 	known Bluetooth hosts is contained in
> 	<filename>/etc/bluetooth/hosts</filename>.  The following
> 	example shows how to obtain the human readable name that was
> 	assigned to the remote device:</para>
> 
>       <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput>
> BD_ADDR: 00:80:37:29:19:a4
> Name: Pav's T39</screen>
> 
>       <para>If an inquiry is performed on a remote Bluetooth device,
> 	it will find the computer as
> 	<quote>your.host.name (ubt0)</quote>.  The name assigned to
> 	the local device can be changed at any time.</para>
> 
>       <para>The Bluetooth system provides a point-to-point connection
> 	between two Bluetooth units, or a point-to-multipoint
> 	connection which is shared among several Bluetooth devices.
> 	The following example shows how to obtain the list of active
> 	baseband connections for the local device:</para>
> 
>       <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
> Remote BD_ADDR    Handle Type Mode Role Encrypt Pending Queue State
> 00:80:37:29:19:a4     41  ACL    0 MAST    NONE       0     0 OPEN</screen>
> 
>       <para>A <emphasis>connection handle</emphasis> is useful when
> 	termination of the baseband connection is required, though
> 	it is normally not required to do this by hand.  The stack
> 	will automatically terminate inactive baseband
> 	connections.</para>
> 
>       <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput>
> Connection handle: 41
> Reason: Connection terminated by local host [0x16]</screen>
> 
>       <para>Type <command>hccontrol help</command> for a complete
> 	listing of available <acronym>HCI</acronym> commands.  Most
> 	of the <acronym>HCI</acronym> commands do not require
> 	superuser privileges.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Device Pairing</title>
> 
>       <para>By default, Bluetooth communication is not authenticated,
> 	and any device can talk to any other device.  A Bluetooth
> 	device, such as a cellular phone, may choose to require
> 	authentication to provide a particular service.  Bluetooth
> 	authentication is normally done with a
> 	<emphasis><acronym>PIN</acronym> code</emphasis>, an ASCII
> 	string up to 16 characters in length.  The user is required
> 	to enter the same <acronym>PIN</acronym> code on both devices.
> 	Once the user has entered the <acronym>PIN</acronym> code,
> 	both devices will generate a <emphasis>link key</emphasis>.
> 	After that, the link key can be stored either in the devices
> 	or in a persistent storage.  Next time, both devices will
> 	use the previously generated link key.  This procedure is
> 	called <emphasis>pairing</emphasis>.  Note that if the link
> 	key is lost by either device, the pairing must be
> 	repeated.</para>
> 
>       <para>The &man.hcsecd.8; daemon is responsible for handling
> 	Bluetooth authentication requests.  The default configuration
> 	file is <filename>/etc/bluetooth/hcsecd.conf</filename>.  An
> 	example section for a cellular phone with the
> 	<acronym>PIN</acronym> code set to <literal>1234</literal> is
> 	shown below:</para>
> 
>       <programlisting>device {
>         bdaddr  00:80:37:29:19:a4;
>         name    "Pav's T39";
>         key     nokey;
>         pin     "1234";
>       }</programlisting>
> 
>       <para>The only limitation on <acronym>PIN</acronym> codes is
> 	length.  Some devices, such as Bluetooth headsets, may have
> 	a fixed <acronym>PIN</acronym> code built in.  The
> 	<option>-d</option> switch forces &man.hcsecd.8; to stay in
> 	the foreground, so it is easy to see what is happening.  Set
> 	the remote device to receive pairing and initiate the
> 	Bluetooth connection to the remote device.  The remote device
> 	should indicate that pairing was accepted and request the
> 	<acronym>PIN</acronym> code.  Enter the same
> 	<acronym>PIN</acronym> code listed in
> 	<filename>hcsecd.conf</filename>.  Now the computer and the
> 	remote device are paired.  Alternatively, pairing can be
> 	initiated on the remote device.</para>
> 
>       <para>The following line can be added to
> 	<filename>/etc/rc.conf</filename> to configure &man.hcsecd.8;
> 	to start automatically on system start:</para>
> 
>       <programlisting>hcsecd_enable="YES"</programlisting>
> 
>       <para>The following is a sample of the &man.hcsecd.8; daemon
> 	output:</para>
> 
>       <programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
> hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist
> hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4
> hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4
> hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists
> hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting>
>     </sect2>
> 
>     <sect2>
>       <title>Network Access with
> 	<acronym>PPP</acronym> Profiles</title>
> 
>       <para>A Dial-Up Networking (<acronym>DUN</acronym>) profile can
> 	be used to configure a cellular phone as a wireless modem for
> 	connecting to a dial-up Internet access server.  It can also
> 	be used to configure a computer to receive data calls from a
> 	cellular phone.</para>
> 
>       <para>Network access with a <acronym>PPP</acronym> profile can
> 	be used to provide <acronym>LAN</acronym> access for a single
> 	Bluetooth device or multiple Bluetooth devices.  It can also
> 	provide <acronym>PC</acronym> to <acronym>PC</acronym>
> 	connection using <acronym>PPP</acronym> networking over serial
> 	cable emulation.</para>
> 
>       <para>In &os;, these profiles are implemented with &man.ppp.8;
> 	and the &man.rfcomm.pppd.8; wrapper which converts a
> 	Bluetooth connection into something
> 	<acronym>PPP</acronym> can use.  Before a profile can be used,
> 	a new <acronym>PPP</acronym> label must be created in
> 	<filename>/etc/ppp/ppp.conf</filename>.  Consult
> 	&man.rfcomm.pppd.8; for examples.</para>
> 
>       <para>In this example, &man.rfcomm.pppd.8; is used to open a
> 	connection to a remote device with a
> 	<literal>BD_ADDR</literal> of
> 	<literal>00:80:37:29:19:a4</literal> on a
> 	<acronym>DUN</acronym> <acronym>RFCOMM</acronym>
> 	channel:</para>
> 
>       <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen>
> 
>       <para>The actual channel number will be obtained from the remote
> 	device using the <acronym>SDP</acronym> protocol.  It is
> 	possible to specify the <acronym>RFCOMM</acronym> channel by
> 	hand, and in this case &man.rfcomm.pppd.8; will not perform
> 	the <acronym>SDP</acronym> query.  Use &man.sdpcontrol.8; to
> 	find out the <acronym>RFCOMM</acronym> channel on the remote
> 	device.</para>
> 
>       <para>In order to provide network access with the
> 	<acronym>PPP</acronym> <acronym>LAN</acronym> service,
> 	&man.sdpd.8; must be running and a new entry for
> 	<acronym>LAN</acronym> clients must be created in
> 	<filename>/etc/ppp/ppp.conf</filename>.  Consult
> 	&man.rfcomm.pppd.8; for examples.  Finally, start the
> 	<acronym>RFCOMM</acronym> <acronym>PPP</acronym> server on a
> 	valid <acronym>RFCOMM</acronym> channel number.  The
> 	<acronym>RFCOMM</acronym> <acronym>PPP</acronym> server will
> 	automatically register the Bluetooth <acronym>LAN</acronym>
> 	service with the local <acronym>SDP</acronym> daemon.  The
> 	example below shows how to start the <acronym>RFCOMM</acronym>
> 	<acronym>PPP</acronym> server.</para>
> 
>       <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen>
>     </sect2>
> 
>     <sect2>
>       <title>Bluetooth Protocols</title>
> 
>       <para>This section provides an overview of the various Bluetooth
> 	protocols, their function, and associated utilities.</para>
> 
>       <sect3>
> 	<title>Logical Link Control and Adaptation Protocol
> 	  (<acronym>L2CAP</acronym>)</title>
> 
> 	<indexterm>
> 	  <primary>L2CAP</primary>
> 	</indexterm>
> 
> 	<para>The Logical Link Control and Adaptation Protocol
> 	  (<acronym>L2CAP</acronym>) provides connection-oriented and
> 	  connectionless data services to upper layer protocols.
> 	  <acronym>L2CAP</acronym> permits higher level protocols and
> 	  applications to transmit and receive
> 	  <acronym>L2CAP</acronym> data packets up to 64 kilobytes in
> 	  length.</para>
> 
> 	<para><acronym>L2CAP</acronym> is based around the concept of
> 	  <emphasis>channels</emphasis>.  A channel is a logical
> 	  connection on top of a baseband connection, where each
> 	  channel is bound to a single protocol in a many-to-one
> 	  fashion.  Multiple channels can be bound to the same
> 	  protocol, but a channel cannot be bound to multiple
> 	  protocols.  Each <acronym>L2CAP</acronym> packet received on
> 	  a channel is directed to the appropriate higher level
> 	  protocol.  Multiple channels can share the same baseband
> 	  connection.</para>
> 
> 	<para>In &os;, a netgraph <acronym>L2CAP</acronym> node is
> 	  created for each Bluetooth device.  This node is normally
> 	  connected to the downstream Bluetooth <acronym>HCI</acronym>
> 	  node and upstream Bluetooth socket nodes.  The default name
> 	  for the <acronym>L2CAP</acronym> node is
> 	  <quote>devicel2cap</quote>.  For more details refer to
> 	  &man.ng.l2cap.4;.</para>
> 
> 	<para>A useful command is &man.l2ping.8;, which can be used to
> 	  ping other devices.  Some Bluetooth implementations might
> 	  not return all of the data sent to them, so <literal>0
> 	    bytes</literal> in the following example is normal.</para>
> 
> 	<screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput>
> 0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0
> 0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0
> 0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0
> 0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen>
> 
> 	<para>The &man.l2control.8; utility is used to perform various
> 	  operations on <acronym>L2CAP</acronym> nodes.  This example
> 	  shows how to obtain the list of logical connections
> 	  (channels) and the list of baseband connections for the
> 	  local device:</para>
> 
> 	<screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput>
> L2CAP channels:
> Remote BD_ADDR     SCID/ DCID   PSM  IMTU/ OMTU State
> 00:07:e0:00:0b:ca    66/   64     3   132/  672 OPEN
> &prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput>
> L2CAP connections:
> Remote BD_ADDR    Handle Flags Pending State
> 00:07:e0:00:0b:ca     41 O           0 OPEN</screen>
> 
> 	<para>Another diagnostic tool is &man.btsockstat.1;.  It is
> 	  similar to &man.netstat.1;, but for Bluetooth
> 	  network-related data structures.  The example below shows
> 	  the same logical connection as &man.l2control.8;
> 	  above.</para>
> 
> 	<screen>&prompt.user; <userinput>btsockstat</userinput>
> Active L2CAP sockets
> PCB      Recv-Q Send-Q Local address/PSM       Foreign address   CID   State
> c2afe900      0      0 00:02:72:00:d4:1a/3     00:07:e0:00:0b:ca 66    OPEN
> Active RFCOMM sessions
> L2PCB    PCB      Flag MTU   Out-Q DLCs State
> c2afe900 c2b53380 1    127   0     Yes  OPEN
> Active RFCOMM sockets
> PCB      Recv-Q Send-Q Local address     Foreign address   Chan DLCI State
> c2e8bc80      0    250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3    6    OPEN</screen>
>       </sect3>
> 
>       <sect3>
> 	<title>Radio Frequency Communication
> 	  (<acronym>RFCOMM</acronym>)</title>
> 
> 	<para>The <acronym>RFCOMM</acronym> protocol provides
> 	  emulation of serial ports over the <acronym>L2CAP</acronym>
> 	  protocol.  <acronym>RFCOMM</acronym> is a simple transport
> 	  protocol, with additional provisions for emulating the 9
> 	  circuits of RS-232 (EIATIA-232-E) serial ports.  It
> 	  supports up to 60 simultaneous connections
> 	  (<acronym>RFCOMM</acronym> channels) between two Bluetooth
> 	  devices.</para>
> 
> 	<para>For the purposes of <acronym>RFCOMM</acronym>, a
> 	  complete communication path involves two applications
> 	  running on the communication endpoints with a communication
> 	  segment between them.  <acronym>RFCOMM</acronym> is intended
> 	  to cover applications that make use of the serial ports of
> 	  the devices in which they reside.  The communication segment
> 	  is a direct connect Bluetooth link from one device to
> 	  another.</para>
> 
> 	<para><acronym>RFCOMM</acronym> is only concerned with the
> 	  connection between the devices in the direct connect case,
> 	  or between the device and a modem in the network case.
> 	  <acronym>RFCOMM</acronym> can support other configurations,
> 	  such as modules that communicate via Bluetooth wireless
> 	  technology on one side and provide a wired interface on the
> 	  other side.</para>
> 
> 	<para>In &os;, <acronym>RFCOMM</acronym> is implemented at the
> 	  Bluetooth sockets layer.</para>
>       </sect3>
> 
>       <sect3>
> 	<title>Service Discovery Protocol
> 	  (<acronym>SDP</acronym>)</title>
> 
> 	<indexterm>
> 	  <primary>SDP</primary>
> 	</indexterm>
> 
> 	<para>The Service Discovery Protocol (<acronym>SDP</acronym>)
> 	  provides the means for client applications to discover the
> 	  existence of services provided by server applications as
> 	  well as the attributes of those services.  The attributes of
> 	  a service include the type or class of service offered and
> 	  the mechanism or protocol information needed to utilize the
> 	  service.</para>
> 
> 	<para><acronym>SDP</acronym> involves communication between a
> 	  <acronym>SDP</acronym> server and a <acronym>SDP</acronym>
> 	  client.  The server maintains a list of service records that
> 	  describe the characteristics of services associated with the
> 	  server.  Each service record contains information about a
> 	  single service.  A client may retrieve information from a
> 	  service record maintained by the <acronym>SDP</acronym>
> 	  server by issuing a <acronym>SDP</acronym> request.  If the
> 	  client, or an application associated with the client,
> 	  decides to use a service, it must open a separate connection
> 	  to the service provider in order to utilize the service.
> 	  <acronym>SDP</acronym> provides a mechanism for discovering
> 	  services and their attributes, but it does not provide a
> 	  mechanism for utilizing those services.</para>
> 
> 	<para>Normally, a <acronym>SDP</acronym> client searches for
> 	  services based on some desired characteristics of the
> 	  services.  However, there are times when it is desirable to
> 	  discover which types of services are described by an
> 	  <acronym>SDP</acronym> server's service records without any
> 	  prior information about the services.  This process of
> 	  looking for any offered services is called
> 	  <emphasis>browsing</emphasis>.</para>
> 
> 	<para>The Bluetooth <acronym>SDP</acronym> server,
> 	  &man.sdpd.8;, and command line client, &man.sdpcontrol.8;,
> 	  are included in the standard &os; installation.  The
> 	  following example shows how to perform a
> 	  <acronym>SDP</acronym> browse query.</para>
> 
> 	<screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput>
> Record Handle: 00000000
> Service Class ID List:
>         Service Discovery Server (0x1000)
> Protocol Descriptor List:
>         L2CAP (0x0100)
>                 Protocol specific parameter #1: u/int/uuid16 1
>                 Protocol specific parameter #2: u/int/uuid16 1
> 
> Record Handle: 0x00000001
> Service Class ID List:
>         Browse Group Descriptor (0x1001)
> 
> Record Handle: 0x00000002
> Service Class ID List:
>         LAN Access Using PPP (0x1102)
> Protocol Descriptor List:
>         L2CAP (0x0100)
>         RFCOMM (0x0003)
>                 Protocol specific parameter #1: u/int8/bool 1
> Bluetooth Profile Descriptor List:
>         LAN Access Using PPP (0x1102) ver. 1.0</screen>
> 
> 	<para>Note that each service has a list of attributes, such
> 	  as the <acronym>RFCOMM</acronym> channel.  Depending on the
> 	  service, the user might need to make note of some of the
> 	  attributes.  Some Bluetooth implementations do not support
> 	  service browsing and may return an empty list.  In this
> 	  case, it is possible to search for the specific service.
> 	  The example below shows how to search for the
> 	  <acronym>OBEX</acronym> Object Push
> 	  (<acronym>OPUSH</acronym>) service:</para>
> 
> 	<screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen>
> 
> 	<para>Offering services on &os; to Bluetooth clients is done
> 	  with the &man.sdpd.8; server.  The following line can be
> 	  added to <filename>/etc/rc.conf</filename>:</para>
> 
> 	<programlisting>sdpd_enable="YES"</programlisting>
> 
> 	<para>Then the &man.sdpd.8; daemon can be started with:</para>
> 
> 	<screen>&prompt.root; <userinput>service sdpd start</userinput></screen>
> 
> 	<para>The local server application that wants to provide a
> 	  Bluetooth service to remote clients will register the
> 	  service with the local <acronym>SDP</acronym> daemon.  An
> 	  example of such an application is &man.rfcomm.pppd.8;.  Once
> 	  started, it will register the Bluetooth LAN service with the
> 	  local <acronym>SDP</acronym> daemon.</para>
> 
> 	<para>The list of services registered with the local
> 	  <acronym>SDP</acronym> server can be obtained by issuing a
> 	  <acronym>SDP</acronym> browse query via the local control
> 	  channel:</para>
> 
> 	<screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen>
>       </sect3>
> 
>       <sect3>
> 	<title><acronym>OBEX</acronym> Object Push
> 	  (<acronym>OPUSH</acronym>)</title>
> 
> 	<indexterm>
> 	  <primary>OBEX</primary>
> 	</indexterm>
> 
> 	<para>Object Exchange (<acronym>OBEX</acronym>) is a widely
> 	  used protocol for simple file transfers between mobile
> 	  devices.  Its main use is in infrared communication, where
> 	  it is used for generic file transfers between notebooks or
> 	  <acronym>PDA</acronym>s, and for sending business cards or
> 	  calendar entries between cellular phones and other devices
> 	  with Personal Information Manager (<acronym>PIM</acronym>)
> 	  applications.</para>
> 
> 	<para>The <acronym>OBEX</acronym> server and client are
> 	  implemented by <application>obexapp</application>, which can
> 	  be installed using the <package>comms/obexapp</package>
> 	  package or port.</para>
> 
> 	<para>The <acronym>OBEX</acronym> client is used to push
> 	  and/or pull objects from the <acronym>OBEX</acronym> server.
> 	  An example object is a business card or an appointment.
> 	  The <acronym>OBEX</acronym> client can obtain the
> 	  <acronym>RFCOMM</acronym> channel number from the remote
> 	  device via <acronym>SDP</acronym>.  This can be done by
> 	  specifying the service name instead of the
> 	  <acronym>RFCOMM</acronym> channel number.  Supported service
> 	  names are: <literal>IrMC</literal>, <literal>FTRN</literal>,
> 	  and <literal>OPUSH</literal>.  It is also possible to
> 	  specify the <acronym>RFCOMM</acronym> channel as a number.
> 	  Below is an example of an <acronym>OBEX</acronym> session
> 	  where the device information object is pulled from the
> 	  cellular phone, and a new object, the business card, is
> 	  pushed into the phone's directory.</para>
> 
> 	<screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput>
> obex&gt; get telecom/devinfo.txt devinfo-t39.txt
> Success, response: OK, Success (0x20)
> obex&gt; put new.vcf
> Success, response: OK, Success (0x20)
> obex&gt; di
> Success, response: OK, Success (0x20)</screen>
> 
> 	<para>In order to provide the <acronym>OPUSH</acronym>
> 	  service, &man.sdpd.8; must be running and a root folder,
> 	  where all incoming objects will be stored, must be created.
> 	  The default path to the root folder is
> 	  <filename>/var/spool/obex</filename>.  Finally, start the
> 	  <acronym>OBEX</acronym> server on a valid
> 	  <acronym>RFCOMM</acronym> channel number.  The
> 	  <acronym>OBEX</acronym> server will automatically register
> 	  the <acronym>OPUSH</acronym> service with the local
> 	  <acronym>SDP</acronym> daemon.  The example below shows how
> 	  to start the <acronym>OBEX</acronym> server.</para>
> 
> 	<screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen>
>       </sect3>
> 
>       <sect3>
> 	<title>Serial Port Profile (<acronym>SPP</acronym>)</title>
> 
> 	<para>The Serial Port Profile (<acronym>SPP</acronym>) allows
> 	  Bluetooth devices to perform serial cable emulation.  This
> 	  profile allows legacy applications to use Bluetooth as a
> 	  cable replacement, through a virtual serial port
> 	  abstraction.</para>
> 
> 	<para>In &os;, &man.rfcomm.sppd.1; implements
> 	  <acronym>SPP</acronym> and a pseudo tty is used as a virtual
> 	  serial port abstraction.  The example below shows how to
> 	  connect to a remote device's serial port service.  A
> 	  <acronym>RFCOMM</acronym> channel does not have to be
> 	  specified as &man.rfcomm.sppd.1; can obtain it from the
> 	  remote device via <acronym>SDP</acronym>.  To override this,
> 	  specify a <acronym>RFCOMM</acronym> channel on the command
> 	  line.</para>
> 
> 	<screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -t</userinput>
> rfcomm_sppd[94692]: Starting on /dev/pts/6...
> /dev/pts/6</screen>
> 
> 	<para>Once connected, the pseudo tty can be used as serial
> 	  port:</para>
> 
> 	<screen>&prompt.root; <userinput>cu -l /dev/pts/6</userinput></screen>
> 
> 	<para>The pseudo tty is printed on stdout and can be read by
> 	  wrapper scripts:</para>
> 
> 	<programlisting>PTS=`rfcomm_sppd -a 00:07:E0:00:0B:CA -t`
> cu -l $PTS</programlisting>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Troubleshooting</title>
> 
>       <para>By default, when &os; is accepting a new connection, it
> 	tries to perform a role switch and become master.  Some older
> 	Bluetooth devices which do not support role switching will not
> 	be able to connect.  Since role switching is performed when a
> 	new connection is being established, it is not possible to ask
> 	the remote device if it supports role switching.  However,
> 	there is a <acronym>HCI</acronym> option to disable role
> 	switching on the local side:</para>
> 
>       <screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen>
> 
>       <para>To display Bluetooth packets, use the third-party package
> 	<application>hcidump</application>, which can be installed
> 	using the <package>comms/hcidump</package> package or port.
> 	This utility is similar to &man.tcpdump.1; and can be used to
> 	display the contents of Bluetooth packets on the terminal and
> 	to dump the Bluetooth packets to a file.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-bridging">
>     <info>
>       <title>Bridging</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Andrew</firstname>
> 	    <surname>Thompson</surname>
> 	  </personname>
> 	  <contrib>Written by </contrib>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm>
>       <primary><acronym>IP</acronym> subnet</primary>
>     </indexterm>
>     <indexterm>
>       <primary>bridge</primary>
>     </indexterm>
> 
>     <para>It is sometimes useful to divide a network, such as an
>       Ethernet segment, into network segments without having to
>       create <acronym>IP</acronym> subnets and use a router to connect
>       the segments together.  A device that connects two networks
>       together in this fashion is called a
>       <quote>bridge</quote>.</para>
> 
>     <para>A bridge works by learning the <acronym>MAC</acronym>
>       addresses of the devices on each of its network interfaces.  It
>       forwards traffic between networks only when the source and
>       destination <acronym>MAC</acronym> addresses are on different
>       networks.  In many respects, a bridge is like an Ethernet switch
>       with very few ports.    A &os; system with multiple network
>       interfaces can be configured to act as a bridge.</para>
> 
>     <para>Bridging can be useful in the following situations:</para>
> 
>     <variablelist>
>       <varlistentry>
> 	<term>Connecting Networks</term>
> 	<listitem>
> 	  <para>The basic operation of a bridge is to join two or more
> 	    network segments.  There are many reasons to use a
> 	    host-based bridge instead of networking equipment, such as
> 	    cabling constraints or firewalling.  A bridge can also
> 	    connect a wireless interface running in hostap mode to a
> 	    wired network and act as an access point.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term>Filtering/Traffic Shaping Firewall</term>
> 	<listitem>
> 	  <para>A bridge can be used when firewall functionality is
> 	    needed without routing or Network Address Translation
> 	    (<acronym>NAT</acronym>).</para>
> 
> 	  <para>An example is a small company that is connected via
> 	    <acronym>DSL</acronym> or <acronym>ISDN</acronym> to an
> 	    <acronym>ISP</acronym>.  There are thirteen public
> 	    <acronym>IP</acronym> addresses from the
> 	    <acronym>ISP</acronym> and ten computers on the network.
> 	    In this situation, using a router-based firewall is
> 	    difficult because of subnetting issues.  A bridge-based
> 	    firewall can be configured without any
> 	    <acronym>IP</acronym> addressing issues.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term>Network Tap</term>
> 	<listitem>
> 	  <para>A bridge can join two network segments in order to
> 	    inspect all Ethernet frames that pass between them using
> 	    &man.bpf.4; and &man.tcpdump.1; on the bridge interface or
> 	    by sending a copy of all frames out an additional
> 	    interface known as a span port.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term>Layer 2 <acronym>VPN</acronym></term>
> 	<listitem>
> 	  <para>Two Ethernet networks can be joined across an
> 	    <acronym>IP</acronym> link by bridging the networks to an
> 	    EtherIP tunnel or a &man.tap.4; based solution such as
> 	    <application>OpenVPN</application>.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term>Layer 2 Redundancy</term>
> 	<listitem>
> 	  <para>A network can be connected together with multiple
> 	    links and use the Spanning Tree Protocol
> 	    (<acronym>STP</acronym>) to block redundant paths.</para>
> 	</listitem>
>       </varlistentry>
>     </variablelist>
> 
>     <para>This section describes how to configure a &os; system as a
>       bridge using &man.if.bridge.4;.  A netgraph bridging driver is
>       also available, and is described in &man.ng.bridge.4;.</para>
> 
>     <note>
>       <para>Packet filtering can be used with any firewall package
> 	that hooks into the &man.pfil.9; framework.  The bridge can be
> 	used as a traffic shaper with &man.altq.4; or
> 	&man.dummynet.4;.</para>
>     </note>
> 
>     <sect2>
>       <title>Enabling the Bridge</title>
> 
>       <para>In &os;, &man.if.bridge.4; is a kernel module which is
> 	automatically loaded by &man.ifconfig.8; when creating a
> 	bridge interface.  It is also possible to compile bridge
> 	support into a custom kernel by adding
> 	<literal>device if_bridge</literal> to the custom kernel
> 	configuration file.</para>
> 
>       <para>The bridge is created using interface cloning.  To create
> 	the bridge interface:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig bridge create</userinput>
> bridge0
> &prompt.root; <userinput>ifconfig bridge0</userinput>
> bridge0: flags=8802&lt;BROADCAST,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
>         ether 96:3d:4b:f1:79:7a
>         id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15
>         maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
>         root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0</screen>
> 
>       <para>When a bridge interface is created, it is automatically
> 	assigned a randomly generated Ethernet address.  The
> 	<literal>maxaddr</literal> and <literal>timeout</literal>
> 	parameters control how many <acronym>MAC</acronym> addresses
> 	the bridge will keep in its forwarding table and how many
> 	seconds before each entry is removed after it is last seen.
> 	The other parameters control how <acronym>STP</acronym>
> 	operates.</para>
> 
>       <para>Next, specify which network interfaces to add as members
> 	of the bridge.  For the bridge to forward packets, all member
> 	interfaces and the bridge need to be up:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 up</userinput>
> &prompt.root; <userinput>ifconfig fxp0 up</userinput>
> &prompt.root; <userinput>ifconfig fxp1 up</userinput></screen>
> 
>       <para>The bridge can now forward Ethernet frames between
> 	<filename>fxp0</filename> and <filename>fxp1</filename>.  Add
> 	the following lines to <filename>/etc/rc.conf</filename> so
> 	the bridge is created at startup:</para>
> 
>       <programlisting>cloned_interfaces="bridge0"
> ifconfig_bridge0="addm fxp0 addm fxp1 up"
> ifconfig_fxp0="up"
> ifconfig_fxp1="up"</programlisting>
> 
>       <para>If the bridge host needs an <acronym>IP</acronym>
> 	address, set it on the bridge interface, not on the member
> 	interfaces.  The address can be set statically or via
> 	<acronym>DHCP</acronym>.  This example sets a static
> 	<acronym>IP</acronym> address:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>
> 
>       <para>It is also possible to assign an <acronym>IPv6</acronym>
> 	address to a bridge interface.  To make the changes permanent,
> 	add the addressing information to
> 	<filename>/etc/rc.conf</filename>.</para>
> 
>       <note>
> 	<para>When packet filtering is enabled, bridged packets will
> 	  pass through the filter inbound on the originating interface
> 	  on the bridge interface, and outbound on the appropriate
> 	  interfaces.  Either stage can be disabled.  When direction
> 	  of the packet flow is important, it is best to firewall on
> 	  the member interfaces rather than the bridge itself.</para>
> 
> 	<para>The bridge has several configurable settings for passing
> 	  non-<acronym>IP</acronym> and <acronym>IP</acronym> packets,
> 	  and layer2 firewalling with &man.ipfw.8;.  See
> 	  &man.if.bridge.4; for more information.</para>
>       </note>
>     </sect2>
> 
>     <sect2>
>       <title>Enabling Spanning Tree</title>
> 
>       <para>For an Ethernet network to function properly, only one
> 	active path can exist between two devices.  The
> 	<acronym>STP</acronym> protocol detects loops and puts
> 	redundant links into a blocked state.  Should one of the
> 	active links fail, <acronym>STP</acronym> calculates a
> 	different tree and enables one of the blocked paths to restore
> 	connectivity to all points in the network.</para>
> 
>       <para>The Rapid Spanning Tree Protocol (<acronym>RSTP</acronym>
> 	or 802.1w) provides backwards compatibility with legacy
> 	<acronym>STP</acronym>.  <acronym>RSTP</acronym> provides
> 	faster convergence and exchanges information with neighboring
> 	switches to quickly transition to forwarding mode without
> 	creating loops.  &os; supports <acronym>RSTP</acronym> and
> 	<acronym>STP</acronym> as operating modes, with
> 	<acronym>RSTP</acronym> being the default mode.</para>
> 
>       <para><acronym>STP</acronym> can be enabled on member interfaces
> 	using &man.ifconfig.8;.  For a bridge with
> 	<filename>fxp0</filename> and <filename>fxp1</filename> as the
> 	current interfaces, enable <acronym>STP</acronym> with:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput>
> bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
>         ether d6:cf:d5:a0:94:6d
>         id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15
>         maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
>         root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0
>         member: fxp0 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
>                 port 3 priority 128 path cost 200000 proto rstp
>                 role designated state forwarding
>         member: fxp1 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
>                 port 4 priority 128 path cost 200000 proto rstp
>                 role designated state forwarding</screen>
> 
>       <para>This bridge has a spanning tree ID of
> 	<literal>00:01:02:4b:d4:50</literal> and a priority of
> 	<literal>32768</literal>.  As the <literal>root id</literal>
> 	is the same, it indicates that this is the root bridge for the
> 	tree.</para>
> 
>       <para>Another bridge on the network also has
> 	<acronym>STP</acronym> enabled:</para>
> 
>       <screen>bridge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
>         ether 96:3d:4b:f1:79:7a
>         id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15
>         maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200
>         root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4
>         member: fxp0 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
>                 port 4 priority 128 path cost 200000 proto rstp
>                 role root state forwarding
>         member: fxp1 flags=1c7&lt;LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP&gt;
>                 port 5 priority 128 path cost 200000 proto rstp
>                 role designated state forwarding</screen>
> 
>       <para>The line <literal>root id 00:01:02:4b:d4:50 priority 32768
> 	  ifcost 400000 port 4</literal> shows that the root bridge is
> 	<literal>00:01:02:4b:d4:50</literal> and has a path cost of
> 	<literal>400000</literal> from this bridge.  The path to the
> 	root bridge is via <literal>port 4</literal> which is
> 	<filename>fxp0</filename>.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Bridge Interface Parameters</title>
> 
>       <para>Several <command>ifconfig</command> parameters are unique
> 	to bridge interfaces.  This section summarizes some common
> 	uses for these parameters.  The complete list of available
> 	parameters is described in &man.ifconfig.8;.</para>
> 
>       <variablelist>
> 	<varlistentry>
> 	  <term>private</term>
> 	  <listitem>
> 	    <para>A private interface does not forward any traffic to
> 	      any other port that is also designated as a private
> 	      interface.  The traffic is blocked unconditionally so no
> 	      Ethernet frames will be forwarded, including
> 	      <acronym>ARP</acronym> packets.  If traffic needs to be
> 	      selectively blocked, a firewall should be used
> 	      instead.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>span</term>
> 	  <listitem>
> 	    <para>A span port transmits a copy of every Ethernet frame
> 	      received by the bridge.  The number of span ports
> 	      configured on a bridge is unlimited, but if an
> 	      interface is designated as a span port, it cannot also
> 	      be used as a regular bridge port.  This is most useful
> 	      for snooping a bridged network passively on another host
> 	      connected to one of the span ports of the bridge.  For
> 	      example, to send a copy of all frames out the interface
> 	      named <filename>fxp4</filename>:</para>
> 
> 	    <screen>&prompt.root; <userinput>ifconfig bridge0 span fxp4</userinput></screen>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>sticky</term>
> 	  <listitem>
> 	    <para>If a bridge member interface is marked as sticky,
> 	      dynamically learned address entries are treated as
> 	      static entries in the forwarding cache.  Sticky entries
> 	      are never aged out of the cache or replaced, even if the
> 	      address is seen on a different interface.  This gives
> 	      the benefit of static address entries without the need
> 	      to pre-populate the forwarding table.  Clients learned
> 	      on a particular segment of the bridge cannot roam to
> 	      another segment.</para>
> 
> 	    <para>An example of using sticky addresses is to combine
> 	      the bridge with <acronym>VLAN</acronym>s in order to
> 	      isolate customer networks without wasting
> 	      <acronym>IP</acronym> address space.  Consider that
> 	      <systemitem class="fqdomainname">CustomerA</systemitem>
> 	      is on <literal>vlan100</literal>, <systemitem
> 		class="fqdomainname">CustomerB</systemitem> is on
> 	      <literal>vlan101</literal>, and the bridge has the
> 	      address <systemitem
> 		class="ipaddress">192.168.0.1</systemitem>:</para>
> 
> 	    <screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput>
> &prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen>
> 
> 	    <para>In this example, both clients see <systemitem
> 		class="ipaddress">192.168.0.1</systemitem> as their
> 	      default gateway.  Since the bridge cache is sticky, one
> 	      host cannot spoof the <acronym>MAC</acronym> address of
> 	      the other customer in order to intercept their
> 	      traffic.</para>
> 
> 	    <para>Any communication between the
> 	      <acronym>VLAN</acronym>s can be blocked using a firewall
> 	      or, as seen in this example, private interfaces:</para>
> 
> 	    <screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen>
> 
> 	    <para>The customers are completely isolated from each
> 	      other and the full <systemitem
> 		class="netmask">/24</systemitem> address range can be
> 	      allocated without subnetting.</para>
> 
> 	    <para>The number of unique source <acronym>MAC</acronym>
> 	      addresses behind an interface can be limited.  Once the
> 	      limit is reached, packets with unknown source addresses
> 	      are dropped until an existing host cache entry expires
> 	      or is removed.</para>
> 
> 	    <para>The following example sets the maximum number of
> 	      Ethernet devices for <systemitem
> 		class="fqdomainname">CustomerA</systemitem> on
> 	      <literal>vlan100</literal> to 10:</para>
> 
> 	    <screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen>
> 	  </listitem>
> 	</varlistentry>
>       </variablelist>
> 
>       <para>Bridge interfaces also support monitor mode, where the
> 	packets are discarded after &man.bpf.4; processing and are not
> 	processed or forwarded further.  This can be used to
> 	multiplex the input of two or more interfaces into a single
> 	&man.bpf.4; stream.  This is useful for reconstructing the
> 	traffic for network taps that transmit the RX/TX signals out
> 	through two separate interfaces.  For example, to read the
> 	input from four network interfaces as one stream:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up</userinput>
> &prompt.root; <userinput>tcpdump -i bridge0</userinput></screen>
>     </sect2>
> 
>     <sect2>
>       <title><acronym>SNMP</acronym> Monitoring</title>
> 
>       <para>The bridge interface and <acronym>STP</acronym>
> 	parameters can be monitored via &man.bsnmpd.1; which is
> 	included in the &os; base system.  The exported bridge
> 	<acronym>MIB</acronym>s conform to <acronym>IETF</acronym>
> 	standards so any <acronym>SNMP</acronym> client or monitoring
> 	package can be used to retrieve the data.</para>
> 
>       <para>To enable monitoring on the bridge, uncomment this line in
> 	<filename>/etc/snmpd.config</filename> by removing the
> 	beginning <literal>#</literal> symbol:</para>
> 
>       <programlisting>begemotSnmpdModulePath."bridge" = "/usr/lib/snmp_bridge.so"</programlisting>
> 
>       <para>Other configuration settings, such as community names and
> 	access lists, may need to be modified in this file.  See
> 	&man.bsnmpd.1; and &man.snmp.bridge.3; for more information.
> 	Once these edits are saved, add this line to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>bsnmpd_enable="YES"</programlisting>
> 
>       <para>Then, start  &man.bsnmpd.1;:</para>
> 
>       <screen>&prompt.root; <userinput>service bsnmpd start</userinput></screen>
> 
>       <para>The following examples use the
> 	<application>Net-SNMP</application> software
> 	(<package>net-mgmt/net-snmp</package>) to query a bridge
> 	from a client system.  The
> 	<package>net-mgmt/bsnmptools</package> port can also be used.
> 	From the <acronym>SNMP</acronym> client which is running
> 	<application>Net-SNMP</application>, add the following lines
> 	to <filename>$HOME/.snmp/snmp.conf</filename> in order to
> 	import the bridge <acronym>MIB</acronym> definitions:</para>
> 
>       <programlisting>mibdirs +/usr/share/snmp/mibs
> mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB</programlisting>
> 
>       <para>To monitor a single bridge using the IETF BRIDGE-MIB
> 	(RFC4188):</para>
> 
>       <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge</userinput>
> BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44
> BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports
> BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds
> BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2
> BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50
> ...
> BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5)
> BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1)
> BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000
> BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
> BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0
> BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50
> BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80
> BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1
> RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)</screen>
> 
>       <para>The <literal>dot1dStpTopChanges.0</literal> value is two,
> 	indicating that the <acronym>STP</acronym> bridge topology has
> 	changed twice.  A topology change means that one or more links
> 	in the network have changed or failed and a new tree has been
> 	calculated.  The
> 	<literal>dot1dStpTimeSinceTopologyChange.0</literal> value
> 	will show when this happened.</para>
> 
>       <para>To monitor multiple bridge interfaces, the private
> 	BEGEMOT-BRIDGE-MIB can be used:</para>
> 
>       <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com</userinput>
> enterprises.fokus.begemot.begemotBridge
> BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0
> BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2
> BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13
> BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc
> BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1
> BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1
> ...
> BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds
> BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds
> BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1
> BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1
> BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31
> BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9</screen>
> 
>       <para>To change the bridge interface being monitored via the
> 	<literal>mib-2.dot1dBridge</literal> subtree:</para>
> 
>       <screen>&prompt.user; <userinput>snmpset -v 2c -c private bridge1.example.com</userinput>
> BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-aggregation">
>     <info>
>       <title>Link Aggregation and Failover</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Andrew</firstname>
> 	    <surname>Thompson</surname>
> 	  </personname>
> 	  <contrib>Written by </contrib>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm>
>       <primary>lagg</primary>
>     </indexterm>
>     <indexterm>
>       <primary>failover</primary>
>     </indexterm>
>     <indexterm>
>       <primary><acronym>FEC</acronym></primary>
>     </indexterm>
>     <indexterm>
>       <primary><acronym>LACP</acronym></primary>
>     </indexterm>
>     <indexterm>
>       <primary>loadbalance</primary>
>     </indexterm>
>     <indexterm>
>       <primary>roundrobin</primary>
>     </indexterm>
> 
>     <para>&os; provides the &man.lagg.4; interface which can be used
>       to aggregate multiple network interfaces into one virtual
>       interface in order to provide failover and link aggregation.
>       Failover allows traffic to continue to flow as long as at least
>       one aggregated network interface has an established link.  Link
>       aggregation works best on switches which support
>       <acronym>LACP</acronym>, as this protocol distributes traffic
>       bi-directionally while responding to the failure of individual
>       links.</para>
> 
>     <para>The aggregation protocols supported by the lagg interface
>       determine which ports are used for outgoing traffic and whether
>       or not a specific port accepts incoming traffic.  The following
>       protocols are supported by &man.lagg.4;:</para>
> 
>     <variablelist>
>       <varlistentry>
> 	<term>failover</term>
> 	<listitem>
> 	  <para>This mode sends and receives traffic only through
> 	    the master port.  If the master port becomes
> 	    unavailable, the next active port is used.  The first
> 	    interface added to the virtual interface is the master
> 	    port and all subsequently added interfaces are used as
> 	    failover devices.  If failover to a non-master port
> 	    occurs, the original port becomes master once it
> 	    becomes available again.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term>fec / loadbalance</term>
> 	<listitem>
> 	  <para>&cisco; Fast &etherchannel; (<acronym>FEC</acronym>)
> 	    is found on older &cisco; switches.  It provides a
> 	    static setup and does not negotiate aggregation with the
> 	    peer or exchange frames to monitor the link.  If the
> 	    switch supports <acronym>LACP</acronym>, that should be
> 	    used instead.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term><acronym>lacp</acronym></term>
> 	<listitem>
> 	  <para>The &ieee; 802.3ad Link Aggregation Control Protocol
> 	    (<acronym>LACP</acronym>) negotiates a set of
> 	    aggregable links with the peer into one or more Link
> 	    Aggregated Groups (<acronym>LAG</acronym>s).  Each
> 	    <acronym>LAG</acronym> is composed of ports of the same
> 	    speed, set to full-duplex operation, and traffic is
> 	    balanced across the ports in the
> 	    <acronym>LAG</acronym> with the greatest total speed.
> 	    Typically, there is only one <acronym>LAG</acronym>
> 	    which contains all the ports.  In the event of changes
> 	    in physical connectivity,
> 	    <acronym>LACP</acronym> will quickly converge to a new
> 	    configuration.</para>
> 
> 	  <para><acronym>LACP</acronym> balances outgoing traffic
> 	    across the active ports based on hashed protocol header
> 	    information and accepts incoming traffic from any active
> 	    port.  The hash includes the Ethernet source and
> 	    destination address and, if available, the
> 	    <acronym>VLAN</acronym> tag, and the
> 	    <acronym>IPv4</acronym> or <acronym>IPv6</acronym>
> 	    source and destination address.</para>
> 	</listitem>
>       </varlistentry>
> 
>       <varlistentry>
> 	<term>roundrobin</term>
> 	<listitem>
> 	  <para>This mode distributes outgoing traffic using a
> 	    round-robin scheduler through all active ports and
> 	    accepts incoming traffic from any active port.  Since
> 	    this mode violates Ethernet frame ordering, it should be
> 	    used with caution.</para>
> 	</listitem>
>       </varlistentry>
>     </variablelist>
> 
>     <sect2>
>       <title>Configuration Examples</title>
> 
>       <para>This section demonstrates how to configure a &cisco;
> 	switch and a &os; system for <acronym>LACP</acronym> load
> 	balancing.  It then shows how to configure two Ethernet
> 	interfaces in failover mode as well as how to configure
> 	failover mode between an Ethernet and a wireless
> 	interface.</para>
> 
>       <example xml:id="networking-lacp-aggregation-cisco">
> 	<title><acronym>LACP</acronym> Aggregation with a &cisco;
> 	  Switch</title>
> 
> 	<para>This example connects two &man.fxp.4; Ethernet
> 	  interfaces on a &os; machine to the first two Ethernet ports
> 	  on a &cisco; switch as a single load balanced and fault
> 	  tolerant link.  More interfaces can be added to increase
> 	  throughput and fault tolerance.  Replace the names of the
> 	  &cisco; ports, Ethernet devices, channel group number, and
> 	  <acronym>IP</acronym> address shown in the example to match
> 	  the local configuration.</para>
> 
> 	<para>Frame ordering is mandatory on Ethernet links and any
> 	  traffic between two stations always flows over the same
> 	  physical link, limiting the maximum speed to that of one
> 	  interface.  The transmit algorithm attempts to use as much
> 	  information as it can to distinguish different traffic flows
> 	  and balance the flows across the available
> 	  interfaces.</para>
> 
> 	<para>On the &cisco; switch, add the
> 	  <replaceable>FastEthernet0/1</replaceable> and
> 	  <replaceable>FastEthernet0/2</replaceable> interfaces to
> 	  channel group <replaceable>1</replaceable>:</para>
> 
> 	<screen><userinput>interface <replaceable>FastEthernet0/1</replaceable>
>  channel-group <replaceable>1</replaceable> mode active
>  channel-protocol lacp</userinput>
> !
> <userinput>interface <replaceable>FastEthernet0/2</replaceable>
>  channel-group <replaceable>1</replaceable> mode active
>  channel-protocol lacp</userinput></screen>
> 
> 	<para>On the &os; system, create the &man.lagg.4; interface
> 	  using the physical interfaces
> 	  <replaceable>fxp0</replaceable> and
> 	  <replaceable>fxp1</replaceable> and bring the interfaces up
> 	  with an <acronym>IP</acronym> address of
> 	  <replaceable>10.0.0.3/24</replaceable>:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
> &prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput>
> &prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create </userinput>
> &prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable></userinput></screen>
> 
> 	<para>Next, verify the status of the virtual interface:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
> lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
>         options=8&lt;VLAN_MTU&gt;
>         ether 00:05:5d:71:8d:b8
>         media: Ethernet autoselect
>         status: active
>         laggproto lacp
>         laggport: fxp1 flags=1c&lt;ACTIVE,COLLECTING,DISTRIBUTING&gt;
>         laggport: fxp0 flags=1c&lt;ACTIVE,COLLECTING,DISTRIBUTING&gt;</screen>
> 
> 	<para>Ports
> 	  marked as <literal>ACTIVE</literal> are part of the
> 	  <acronym>LAG</acronym> that has been negotiated with the
> 	  remote switch.  Traffic will be transmitted and received
> 	  through these active ports.  Add <option>-v</option> to the
> 	  above command to view the <acronym>LAG</acronym>
> 	  identifiers.</para>
> 
> 	<para>To see the port status on the &cisco; switch:</para>
> 
> 	<screen>switch# <userinput>show lacp neighbor</userinput>
> Flags:  S - Device is requesting Slow LACPDUs
>         F - Device is requesting Fast LACPDUs
>         A - Device is in Active mode       P - Device is in Passive mode
> 
> Channel group 1 neighbors
> 
> Partner's information:
> 
>                   LACP port                        Oper    Port     Port
> Port      Flags   Priority  Dev ID         Age     Key     Number   State
> Fa0/1     SA      32768     0005.5d71.8db8  29s    0x146   0x3      0x3D
> Fa0/2     SA      32768     0005.5d71.8db8  29s    0x146   0x4      0x3D</screen>
> 
> 	<para>For more detail, type <userinput>show lacp neighbor
> 	  detail</userinput>.</para>
> 
> 	<para>To retain this configuration across reboots, add the
> 	  following entries to
> 	  <filename>/etc/rc.conf</filename> on the &os; system:</para>
> 
> 	<programlisting>ifconfig_<replaceable>fxp0</replaceable>="up"
> ifconfig_<replaceable>fxp1</replaceable>="up"
> cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
> ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting>
>       </example>
> 
>       <example xml:id="networking-lagg-failover">
> 	<title>Failover Mode</title>
> 
> 	<para>Failover mode can be used to switch over to a secondary
> 	  interface if the link is lost on the master interface.  To
> 	  configure failover, make sure that the underlying physical
> 	  interfaces are up, then create the &man.lagg.4; interface.
> 	  In this example, <replaceable>fxp0</replaceable> is the
> 	  master interface, <replaceable>fxp1</replaceable> is the
> 	  secondary interface, and the virtual interface is assigned
> 	  an <acronym>IP</acronym> address of
> 	  <replaceable>10.0.0.15/24</replaceable>:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput>
> &prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput>
> &prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
> &prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen>
> 
> 	<para>The virtual interface should look something like
> 	  this:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
> lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
>         options=8&lt;VLAN_MTU&gt;
>         ether 00:05:5d:71:8d:b8
>         inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255
>         media: Ethernet autoselect
>         status: active
>         laggproto failover
>         laggport: fxp1 flags=0&lt;&gt;
>         laggport: fxp0 flags=5&lt;MASTER,ACTIVE&gt;</screen>
> 
> 	<para>Traffic will be transmitted and received on
> 	  <replaceable>fxp0</replaceable>.  If the link is lost on
> 	  <replaceable>fxp0</replaceable>,
> 	  <replaceable>fxp1</replaceable> will become the active link.
> 	  If the link is restored on the master interface, it will
> 	  once again become the active link.</para>
> 
> 	<para>To retain this configuration across reboots, add the
> 	  following entries to
> 	  <filename>/etc/rc.conf</filename>:</para>
> 
> 	<programlisting>ifconfig_<replaceable>fxp0</replaceable>="up"
> ifconfig_<replaceable>fxp1</replaceable>="up"
> cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
> ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>"</programlisting>
>       </example>
> 
>       <example xml:id="networking-lagg-wired-and-wireless">
> 	<title>Failover Mode Between Ethernet and Wireless
> 	  Interfaces</title>
> 
> 	<para>For laptop users, it is usually desirable to configure
> 	  the wireless device as a secondary which is only used when
> 	  the Ethernet connection is not available.  With
> 	  &man.lagg.4;, it is possible to configure a failover which
> 	  prefers the Ethernet connection for both performance and
> 	  security reasons, while maintaining the ability to transfer
> 	  data over the wireless connection.</para>
> 
> 	<para>This is achieved by overriding the physical wireless
> 	  interface's <acronym>MAC</acronym> address with that of the
> 	  Ethernet interface.</para>
> 
> 	<para>In this example, the Ethernet interface,
> 	  <replaceable>bge0</replaceable>, is the master and the
> 	  wireless interface, <replaceable>wlan0</replaceable>, is
> 	  the failover.  The <replaceable>wlan0</replaceable> device
> 	  was created from <replaceable>iwn0</replaceable> wireless
> 	  interface, which will be configured with the
> 	  <acronym>MAC</acronym> address of the Ethernet interface.
> 	  First, determine the <acronym>MAC</acronym> address of the
> 	  Ethernet interface:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput>
> bge0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
> 	options=19b&lt;RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4&gt;
> 	ether 00:21:70:da:ae:37
> 	inet6 fe80::221:70ff:feda:ae37%bge0 prefixlen 64 scopeid 0x2
> 	nd6 options=29&lt;PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL&gt;
> 	media: Ethernet autoselect (1000baseT &lt;full-duplex&gt;)
> 	status: active</screen>
> 
> 	<para>Replace <replaceable>bge0</replaceable> to match the
> 	  system's Ethernet interface name.  The
> 	  <literal>ether</literal> line will contain the
> 	  <acronym>MAC</acronym> address of the specified interface.
> 	  Now, change the <acronym>MAC</acronym> address of the
> 	  underlying wireless interface:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen>
> 
> 	<para>Bring the wireless interface up, but do not set an
> 	  <acronym>IP</acronym> address:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen>
> 
> 	<para>Make sure the <replaceable>bge0</replaceable> interface
> 	  is up, then create the &man.lagg.4; interface with
> 	  <replaceable>bge0</replaceable> as master with failover to
> 	  <replaceable>wlan0</replaceable>:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput>
> &prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput>
> &prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen>
> 
> 	<para>The virtual interface should look something like
> 	  this:</para>
> 
> 	<screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput>
> lagg0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; metric 0 mtu 1500
>         options=8&lt;VLAN_MTU&gt;
>         ether 00:21:70:da:ae:37
>         media: Ethernet autoselect
>         status: active
>         laggproto failover
>         laggport: wlan0 flags=0&lt;&gt;
>         laggport: bge0 flags=5&lt;MASTER,ACTIVE&gt;</screen>
> 
> 	<para>Then, start the <acronym>DHCP</acronym> client to
> 	  obtain an <acronym>IP</acronym> address:</para>
> 
> 	<screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen>
> 
> 	<para>To retain this configuration across reboots, add the
> 	  following entries to
> 	  <filename>/etc/rc.conf</filename>:</para>
> 
> 	<programlisting>ifconfig_bge0="up"
> wlans_<replaceable>iwn0</replaceable>="wlan0"
> ifconfig_wlan0="WPA"
> create_args_wlan0="<replaceable>wlanaddr 00:21:70:da:ae:37</replaceable>"
> cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>"
> ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="up laggproto failover laggport bge0 laggport wlan0 DHCP"</programlisting>
>       </example>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-diskless">
>     <info>
>       <title>Diskless Operation with <acronym>PXE</acronym></title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Jean-Fran&ccedil;ois</firstname>
> 	    <surname>Dock&egrave;s</surname>
> 	  </personname>
> 	  <contrib>Updated by </contrib>
> 	</author>
>       </authorgroup>
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Alex</firstname>
> 	    <surname>Dupre</surname>
> 	  </personname>
> 	  <contrib>Reorganized and enhanced by </contrib>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm>
>       <primary>diskless workstation</primary>
>     </indexterm>
>     <indexterm>
>       <primary>diskless operation</primary>
>     </indexterm>
> 
>     <para>The &intel; Preboot eXecution Environment
>       (<acronym>PXE</acronym>) allows an operating system to boot over
>       the network.  For example, a &os; system can boot over the
>       network and operate without a local disk, using file systems
>       mounted from an <acronym>NFS</acronym> server.
>       <acronym>PXE</acronym> support is usually available in the
>       <acronym>BIOS</acronym>.  To use <acronym>PXE</acronym> when the
>       machine starts, select the <literal>Boot from network</literal>
>       option in the <acronym>BIOS</acronym> setup or type a function
>       key during system initialization.</para>
> 
>     <para>In order to provide the files needed for an operating system
>       to boot over the network, a <acronym>PXE</acronym> setup also
>       requires properly configured <acronym>DHCP</acronym>,
>       <acronym>TFTP</acronym>, and <acronym>NFS</acronym> servers,
>       where:</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para>Initial parameters, such as an <acronym>IP</acronym>
> 	  address, executable boot filename and location, server name,
> 	  and root path are obtained from the
> 	  <acronym>DHCP</acronym> server.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>The operating system loader file is booted using
> 	  <acronym>TFTP</acronym>.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>The file systems are loaded using
> 	  <acronym>NFS</acronym>.</para>
>       </listitem>
>     </itemizedlist>
> 
>     <para>When a computer <acronym>PXE</acronym> boots, it receives
>       information over <acronym>DHCP</acronym> about where to obtain
>       the initial boot loader file.  After the host computer receives
>       this information, it downloads the boot loader via
>       <acronym>TFTP</acronym> and then executes the boot loader.  In
>       &os;, the boot loader file is
>       <filename>/boot/pxeboot</filename>.  After
>       <filename>/boot/pxeboot</filename> executes, the &os; kernel is
>       loaded and the rest of the &os; bootup sequence proceeds, as
>       described in <xref linkend="boot"/>.</para>
> 
>     <para>This section describes how to configure these services on a
>       &os; system so that other systems can <acronym>PXE</acronym>
>       boot into &os;.  Refer to &man.diskless.8; for more
>       information.</para>
> 
>     <caution>
>       <para>As described, the system providing these services is
> 	insecure.  It should live in a protected area of a network and
> 	be untrusted by other hosts.</para>
>     </caution>
> 
>     <sect2 xml:id="network-pxe-nfs">
>       <info>
> 	<title>Setting Up the <acronym>PXE</acronym>
> 	  Environment</title>
> 
> 	<authorgroup>
> 	  <author>
> 	    <personname>
> 	      <firstname>Craig</firstname>
> 	      <surname>Rodrigues</surname>
> 	    </personname>
> 	    <affiliation>
> 	      <address>rodrigc@FreeBSD.org</address>
> 	    </affiliation>
> 	    <contrib>Written by </contrib>
> 	  </author>
> 	</authorgroup>
>       </info>
> 
>       <para>The steps shown in this section configure the built-in
> 	<acronym>NFS</acronym> and <acronym>TFTP</acronym> servers.
> 	The next section demonstrates how to install and configure the
> 	<acronym>DHCP</acronym> server.  In this example, the
> 	directory which will contain the files used by
> 	<acronym>PXE</acronym> users is
> 	<filename>/b/tftpboot/FreeBSD/install</filename>.  It is
> 	important that this directory exists and that the same
> 	directory name is set in both
> 	<filename>/etc/inetd.conf</filename> and
> 	<filename>/usr/local/etc/dhcpd.conf</filename>.</para>
> 
>       <procedure>
> 	<step>
> 	  <para>Create the root directory which will contain a &os;
> 	    installation to be <acronym>NFS</acronym> mounted:</para>
> 
> 	  <screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput>
> &prompt.root; <userinput>mkdir -p ${NFSROOTDIR}</userinput></screen>
> 	</step>
> 
> 	<step>
> 	  <para>Enable the <acronym>NFS</acronym> server by adding
> 	    this line to <filename>/etc/rc.conf</filename>:</para>
> 
> 	  <programlisting>nfs_server_enable="YES"</programlisting>
> 	</step>
> 
> 	<step>
> 	  <para>Export the diskless root directory via
> 	    <acronym>NFS</acronym> by adding the following to
> 	    <filename>/etc/exports</filename>:</para>
> 
> 	  <programlisting>/b -ro -alldirs</programlisting>
> 	</step>
> 
> 	<step>
> 	  <para>Start the <acronym>NFS</acronym> server:</para>
> 
> 	  <screen>&prompt.root; <userinput>service nfsd start</userinput></screen>
> 	</step>
> 
> 	<step>
> 	  <para>Enable &man.inetd.8; by adding the following line to
> 	    <filename>/etc/rc.conf</filename>:</para>
> 
> 	  <programlisting>inetd_enable="YES"</programlisting>
> 	</step>
> 
> 	<step>
> 	  <para>Uncomment the following line in
> 	    <filename>/etc/inetd.conf</filename> by making sure it
> 	    does not start with a <literal>#</literal> symbol:</para>
> 
> 	  <programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /b/tftpboot</programlisting>
> 
> 	  <note>
> 	    <para>Some <acronym>PXE</acronym> versions require the
> 	      <acronym>TCP</acronym> version of
> 	      <acronym>TFTP</acronym>.  In this case, uncomment the
> 	      second <literal>tftp</literal> line which contains
> 	      <literal>stream tcp</literal>.</para>
> 	  </note>
> 	</step>
> 
> 	<step>
> 	  <para>Start &man.inetd.8;:</para>
> 
> 	  <screen>&prompt.root; <userinput>service inetd start</userinput></screen>
> 	</step>
> 
> 	<step>
> 	  <para>Rebuild the &os; kernel and userland (refer to <xref
> 	      linkend="makeworld"/> for more detailed
> 	    instructions):</para>
> 
> 	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
> &prompt.root; <userinput>make buildworld</userinput>
> &prompt.root; <userinput>make buildkernel</userinput></screen>
> 	</step>
> 
> 	<step>
> 	  <para>Install &os; into the directory mounted over
> 	    <acronym>NFS</acronym>:</para>
> 
> 	  <screen>&prompt.root; <userinput>make installworld DESTDIR=${NFSROOTDIR}</userinput>
> &prompt.root; <userinput>make installkernel DESTDIR=${NFSROOTDIR}</userinput>
> &prompt.root; <userinput>make distribution DESTDIR=${NFSROOTDIR}</userinput></screen>
> 	</step>
> 
> 	<step>
> 	  <para>Test that the <acronym>TFTP</acronym> server works and
> 	    can download the boot loader which will be obtained via
> 	    <acronym>PXE</acronym>:</para>
> 
> 	  <screen>&prompt.root; <userinput>tftp localhost</userinput>
> tftp&gt; <userinput>get FreeBSD/install/boot/pxeboot</userinput>
> Received 264951 bytes in 0.1 seconds</screen>
> 	</step>
> 
> 	<step>
> 	  <para>Edit <filename>${NFSROOTDIR}/etc/fstab</filename> and
> 	    create an entry to mount the root file system over
> 	    <acronym>NFS</acronym>:</para>
> 
> 	  <programlisting># Device                                         Mountpoint    FSType   Options  Dump Pass
> <replaceable>myhost.example.com</replaceable>:/b/tftpboot/FreeBSD/install       /         nfs      ro        0    0</programlisting>
> 
> 	  <para>Replace <replaceable>myhost.example.com</replaceable>
> 	    with the hostname or <acronym>IP</acronym> address of the
> 	    <acronym>NFS</acronym> server.  In this example, the root
> 	    file system is mounted read-only in order to prevent
> 	    <acronym>NFS</acronym> clients from potentially deleting
> 	    the contents of the root file system.</para>
> 	</step>
> 
> 	<step>
> 	  <para>Set the root password in the <acronym>PXE</acronym>
> 	    environment for client machines which are
> 	    <acronym>PXE</acronym> booting :</para>
> 
> 	  <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
> &prompt.root; <userinput>passwd</userinput></screen>
> 	</step>
> 
> 	<step>
> 	  <para>If needed, enable &man.ssh.1; root logins for client
> 	    machines which are <acronym>PXE</acronym> booting by
> 	    editing
> 	    <filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename> and
> 	    enabling <literal>PermitRootLogin</literal>.  This option
> 	    is documented in &man.sshd.config.5;.</para>
> 	</step>
> 
> 	<step>
> 	  <para>Perform any other needed customizations of the
> 	    <acronym>PXE</acronym> environment in
> 	    <filename>${NFSROOTDIR}</filename>.  These customizations
> 	    could include things like installing packages or editing
> 	    the password file with &man.vipw.8;.</para>
> 	</step>
>       </procedure>
> 
>       <para>When booting from an <acronym>NFS</acronym> root volume,
> 	<filename>/etc/rc</filename> detects the
> 	<acronym>NFS</acronym> boot and runs
> 	<filename>/etc/rc.initdiskless</filename>.  In this case,
> 	<filename>/etc</filename> and <filename>/var</filename> need
> 	to be memory backed file systems so that these directories are
> 	writable but the <acronym>NFS</acronym> root directory is
> 	read-only:</para>
> 
>       <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
> &prompt.root; <userinput>mkdir -p conf/base</userinput>
> &prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput>
> &prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen>
> 
>       <para>When the system boots, memory file systems for
> 	<filename>/etc</filename> and <filename>/var</filename> will
> 	be created and mounted and the contents of the
> 	<filename>cpio.gz</filename> files will be copied into
> 	them.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-pxe-setting-up-dhcp">
>       <title>Configuring the <acronym>DHCP</acronym> Server</title>
> 
>       <indexterm>
> 	<primary>DHCP</primary>
> 	<secondary>diskless operation</secondary>
>       </indexterm>
> 
>       <para>The <acronym>DHCP</acronym> server does not need to be the
> 	same machine as the <acronym>TFTP</acronym> and
> 	<acronym>NFS</acronym> server, but it needs to be accessible
> 	in the network.</para>
> 
>       <para><acronym>DHCP</acronym> is not part of the &os; base
> 	system but can be installed using the
>-	<package>net/isc-dhcp42-server</package> port or
>+	<package>net/isc-dhcp43-server</package> port or
> 	package.</para>
> 
>       <para>Once installed, edit the configuration file,
> 	<filename>/usr/local/etc/dhcpd.conf</filename>.  Configure
> 	the <literal>next-server</literal>,
> 	<literal>filename</literal>, and
> 	<literal>root-path</literal> settings as seen in this
> 	example:</para>
> 
>       <programlisting>subnet 192.168.0.0 netmask 255.255.255.0 {
>    range 192.168.0.2 192.168.0.3 ;
>    option subnet-mask 255.255.255.0 ;
>    option routers 192.168.0.1 ;
>    option broadcast-address 192.168.0.255 ;
>    option domain-name-servers 192.168.35.35, 192.168.35.36 ;
>    option domain-name "example.com";
> 
>    # IP address of TFTP server
>    next-server <replaceable>192.168.0.1</replaceable> ;
> 
>    # path of boot loader obtained via tftp
>      filename "<replaceable>FreeBSD/install/boot/pxeboot</replaceable>" ;
> 
>    # pxeboot boot loader will try to NFS mount this directory for root FS
>    option root-path "<replaceable>192.168.0.1:/b/tftpboot/FreeBSD/install/</replaceable>" ;
> 
> }</programlisting>
> 
> 
> 
>       <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>
> 
> 
>     <sect2>
>       <title>Debugging <acronym>PXE</acronym> Problems</title>
> 
>       <para>Once all of the services are configured and started,
> 	<acronym>PXE</acronym> clients should be able to
> 	automatically load &os; over the network.  If a particular
> 	client is unable to connect, when that client machine boots
> 	up, enter the <acronym>BIOS</acronym> configuration menu and
> 	confirm that it is set to boot from the network.</para>
> 
>       <para>This section describes some troubleshooting tips for
> 	isolating the source of the configuration problem should no
> 	clients be able to <acronym>PXE</acronym> boot.</para>
> 
>       <procedure>
> 	<step>
> 	  <para>Use the <package>net/wireshark</package> package or
> 	    port to debug the network traffic involved during the
> 	    <acronym>PXE</acronym> booting process, which is
> 	    illustrated in the diagram below.</para>
> 
> 	  <figure>
> 	    <title><acronym>PXE</acronym> Booting Process with
> 	      <acronym>NFS</acronym> Root Mount</title>
> 
> 	    <mediaobject>
> 	      <imageobjectco>
> 		<areaspec units="calspair">
> 		  <area
> 		    xml:id="co-pxenfs1" coords="2873,8133 3313,7266"/>
> 		  <area
> 		    xml:id="co-pxenfs2" coords="3519,6333 3885,5500"/>
> 		  <area
> 		    xml:id="co-pxenfs3" coords="4780,5866 5102,5200"/>
> 		  <area
> 		    xml:id="co-pxenfs4" coords="4794,4333 5102,3600"/>
> 		  <area
> 		    xml:id="co-pxenfs5" coords="3108,2666 3519,1800"/>
> 		</areaspec>
> 		<imageobject>
> 		  <imagedata fileref="advanced-networking/pxe-nfs"/>
> 		</imageobject>
> 		<calloutlist>
> 		  <callout arearefs="co-pxenfs1">
> 		    <para>Client broadcasts a
> 		      <literal>DHCPDISCOVER</literal> message.</para>
> 		  </callout>
> 		  <callout arearefs="co-pxenfs2">
> 		    <para>The <acronym>DHCP</acronym> server responds
> 		      with the <acronym>IP</acronym> address,
> 		      <literal>next-server</literal>,
> 		      <literal>filename</literal>, and
> 		      <literal>root-path</literal> values.</para>
> 		  </callout>
> 		  <callout arearefs="co-pxenfs3">
> 		    <para>The client sends a <acronym>TFTP</acronym>
> 		      request to <literal>next-server</literal>,
> 		      asking to retrieve
> 		      <literal>filename</literal>.</para>
> 		  </callout>
> 		  <callout arearefs="co-pxenfs4">
> 		    <para>The <acronym>TFTP</acronym> server responds
> 		      and sends <literal>filename</literal> to
> 		      client.</para>
> 		  </callout>
> 		  <callout arearefs="co-pxenfs5">
> 		    <para>The client executes
> 		      <literal>filename</literal>, which is
> 		      &man.pxeboot.8;, which then loads the kernel.
> 		      When the kernel executes, the root file system
> 		      specified by <literal>root-path</literal> is
> 		      mounted over <acronym>NFS</acronym>.</para>
> 		  </callout>
> 		</calloutlist>
> 	      </imageobjectco>
> 	    </mediaobject>
> 	  </figure>
> 	</step>
> 
> 	<step>
> 	  <para>On the
> 	    <acronym>TFTP</acronym> server, read
> 	    <filename>/var/log/xferlog</filename> to ensure that
> 	    <filename>pxeboot</filename> is being retrieved from
> 	    the correct location.  To test this example
> 	    configuration:</para>
> 
> 	  <screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput>
> tftp&gt; <userinput>get FreeBSD/install/boot/pxeboot</userinput>
> Received 264951 bytes in 0.1 seconds</screen>
> 
> 	  <para>The <literal>BUGS</literal> sections in &man.tftpd.8;
> 	    and &man.tftp.1; document some limitations with
> 	    <acronym>TFTP</acronym>.</para>
> 	</step>
> 
> 	<step>
> 	  <para>Make sure that the root file system can be mounted
> 	    via <acronym>NFS</acronym>.  To test this example
> 	    configuration:</para>
> 
> 	  <screen>&prompt.root; <userinput>mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt</userinput></screen>
> 	</step>
>       </procedure>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-ipv6">
>     <info>
>       <title><acronym>IPv6</acronym></title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Aaron</firstname>
> 	    <surname>Kaplan</surname>
> 	  </personname>
> 	  <contrib>Originally Written by </contrib>
> 	</author>
>       </authorgroup>
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Tom</firstname>
> 	    <surname>Rhodes</surname>
> 	  </personname>
> 	  <contrib>Restructured and Added by </contrib>
> 	</author>
>       </authorgroup>
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Brad</firstname>
> 	    <surname>Davis</surname>
> 	  </personname>
> 	  <contrib>Extended by </contrib>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <para><acronym>IPv6</acronym> is the new version of the well known
>       <acronym>IP</acronym> protocol, also known as
>       <acronym>IPv4</acronym>.  <acronym>IPv6</acronym> provides
>       several advantages over <acronym>IPv4</acronym> as well as many
>       new features:</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para>Its 128-bit address space allows for
> 	  340,282,366,920,938,463,463,374,607,431,768,211,456
> 	  addresses.  This addresses the <acronym>IPv4</acronym>
> 	  address shortage and eventual <acronym>IPv4</acronym>
> 	  address exhaustion.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Routers only store network aggregation addresses in
> 	  their routing tables, thus reducing the average space of a
> 	  routing table to 8192 entries.  This addresses the
> 	  scalability issues associated with <acronym>IPv4</acronym>,
> 	  which required every allocated block of
> 	  <acronym>IPv4</acronym> addresses to be exchanged between
> 	  Internet routers, causing their routing tables to become too
> 	  large to allow efficient routing.</para>
>       </listitem>
>     </itemizedlist>
> 
>     <itemizedlist>
>       <listitem>
> 	<para>Address autoconfiguration (<link
> 	    xlink:href="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</link>).</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Mandatory multicast addresses.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Built-in <acronym>IPsec</acronym> (<acronym>IP</acronym>
> 	  security).</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Simplified header structure.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Support for mobile <acronym>IP</acronym>.</para>
>       </listitem>
> 
>       <listitem>
> 	<para><acronym>IPv6</acronym>-to-<acronym>IPv4</acronym>
> 	  transition mechanisms.</para>
>       </listitem>
>     </itemizedlist>
> 
>     <para>&os; includes the <link
> 	xlink:href="http://www.kame.net/">http://www.kame.net/</link>
>       <acronym>IPv6</acronym> reference implementation and comes
>       with everything needed to use <acronym>IPv6</acronym>.  This
>       section focuses on getting <acronym>IPv6</acronym> configured
>       and running.</para>
> 
>     <sect2>
>       <title>Background on <acronym>IPv6</acronym> Addresses</title>
> 
>       <para>There are three different types of <acronym>IPv6</acronym>
> 	addresses:</para>
> 
>       <variablelist>
> 	<varlistentry>
> 	  <term>Unicast</term>
> 	  <listitem>
> 	    <para>A packet sent to a unicast address arrives at the
> 	      interface belonging to the address.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>Anycast</term>
> 	  <listitem>
> 	    <para>These addresses are syntactically indistinguishable
> 	      from unicast addresses but they address a group of
> 	      interfaces.  The packet destined for an anycast address
> 	      will arrive at the nearest router interface.  Anycast
> 	      addresses are only used by routers.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>Multicast</term>
> 	  <listitem>
> 	    <para>These addresses identify a group of interfaces.  A
> 	      packet destined for a multicast address will arrive at
> 	      all interfaces belonging to the multicast group.  The
> 	      <acronym>IPv4</acronym> broadcast address, usually
> 	      <systemitem
> 		class="ipaddress">xxx.xxx.xxx.255</systemitem>, is
> 	      expressed by multicast addresses in
> 	      <acronym>IPv6</acronym>.</para>
> 	  </listitem>
> 	</varlistentry>
>       </variablelist>
> 
>       <para>When reading an <acronym>IPv6</acronym> address, the
> 	canonical form is represented as
> 	<systemitem>x:x:x:x:x:x:x:x</systemitem>, where each
> 	<literal>x</literal> represents a 16 bit hex value.  An
> 	example is
> 	<systemitem>FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</systemitem>.</para>
> 
>       <para>Often, an address will have long substrings of all zeros.
> 	A <literal>::</literal> (double colon) can be used to replace
> 	one substring per address.  Also, up to three leading
> 	<literal>0</literal>s per hex value can be omitted.  For
> 	example, <systemitem>fe80::1</systemitem> corresponds to the
> 	canonical form
> 	<systemitem>fe80:0000:0000:0000:0000:0000:0000:0001</systemitem>.</para>
> 
>       <para>A third form is to write the last 32 bits using the well
> 	known <acronym>IPv4</acronym> notation.  For example,
> 	<systemitem>2002::10.0.0.1</systemitem> corresponds to the
> 	hexadecimal canonical representation
> 	<systemitem>2002:0000:0000:0000:0000:0000:0a00:0001</systemitem>,
> 	which in turn is equivalent to
> 	<systemitem>2002::a00:1</systemitem>.</para>
> 
>       <para>To view a &os; system's <acronym>IPv6 </acronym> address,
> 	use &man.ifconfig.8;:</para>
> 
>       <screen>&prompt.root; <userinput>ifconfig</userinput></screen>
> 
>       <programlisting>rl0: flags=8943&lt;UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST&gt; mtu 1500
>          inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
>          inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
>          ether 00:00:21:03:08:e1
>          media: Ethernet autoselect (100baseTX )
>          status: active</programlisting>
> 
>       <para>In this example, the <filename>rl0</filename> interface is
> 	using <systemitem>fe80::200:21ff:fe03:8e1%rl0</systemitem>, an
> 	auto-configured link-local address which was automatically
> 	generated from the <acronym>MAC</acronym> address.</para>
> 
>       <para>Some <acronym>IPv6</acronym> addresses are reserved.  A
> 	summary of these reserved addresses is seen in <xref
> 	  linkend="reservedip6"/>:</para>
> 
>       <table xml:id="reservedip6" frame="none">
> 	<title>Reserved <acronym>IPv6</acronym> Addresses</title>
> 
> 	<tgroup cols="4">
> 	  <thead>
> 	    <row>
> 	      <entry><acronym>IPv6</acronym> address</entry>
> 	      <entry>Prefixlength (Bits)</entry>
> 	      <entry>Description</entry>
> 	      <entry>Notes</entry>
> 	    </row>
> 	  </thead>
> 
> 	  <tbody>
> 	    <row>
> 	      <entry><systemitem>::</systemitem></entry>
> 	      <entry>128 bits</entry>
> 	      <entry>unspecified</entry>
> 	      <entry>Equivalent to <systemitem
> 		  class="ipaddress">0.0.0.0</systemitem> in
> 		<acronym>IPv4</acronym>.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>::1</systemitem></entry>
> 	      <entry>128 bits</entry>
> 	      <entry>loopback address</entry>
> 	      <entry>Equivalent to <systemitem
> 		  class="ipaddress">127.0.0.1</systemitem> in
> 		<acronym>IPv4</acronym>.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>::00:xx:xx:xx:xx</systemitem></entry>
> 	      <entry>96 bits</entry>
> 	      <entry>embedded <acronym>IPv4</acronym></entry>
> 	      <entry>The lower 32 bits are the compatible
> 		<acronym>IPv4</acronym> address.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>::ff:xx:xx:xx:xx</systemitem></entry>
> 	      <entry>96 bits</entry>
> 	      <entry><acronym>IPv4</acronym> mapped
> 		<acronym>IPv6</acronym> address</entry>
> 	      <entry>The lower 32 bits are the <acronym>IPv4</acronym>
> 		address for hosts which do not support
> 		<acronym>IPv6</acronym>.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>fe80::/10</systemitem></entry>
> 	      <entry>10 bits</entry>
> 	      <entry>link-local</entry>
> 	      <entry>Equivalent to 169.254.0.0/16 in
> 		<acronym>IPv4</acronym>.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>fc00::/7</systemitem></entry>
> 	      <entry>7 bits</entry>
> 	      <entry>unique-local</entry>
> 	      <entry>Unique local addresses are intended for local
> 		communication and are only routable within a set of
> 		cooperating sites.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>ff00::</systemitem></entry>
> 	      <entry>8 bits</entry>
> 	      <entry>multicast</entry>
> 	      <entry>&nbsp;</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>2000::-3fff:: </systemitem></entry>
> 	      <entry>3 bits</entry>
> 	      <entry>global unicast</entry>
> 	      <entry>All global unicast addresses are assigned from
> 		this pool.  The first 3 bits are
> 		<literal>001</literal>.</entry>
> 	    </row>
> 	  </tbody>
> 	</tgroup>
>       </table>
> 
>       <para>For further information on the structure of
> 	<acronym>IPv6</acronym> addresses, refer to <link
> 	  xlink:href="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</link>.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Configuring <acronym>IPv6</acronym></title>
> 
>       <para>To configure a &os; system as an <acronym>IPv6</acronym>
> 	client, add these two lines to
> 	<filename>rc.conf</filename>:</para>
> 
>       <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 accept_rtadv"
> rtsold_enable="YES"</programlisting>
> 
>       <para>The first line enables the specified interface to receive
> 	router solicitation messages.  The second line enables the
> 	router solicitation daemon, &man.rtsol.8;.</para>
> 
>       <para>If the interface needs a statically assigned
> 	<acronym>IPv6</acronym> address, add an entry to specify the
> 	static address and associated prefix length:</para>
> 
>       <programlisting>ifconfig_<replaceable>rl0</replaceable>_ipv6="inet6 <replaceable>2001:db8:4672:6565:2026:5043:2d42:5344</replaceable> prefixlen <replaceable>64</replaceable>"</programlisting>
> 
>       <para>To assign a default router, specify its address:</para>
> 
>       <programlisting>ipv6_defaultrouter="<replaceable>2001:db8:4672:6565::1</replaceable>"</programlisting>
>     </sect2>
> 
>     <sect2>
>       <title>Connecting to a Provider</title>
> 
>       <para>In order to connect to other <acronym>IPv6</acronym>
> 	networks, one must have a provider or a tunnel that supports
> 	<acronym>IPv6</acronym>:</para>
> 
>       <itemizedlist>
> 	<listitem>
> 	  <para>Contact an Internet Service Provider to see if they
> 	    offer <acronym>IPv6</acronym>.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><link
> 	      xlink:href="http://www.tunnelbroker.net">Hurricane
> 	      Electric</link> offers tunnels with end-points all
> 	    around the globe.</para>
> 	</listitem>
>       </itemizedlist>
> 
>       <note>
> 	<para>Install the <package>net/freenet6</package> package or
> 	  port for a dial-up connection.</para>
>       </note>
> 
>       <para>This section demonstrates how to take the directions from
> 	a tunnel provider and convert them into
> 	<filename>/etc/rc.conf</filename> settings that will persist
> 	through reboots.</para>
> 
>       <para>The first <filename>/etc/rc.conf</filename> entry creates
> 	the generic tunneling interface
> 	<filename><replaceable>gif0</replaceable></filename>:</para>
> 
>       <programlisting>cloned_interfaces="gif<replaceable>0</replaceable>"</programlisting>
> 
>       <para>Next, configure that interface with the
> 	<acronym>IPv4</acronym> addresses of the local and remote
> 	endpoints.  Replace <replaceable>MY_IPv4_ADDR</replaceable>
> 	and <replaceable>REMOTE_IPv4_ADDR</replaceable> with the
> 	actual <acronym>IPv4</acronym> addresses:</para>
> 
>       <programlisting>create_args_gif0="tunnel <replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting>
> 
>       <para>To apply the <acronym>IPv6</acronym> address that has been
> 	assigned for use as the <acronym>IPv6</acronym> tunnel
> 	endpoint, add this line, replacing
> 	<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>
> 	with the assigned address:</para>
> 
>       <programlisting>ifconfig_gif0_ipv6="inet6 <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
> 
>       <para>Then, set the default route for the other side of the
> 	<acronym>IPv6</acronym> tunnel.  Replace
> 	<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>
> 	with the default gateway address assigned by the
> 	provider:</para>
> 
>       <programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting>
> 
>       <para>If the &os; system will route <acronym>IPv6</acronym>
> 	packets between the rest of the network and the world, enable
> 	the gateway using this line:</para>
> 
>       <programlisting>ipv6_gateway_enable="YES"</programlisting>
>     </sect2>
> 
>     <sect2>
>       <title>Router Advertisement and Host Auto Configuration</title>
> 
>       <para>This section demonstrates how to setup &man.rtadvd.8; to
> 	advertise the <acronym>IPv6</acronym> default route.</para>
> 
>       <para>To enable &man.rtadvd.8;, add the following to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>rtadvd_enable="YES"</programlisting>
> 
>       <para>It is important to specify the interface on which to
> 	do <acronym>IPv6</acronym> router solicitation.  For example,
> 	to tell &man.rtadvd.8; to use
> 	<filename>rl0</filename>:</para>
> 
>       <programlisting>rtadvd_interfaces="rl0"</programlisting>
> 
>       <para>Next, create the configuration file,
> 	<filename>/etc/rtadvd.conf</filename> as seen in this
> 	example:</para>
> 
>       <programlisting>rl0:\
> 	:addrs#1:addr="2001:db8:1f11:246::":prefixlen#64:tc=ether:</programlisting>
> 
>       <para>Replace <filename>rl0</filename> with the interface
> 	to be used and <systemitem>2001:db8:1f11:246::</systemitem>
> 	with the prefix of the allocation.</para>
> 
>       <para>For a dedicated <systemitem
> 	  class="netmask">/64</systemitem> subnet, nothing else needs
> 	to be changed.  Otherwise, change the
> 	<literal>prefixlen#</literal> to the correct value.</para>
>     </sect2>
> 
>     <sect2>
>       <title><acronym>IPv6</acronym> and <acronym>IPv6</acronym>
> 	Address Mapping</title>
> 
>       <para>When <acronym>IPv6</acronym> is enabled on a server, there
> 	may be a need to enable <acronym>IPv4</acronym> mapped
> 	<acronym>IPv6</acronym> address communication.  This
> 	compatibility option allows for <acronym>IPv4</acronym>
> 	addresses to be represented as <acronym>IPv6</acronym>
> 	addresses.  Permitting <acronym>IPv6</acronym> applications
> 	to communicate with <acronym>IPv4</acronym> and vice versa
> 	may be a security issue.</para>
> 
>       <para>This option may not be required in most cases and is
> 	available only for compatibility.  This option will allow
> 	<acronym>IPv6</acronym>-only applications to work with
> 	<acronym>IPv4</acronym> in a dual stack environment.  This
> 	is most useful for third party applications which may not
> 	support an <acronym>IPv6</acronym>-only environment.  To
> 	enable this feature,
> 	add the following to <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>ipv6_ipv4mapping="YES"</programlisting>
> 
>       <para>Reviewing the information in <acronym>RFC</acronym> 3493,
> 	section 3.6 and 3.7 as well as <acronym>RFC</acronym> 4038
> 	section 4.2 may be useful to some administrators.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="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>

Actions: View | Diff

Attachments on bug 219966: 184060