os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml
Sevan Janiyan 9b207cb155 Fix spelling mistakes picked up by igor. 
Approved by:	bcr (mentor)
Differential Revision:	https://reviews.freebsd.org/D8428
2016-11-03 19:48:36 +00:00

5264 lines
207 KiB
XML
Raw Blame History

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