path: root/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml

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

     $FreeBSD$
-->

<chapter id="advanced-networking">
  <title>Advanced Networking</title>

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

    <para>This chapter will cover 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 &ieee; 802.11 and &bluetooth;
	  devices.</para>
      </listitem>

      <listitem>
	<para>How to make FreeBSD act as a bridge.</para>
      </listitem>

      <listitem>
	<para>How to set up network booting on a diskless
	  machine.</para>
      </listitem>

      <listitem>
	<para>How to set up network PXE booting with an NFS root file
	  system.</para>
      </listitem>

      <listitem>
	<para>How to set up network address translation.</para>
      </listitem>

      <listitem>
	<para>How to set up IPv6 on a FreeBSD machine.</para>
      </listitem>

      <listitem>
	<para>How to configure ATM.</para>
      </listitem>

      <listitem>
	<para>How to enable and utilize the features of CARP, the
	  Common Address Redundancy Protocol in &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 FreeBSD kernel
	  (<xref linkend="kernelconfig"/>).</para>
      </listitem>

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

    </itemizedlist>
  </sect1>

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

    <title>Gateways and Routes</title>

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

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

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

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

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

Destination      Gateway            Flags     Refs     Use     Netif Expire

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

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

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

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

      <indexterm><primary>subnet</primary></indexterm>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      <indexterm><primary>default route</primary></indexterm>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	    <row>
	      <entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
	      <entry>T1-GW (10.9.9.1)</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

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

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

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

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

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

    <sect2 id="network-dual-homed-hosts">
      <title>Dual Homed Hosts</title>

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

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

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

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

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

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

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

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

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

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

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

    <sect2 id="network-static-routes">
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Al</firstname>
	    <surname>Hoang</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <!-- Feb 2004 -->
      <title>Setting Up Static Routes</title>

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

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

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

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

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

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

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

Internet:
Destination        Gateway            Flags    Refs      Use  Netif  Expire
default            10.0.0.1           UGS         0    49378    xl0
127.0.0.1          127.0.0.1          UH          0        6    lo0
10.0.0.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  <hostid>RouterA</hostid>
	  will not be able to reach our Internal Net 2.  It does not
	  have a route for
	  <hostid role="ipaddr">192.168.2.0/24</hostid>.  One way to
	  alleviate this is to manually add the route.  The following
	  command would add the Internal Net 2 network to
	  <hostid>RouterA</hostid>'s routing table using
	  <hostid role="ipaddr">192.168.1.2</hostid> as the next
	  hop:</para>

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

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

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

	<para>The above example is perfect for configuring a static
	  route on a running system.  However, one problem is that the
	  routing information will not persist if you reboot your &os;
	  machine.  Additional static routes can be
	  entered in <filename>/etc/rc.conf</filename>:</para>

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

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

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

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

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

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

    <sect2 id="network-routing-propagation">
      <title>Routing Propagation</title>

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

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

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

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

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

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

      <indexterm>
	<primary><command>traceroute</command></primary>
      </indexterm>

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

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

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

    <sect2 id="network-routing-multicast">
      <title>Multicast Routing</title>

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

      <programlisting>options MROUTING</programlisting>

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

      <note>
	<para>The &man.mrouted.8; multicast routing daemon implements
	  the <acronym>DVMRP</acronym> multicast routing protocol,
	  which has largely been replaced by &man.pim.4; in many
	  multicast installations.  &man.mrouted.8; and the related
	  &man.map-mbone.8; and &man.mrinfo.8; utilities are available
	  in the &os; Ports&nbsp;Collection as
	  <filename role="package">net/mrouted</filename>.</para>
      </note>
    </sect2>
  </sect1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	<note>
	  <para>In the rest of this document, we will use an
	    &man.ath.4; device, the device name in the examples must
	    be changed according to your configuration.  A list of
	    available wireless drivers and supported adapters can be
	    found in the &os; Hardware Notes.  Copies of these notes
	    for various releases and architectures are available on
	    the <ulink
	      url="http://www.FreeBSD.org/releases/index.html">Release
	      Information</ulink> page of the &os; Web site.  If a
	    native &os; driver for your wireless device does not
	    exist, it may be possible to directly use the &windows;
	    driver with the help of the
	    <link linkend="config-network-ndis">NDIS</link> driver
	    wrapper.</para>
	</note>

	<para>With that, you will need the modules that implement
	  cryptographic support for the security protocols you intend
	  to use.  These are intended to be dynamically loaded on
	  demand by the &man.wlan.4; module but for now they must be
	  manually configured.  The following modules are available:
	  &man.wlan.wep.4;, &man.wlan.ccmp.4; and &man.wlan.tkip.4;.
	  Both &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are
	  only needed if you intend to use the WPA and/or 802.11i
	  security protocols.  If your network does not use
	  encryption, you will not need &man.wlan.wep.4; support.  To
	  load these modules at boot time, add the following lines to
	  <filename>/boot/loader.conf</filename>:</para>

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

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

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

	  <programlisting>device 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 your &os;
	    machine.</para>
	</note>

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

	<screen>ath0: &lt;Atheros 5212&gt; mem 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>The infrastructure mode or BSS mode is the mode that is
	typically used.  In this mode, a number of wireless access
	points are connected to a wired network.  Each wireless
	network has its own name, this name is called the SSID of the
	network.  Wireless clients connect to the wireless access
	points.</para>

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

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

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

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>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>You must mark the interface <option>up</option>
	      before you can scan.  Subsequent scan requests do not
	      require you to mark the interface up again.</para>
	  </note>

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

	  <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 (ESS).  Indicates that
		    the station is part of an infrastructure network
		    (in contrast to an IBSS/ad-hoc network).</entry>
		</row>

		<row>
		  <entry><literal>I</literal></entry>
		  <entry>IBSS/ad-hoc network.  Indicates that the
		    station is part of an ad-hoc network (in contrast
		    to an ESS network).</entry>
		</row>

		<row>
		  <entry><literal>P</literal></entry>
		  <entry>Privacy.  Data confidentiality is required
		    for all data frames exchanged within the BSS.
		    This means that this BSS requires the station to
		    use cryptographic means such as WEP, TKIP or
		    AES-CCMP to encrypt/decrypt data frames being
		    exchanged with others.</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, short preamble utilizes a 56 bit
		    sync field in contrast to a 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.  After you are familiar with these concepts,
	    we strongly recommend using
	    <link linkend="network-wireless-wpa">WPA</link> to set up
	    your wireless network.</para>

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

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

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

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

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

	    <programlisting>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 SSID (often done to simplify
	      roaming) it may be necessary to associate to one
	      specific device.  In this case you can also specify the
	      BSSID of the access point (you can also leave off the
	      SSID):</para>

	    <programlisting>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 if you have a
	      multi-band wireless card as scanning all the possible
	      channels can be time-consuming.  To limit operation to a
	      specific band you can use the <option>mode</option>
	      parameter; e.g.:</para>

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

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

	  <sect5>
	    <title>Authentication</title>

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

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

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

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

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

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

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

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

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

	    <screen>&prompt.root; <userinput>ifconfig <replaceable>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> means you
	      are connected to the wireless network (to the
	      <literal>dlinkap</literal> network in our case).  The
	      <literal>bssid 00:13:46:49:41:76</literal> part is the
	      MAC address of your access point; the
	      <literal>authmode OPEN</literal> part informs you that
	      the communication is not encrypted.</para>
	  </sect5>

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

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

	    <programlisting>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 id="network-wireless-wpa">
	  <title>WPA</title>

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

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

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

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

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

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

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

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

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

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

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

	    <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>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 the launch of the
	      <command>dhclient</command> command to get the IP
	      address from the DHCP 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</literal> entry with the
		<literal>DHCP</literal> string (like
		<literal>ifconfig_wlan0="DHCP"</literal>),
		<command>dhclient</command> will be launched
		automatically after <command>wpa_supplicant</command>
		associates with the access point.</para>
	    </note>

	    <para>If DHCP is not possible or desired,
	      you can set a static IP address after
	      <command>wpa_supplicant</command> 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 DHCP is not used, you also have to manually set
	      the default gateway and the nameserver:</para>

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

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

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

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

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

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

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

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

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

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

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

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

	      <callout arearefs="co-tls-cacert">
		<para>The <literal>ca_cert</literal> field indicates
		  the pathname of the CA certificate file.  This file
		  is needed to verify the server 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>As previously shown, it is also possible to bring up
	      the interface manually with both
	      <command>wpa_supplicant</command> and
	      <command>ifconfig</command> commands.</para>
	  </sect5>

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

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

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

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

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

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

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

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

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

	    <para>You also have to add the following 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 id="network-wireless-wpa-eap-peap">
	    <title>WPA with EAP-PEAP</title>

	    <note>
	      <para>PEAPv0/EAP-MSCHAPv2 is the most common PEAP
		method.  In the rest of this document, we will use the
		PEAP term to refer to that method.</para>
	    </note>

	    <para>PEAP (Protected EAP) has been designed as an
	      alternative to EAP-TTLS, and is the most used EAP
	      standard after EAP-TLS.  In other words, if you have a
	      network with mixed OSes, PEAP should be the most
	      supported standard after EAP-TLS.</para>

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

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

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

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

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

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

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

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

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

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

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

	    <para>Then we can 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 id="network-wireless-wep">
	  <title>WEP</title>

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

	  <para>WEP can be set up with
	    <command>ifconfig</command>:</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> means which WEP
		key will be used in the transmission.  Here we used
		the third key.  This must match the setting in the
		access point.  If you do not have any idea of which
		key is used by the access point, try
		<literal>1</literal> (i.e., the first key) for this
		value.</para>
	    </listitem>

	    <listitem>
	      <para>The <literal>wepkey</literal> selects one of the
		WEP 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 if we use a key other
		than the first key.</para>

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

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

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

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

	  <para>Then:</para>

	  <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>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>IBSS mode, also called ad-hoc mode, is designed for point
	to point connections.  For example, to establish an ad-hoc
	network between the machine <hostid>A</hostid> and the machine
	<hostid>B</hostid>, we will just need to choose two IP
	addresses and a SSID.</para>

      <para>On the box <hostid>A</hostid>:</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 the
	interface is running in the IBSS mode.</para>

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

      <screen>&prompt.root; <userinput>ifconfig <replaceable>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 the
	machine <hostid>A</hostid> is in ad-hoc mode.  We just have to
	configure <hostid>B</hostid> with a different IP
	address:</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>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 <hostid>A</hostid> and <hostid>B</hostid> are now
	ready to exchange information.</para>
    </sect2>

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

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

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

	<para>Before configuring your &os; machine as an AP, the
	  kernel must be configured with the appropriate wireless
	  networking support for your wireless card.  You also have to
	  add support for the security protocols you intend to
	  use.  For more details, see
	  <xref linkend="network-wireless-basic"/>.</para>

	<note>
	  <para>The use of the NDIS driver wrapper and the &windows;
	    drivers do not currently allow AP operation.  Only native
	    &os; wireless drivers support AP mode.</para>
	</note>

	<para>Once wireless networking support is loaded, you can
	  check if your 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 capabilities; the
	  <literal>HOSTAP</literal> word confirms this wireless card
	  can act as an Access Point.  Various supported ciphers are
	  also mentioned: WEP, TKIP, AES, etc.  This information
	  is important to know what security protocols can be used
	  on the Access Point.</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 <command>ifconfig</command> again to see the status
	  of the <devicename>wlan0</devicename> 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 AP without any
	  authentication or encryption, this is a simple way to check
	  if your AP is working.  This configuration is also important
	  for debugging client issues.</para>

	<para>Once the AP configured as previously shown, it is
	  possible from another wireless machine to initiate a scan to
	  find the AP:</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 Access Point 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>
	<title>WPA Host-based Access Point</title>

	<para>This section will focus on setting up &os; Access Point
	  using the WPA security protocol.  More details regarding WPA
	  and the configuration of WPA-based wireless clients can be
	  found in the <xref linkend="network-wireless-wpa"/>.</para>

	<para>The <application>hostapd</application> daemon is used to
	  deal with client authentication and keys management on the
	  WPA enabled Access Point.</para>

	<para>In the following, all the configuration operations will
	  be performed on the &os; machine acting as AP.  Once the
	  AP is correctly working, <application>hostapd</application>
	  should be automatically enabled at boot with the following
	  line in <filename>/etc/rc.conf</filename>:</para>

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

	<para>Before trying to configure
	  <application>hostapd</application>, be sure you have done
	  the basic settings introduced in the
	  <xref linkend="network-wireless-ap-basic"/>.</para>

	<sect4>
	  <title>WPA-PSK</title>

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

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

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

	  <calloutlist>
	    <callout arearefs="co-ap-wpapsk-iface">
	      <para>This field indicates the wireless interface used
		for the Access Point.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-dbug">
	      <para>This field sets the level of verbosity during the
		execution of <application>hostapd</application>.  A
		value of <literal>1</literal> represents the minimal
		level.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-ciface">
	      <para>The <literal>ctrl_interface</literal> field gives
		the pathname of the directory used by
		<application>hostapd</application> to stores its
		domain socket files for the communication with
		external programs such as &man.hostapd.cli.8;.  The
		default value is used here.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-cifacegrp">
	      <para>The <literal>ctrl_interface_group</literal> line
		sets the group (here, it is the
		<groupname>wheel</groupname> group) allowed to access
		to the control interface files.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-ssid">
	      <para>This field sets the network name.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-wpa">
	      <para>The <literal>wpa</literal> field enables WPA and
		specifies which WPA authentication protocol will be
		required.  A value of <literal>1</literal> configures
		the AP for WPA-PSK.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-pass">
	      <para>The <literal>wpa_passphrase</literal> field
		contains the ASCII passphrase for the WPA
		authentication.</para>

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

	    <callout arearefs="co-ap-wpapsk-kmgmt">
	      <para>The <literal>wpa_key_mgmt</literal> line refers to
		the key management protocol we use.  In our case it is
		WPA-PSK.</para>
	    </callout>

	    <callout arearefs="co-ap-wpapsk-pwise">
	      <para>The <literal>wpa_pairwise</literal> field
		indicates the set of accepted encryption algorithms by
		the Access Point.  Here both TKIP (WPA) and CCMP
		(WPA2) ciphers are accepted.  CCMP cipher is an
		alternative to TKIP and that is strongly preferred
		when possible; TKIP should be used solely for stations
		incapable of doing CCMP.</para>
	    </callout>
	  </calloutlist>

	  <para>The next step is to start
	    <application>hostapd</application>:</para>

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

	  <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput>
  wlan0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 2290
	  inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255
	  inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4
	  ether 00:11:95:c3:0d:ac
	  media: IEEE 802.11 Wireless Ethernet autoselect mode 11g &lt;hostap&gt;
	  status: associated
	  ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac
	  authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen>

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

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

	<para>It is not recommended to use WEP for setting up an
	  Access Point since there is no authentication mechanism and
	  it is easily to be cracked.  Some legacy wireless cards only
	  support WEP as security protocol, these cards will only
	  allow to set up AP without authentication or encryption or
	  using the WEP protocol.</para>

	<para>The wireless device can now be put into hostap mode and
	  configured with the correct SSID and IP 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> means which WEP
	      key will be used in the transmission.  Here we used the
	      third key (note that the key numbering starts with
	      <literal>1</literal>).  This parameter must be specified
	      to really encrypt the data.</para>
	  </listitem>

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

	<para>Use again <command>ifconfig</command> to see the status
	  of the <devicename>wlan0</devicename> 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 possible to
	  initiate a scan to find the AP:</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>The client machine found the Access Point and can be
	  associated with it using the correct parameters (key, etc.),
	  see <xref linkend="network-wireless-wep"/> for more
	  details.</para>
      </sect3>
    </sect2>

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

      <para>Wired connection provides better performance and
	reliability, while wireless connection provides flexibility
	and mobility, users of laptop computers usually want to
	combine these together and roam seamlessly between the
	two.</para>

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

      <para>We will cover link aggregation and failover in
	<xref linkend="network-aggregation"/> where an example for
	using both wired and wireless connection is also provided at
	<xref linkend="networking-lagg-wired-and-wireless"/>.</para>
    </sect2>

    <sect2>
      <title>Troubleshooting</title>

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

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

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

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

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

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

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

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

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

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

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

    <title>Bluetooth</title>

    <indexterm><primary>Bluetooth</primary></indexterm>
    <sect2>
      <title>Introduction</title>

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

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

    <sect2>
      <title>Plugging in the Device</title>

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

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

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

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

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

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

      <para>&man.service.8;
	is used to start and stop the Bluetooth stack.  It is a good
	idea to stop the stack before unplugging the device, but it is
	not (usually) fatal.  When starting the stack, you will
	receive output similar to the following:</para>

      <screen>&prompt.root; <userinput>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>Host Controller Interface (HCI)</title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      <para>RFCOMM is only concerned with the connection between the
	devices in the direct connect case, or between the device and
	a modem in the network case.  RFCOMM can support other
	configurations, such as modules that communicate via Bluetooth
	wireless technology on one side and provide a wired interface
	on the other side.</para>

      <para>In &os; the RFCOMM protocol is implemented at the
	Bluetooth sockets layer.</para>
    </sect2>

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

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

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

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

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

      <para>The following line can be added to the
	<filename>/etc/rc.conf</filename> file to have
	<application>hcsecd</application> started automatically on
	system start:</para>

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

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

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

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

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

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

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

      <para>Normally, a SDP client searches for services based on some
	desired characteristics of the services.  However, there are
	times when it is desirable to discover which types of services
	are described by an SDP server's service records without any a
	priori information about the services.  This process of
	looking for any offered services is called
	<emphasis>browsing</emphasis>.</para>

      <para>The Bluetooth SDP server &man.sdpd.8; and command line
	client &man.sdpcontrol.8; are included in the standard &os;
	installation.  The following example shows how to perform a
	SDP browse query.</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2>
      <title>Serial Port Profile (SPP)</title>

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

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

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

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

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

    <sect2>
      <title>Troubleshooting</title>

      <sect3>
	<title>A Remote Device Cannot Connect</title>

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

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

      <sect3>
	<title>Something is Going Wrong, Can I See What Exactly is
	  Happening?</title>

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

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

    <sect2>
      <title>Introduction</title>

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

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

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

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

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

      <sect3>
	<title>Connecting Networks</title>

	<para>The basic operation of a bridge is to join two or more
	  network segments together.  There are many reasons to use a
	  host based bridge over plain networking equipment such as
	  cabling constraints, firewalling or connecting pseudo
	  networks such as a Virtual Machine interface.  A bridge can
	  also connect a wireless interface running in hostap mode to
	  a wired network and act as an access point.</para>
      </sect3>

      <sect3>
	<title>Filtering/Traffic Shaping Firewall</title>

	<indexterm><primary>firewall</primary></indexterm>
	<indexterm><primary>NAT</primary></indexterm>

	<para>A common situation is where firewall functionality is
	  needed without routing or network address translation
	  (NAT).</para>

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

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

      <sect3>
	<title>Network Tap</title>

	<para>A bridge can join two network segments and be used to
	  inspect all Ethernet frames that pass between them.  This
	  can either be from using &man.bpf.4;/&man.tcpdump.1; on the
	  bridge interface or by sending a copy of all frames out an
	  additional interface (span port).</para>
      </sect3>

      <sect3>
	<title>Layer 2 VPN</title>

	<para>Two Ethernet networks can be joined across an IP link by
	  bridging the networks to an EtherIP tunnel or a &man.tap.4;
	  based solution such as OpenVPN.</para>
      </sect3>

      <sect3>
	<title>Layer 2 Redundancy</title>

	<para>A network can be connected together with multiple links
	  and use the Spanning Tree Protocol to block redundant paths.
	  For an Ethernet network to function properly only one active
	  path can exist between two devices, Spanning Tree will
	  detect loops and put the redundant links into a blocked
	  state.  Should one of the active links fail then the
	  protocol will calculate a different tree and reenable one of
	  the blocked paths to restore connectivity to all points in
	  the network.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Kernel Configuration</title>

      <para>This section covers &man.if.bridge.4; bridge
	implementation, a netgraph bridging driver is also available,
	for more information see &man.ng.bridge.4; manual page.</para>

      <para>The bridge driver is a kernel module and will be
	automatically loaded by &man.ifconfig.8; when creating a
	bridge interface.  It is possible to compile the bridge in to
	the kernel by adding <literal>device if_bridge</literal> to
	your kernel configuration file.</para>

      <para>Packet filtering can be used with any firewall package
	that hooks in via the &man.pfil.9; framework.  The firewall
	can be loaded as a module or compiled into the kernel.</para>

      <para>The bridge can be used as a traffic shaper with
	&man.altq.4; or &man.dummynet.4;.</para>
    </sect2>

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

      <para>The bridge is created using interface cloning.  To create
	a bridge use &man.ifconfig.8;, if the bridge driver is not
	present in the kernel then it will be loaded
	automatically.</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>A bridge interface is created and is automatically
	assigned a randomly generated Ethernet address.  The
	<literal>maxaddr</literal> and <literal>timeout</literal>
	parameters control how many MAC 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 Spanning Tree operates.</para>

      <para>Add the member network interfaces to 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 is now forwarding Ethernet frames between
	<devicename>fxp0</devicename> and
	<devicename>fxp1</devicename>.  The equivalent configuration
	in <filename>/etc/rc.conf</filename> so the bridge is created
	at startup is:</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 IP address then the correct
	place to set this is on the bridge interface itself rather
	than one of the member interfaces.  This can be set statically
	or via DHCP:</para>

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

      <para>It is also possible to assign an IPv6 address to a bridge
	interface.</para>
    </sect2>

    <sect2>
      <title>Firewalling</title>

      <indexterm><primary>firewall</primary></indexterm>

      <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-IP and ARP packets, and layer2 firewalling with IPFW.  See
	&man.if.bridge.4; for more information.</para>
    </sect2>

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

      <para>The bridge driver implements the Rapid Spanning Tree
	Protocol (RSTP or 802.1w) with backwards compatibility with
	the legacy Spanning Tree Protocol (STP).  Spanning Tree is
	used to detect and remove loops in a network topology.  RSTP
	provides faster Spanning Tree convergence than legacy STP, the
	protocol will exchange information with neighbouring switches
	to quickly transition to forwarding without creating
	loops.
	&os; supports RSTP and STP as operating modes, with RSTP
	being the default mode.</para>

      <para>Spanning Tree can be enabled on member interfaces using
	the <literal>stp</literal> command.  For a bridge with
	<devicename>fxp0</devicename> and
	<devicename>fxp1</devicename> as the current interfaces,
	enable STP with the following:</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 spanning tree
	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> as above 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
	<devicename>fxp0</devicename>.</para>
    </sect2>

    <sect2>
      <title>Advanced Bridging</title>

      <sect3>
	<title>Reconstruct Traffic Flows</title>

	<para>The bridge supports 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.</para>

	<para>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>
      </sect3>

      <sect3>
	<title>Span Ports</title>

	<para>A copy of every Ethernet frame received by the bridge
	  will be transmitted out a designated span port.  The number
	  of span ports configured on a bridge is unlimited, if an
	  interface is designated as a span port then it may not 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.</para>

	<para>To send a copy of all frames out the interface named
	  <devicename>fxp4</devicename>:</para>

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

      <sect3>
	<title>Private Interfaces</title>

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

      <sect3>
	<title>Sticky Interfaces</title>

	<para>If a bridge member interface is marked as sticky then
	  dynamically learned address entries are treated at static
	  once entered into 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 learnt on a particular segment of
	  the bridge can not roam to another segment.</para>

	<para>Another example of using sticky addresses would be to
	  combine the bridge with VLANs to create a router where
	  customer networks are isolated without wasting IP address
	  space.  Consider that
	  <hostid role="hostname">CustomerA</hostid> is on
	  <literal>vlan100</literal> and
	  <hostid role="hostname">CustomerB</hostid> is on
	  <literal>vlan101</literal>.  The bridge has the address
	  <hostid role="ipaddr">192.168.0.1</hostid> and is also an
	  internet router.</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>Both clients see
	  <hostid role="ipaddr">192.168.0.1</hostid> as their default
	  gateway and since the bridge cache is sticky they can not
	  spoof the MAC address of the other customer to intercept
	  their traffic.</para>

	<para>Any communication between the VLANs can be blocked using
	  private interfaces (or a firewall):</para>

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

	<para>The customers are completely isolated from each other,
	  the full <hostid role="netmask">/24</hostid> address range
	  can be allocated without subnetting.</para>
      </sect3>

      <sect3>
	<title>Address Limits</title>

	<para>The number of unique source MAC 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
	  <hostid role="hostname">CustomerA</hostid> on
	  <literal>vlan100</literal> to 10.</para>

	<screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen>
      </sect3>

      <sect3>
	<title>SNMP Monitoring</title>

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

	<para>On the bridge machine uncomment the
	  <literal>begemotSnmpdModulePath."bridge" =
	    "/usr/lib/snmp_bridge.so"</literal> line from
	  <filename>/etc/snmp.config</filename> and start the
	  <application>bsnmpd</application> daemon.  Other
	  configuration such as community names and access lists may
	  need to be modified.  See &man.bsnmpd.1; and
	  &man.snmp.bridge.3; for more information.</para>

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

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

	<para>To monitor a single bridge via the IETF BRIDGE-MIB
	  (RFC4188) do</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
	  which means that the STP 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 one may use the
	  private BEGEMOT-BRIDGE-MIB:</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 do:</para>

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

  <sect1 id="network-aggregation">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Andrew</firstname>
	  <surname>Thompson</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Link Aggregation and Failover</title>

    <indexterm><primary>lagg</primary></indexterm>
    <indexterm><primary>failover</primary></indexterm>
    <indexterm><primary>fec</primary></indexterm>
    <indexterm><primary>lacp</primary></indexterm>
    <indexterm><primary>loadbalance</primary></indexterm>
    <indexterm><primary>roundrobin</primary></indexterm>

    <sect2>
      <title>Introduction</title>

      <para>The &man.lagg.4; interface allows aggregation of multiple
	network interfaces as one virtual interface for the purpose of
	providing fault-tolerance and high-speed links.</para>
    </sect2>

    <sect2>
      <title>Operating Modes</title>

      <variablelist>
	<varlistentry>
	  <term>Failover</term>
	  <listitem>
	    <para>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 is the
	      master port; any interfaces added after that are used as
	      failover devices.  If failover to a non-master port
	      occurs, the original port will become master when it
	      becomes available again.</para>
	  </listitem>
	</varlistentry>

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

	    <para><acronym>FEC</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 VLAN tag,
	      and the IPv4/IPv6 source and destination address.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>LACP</term>
	  <listitem>
	    <para>The &ieee; 802.3ad Link Aggregation Control Protocol
	      (LACP) and the Marker Protocol.  LACP will negotiate a
	      set of aggregable links with the peer in to one or more
	      Link Aggregated Groups (LAG).  Each LAG is composed of
	      ports of the same speed, set to full-duplex operation.
	      The traffic will be balanced across the ports in the LAG
	      with the greatest total speed, in most cases there will
	      only be one LAG which contains all ports.  In the event
	      of changes in physical connectivity, Link Aggregation
	      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 VLAN tag,
	      and the IPv4/IPv6 source and destination address.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Loadbalance</term>
	  <listitem>
	    <para>This is an alias of <emphasis>FEC</emphasis>
	      mode.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Round-robin</term>
	  <listitem>
	    <para>Distributes outgoing traffic using a round-robin
	      scheduler through all active ports and accepts incoming
	      traffic from any active port.  This mode violates
	      Ethernet Frame ordering and should be used with
	      caution.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2>
      <title>Examples</title>

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

	<para>This example connects two interfaces on a &os; machine
	  to the switch as a single load balanced and fault tolerant
	  link.  More interfaces can be added to increase throughput
	  and fault tolerance.  Since frame ordering is mandatory on
	  Ethernet links then 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 across the available
	  interfaces.</para>

	<para>On the &cisco; switch add the
	  <replaceable>FastEthernet0/1</replaceable> and
	  <replaceable>FastEthernet0/2</replaceable> interfaces to the
	  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>Create the &man.lagg.4; interface using
	  <replaceable>fxp0</replaceable> and
	  <replaceable>fxp1</replaceable>, and bring the interfaces up
	  with the IP 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>View the interface status by running:</para>

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

	<para>Ports marked as <emphasis>ACTIVE</emphasis> are part of
	  the active aggregation group that has been negotiated with
	  the remote switch and traffic will be transmitted and
	  received.  Use the verbose output of &man.ifconfig.8; to
	  view the LAG identifiers.</para>

	<screen>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>To see the port status on the switch, use
	  <userinput>show lacp neighbor</userinput>:</para>

	<screen>switch# show lacp neighbor
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 use the <userinput>show lacp neighbor
	  detail</userinput> command.</para>

	<para>To retain this configuration across reboots, the
	  following entries can be added 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 lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting>
      </example>

      <example 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.
	  Bring the underlying physical interfaces up.  Create the
	  &man.lagg.4; interface, using
	  <replaceable>fxp0</replaceable> as the master interface and
	  <replaceable>fxp1</replaceable> as the secondary interface
	  and assign an IP 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 interface will look something like this, the major
	  differences will be the <acronym>MAC</acronym> address and
	  the device names:</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> then
	  <replaceable>fxp1</replaceable> will become the active link.
	  If the link is restored on the master interface then it will
	  once again become the active link.</para>

	<para>To retain this configuration across reboots, the
	  following entries can be added 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 id="networking-lagg-wired-and-wireless">
	<title>Failover Mode Between Wired and Wireless
	  Interfaces</title>

	<para>For laptop users, it is usually desirable to make
	  wireless as a secondary interface, which is to be used when
	  the wired connection is not available.  With &man.lagg.4;,
	  it is possible to use one IP address, prefer the wired
	  connection for both performance and security reasons, while
	  maintaining the ability to transfer data over the wireless
	  connection.</para>

	<para>In this setup, we will need to override the underlying
	  wireless interface's <acronym>MAC</acronym> address to match
	  the &man.lagg.4;'s, which is inherited from the master
	  interface being used, the wired interface.</para>

	<para>In this setup, we will treat the wired interface,
	  <replaceable>bge0</replaceable>, as the master, and the
	  wireless interface, <replaceable>wlan0</replaceable>, as the
	  failover interface.  The <replaceable>wlan0</replaceable>
	  was created from <replaceable>iwn0</replaceable> which we
	  will set up with the wired connection's
	  <acronym>MAC</acronym> address.  The first step would be to
	  obtain the <acronym>MAC</acronym> address from the wired
	  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>You can replace the <replaceable>bge0</replaceable> to
	  match your reality, and will get a different
	  <literal>ether</literal> line which is the
	  <acronym>MAC</acronym> address of your wired interface.
	  Now, we change the underlying wireless interface,
	  <replaceable>iwn0</replaceable>:</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 IP
	  address on it:</para>

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

	<para>Bring the <replaceable>bge0</replaceable> interface up.
	  Create the &man.lagg.4; interface with
	  <replaceable>bge0</replaceable> as master, and failover to
	  <replaceable>wlan0</replaceable> if necessary:</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 interface will look something like this, the major
	  differences will be the <acronym>MAC</acronym> address and
	  the device names:</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 DHCP client to obtain an IP
	  address:</para>

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

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

	<programlisting>ifconfig_bge0="up"
ifconfig_iwn0="ether 00:21:70:da:ae:37"
wlans_iwn0="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 id="network-diskless">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Jean-Fran&ccedil;ois</firstname>
	  <surname>Dock&egrave;s</surname>
	  <contrib>Updated by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Alex</firstname>
	  <surname>Dupre</surname>
	  <contrib>Reorganized and enhanced by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Diskless Operation</title>

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

    <para>A FreeBSD machine can boot over the network and operate
      without a local disk, using file systems mounted from an
      <acronym>NFS</acronym> server.  No system modification is
      necessary, beyond standard configuration files.  Such a system
      is relatively easy to set up because all the necessary elements
      are readily available:</para>

    <itemizedlist>
      <listitem>
	<para>There are at least two possible methods to load the
	  kernel over the network:</para>

	<itemizedlist>
	  <listitem>
	    <para><acronym>PXE</acronym>: The &intel; Preboot
	      eXecution Environment system is a form of smart boot ROM
	      built into some networking cards or motherboards.  See
	      &man.pxeboot.8; for more details.</para>
	  </listitem>

	  <listitem>
	    <para>The <application>Etherboot</application> port
	      (<filename role="package">net/etherboot</filename>)
	      produces ROM-able code to boot kernels over the network.
	      The code can be either burnt into a boot PROM on a
	      network card, or loaded from a local floppy (or hard)
	      disk drive, or from a running &ms-dos; system.  Many
	      network cards are supported.</para>
	  </listitem>
	</itemizedlist>
      </listitem>

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

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

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

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

    <itemizedlist>
      <listitem>
	<para>The diskless workstations use a shared read-only
	  <filename class="directory">/</filename> file system,
	  and a shared read-only
	  <filename class="directory">/usr</filename>.</para>

	<para>The root file system is a copy of a standard FreeBSD
	  root (typically the server's), with some configuration files
	  overridden by ones specific to diskless operation or,
	  possibly, to the workstation they belong to.</para>

	<para>The parts of the root which have to be writable are
	  overlaid with &man.md.4; file systems.  Any changes will be
	  lost when the system reboots.</para>
      </listitem>

      <listitem>
	<para>The kernel is transferred and loaded either with
	  <application>Etherboot</application> or
	  <acronym>PXE</acronym> as some situations may mandate the
	  use of either method.</para>
      </listitem>
    </itemizedlist>

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

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

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

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

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

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

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

      <para>Several operations need to be performed for a successful
	bootstrap:</para>

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

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

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

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

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

	  <itemizedlist>
	    <listitem>

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

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

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

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

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

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

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

      <sect3>
	<title>Configuration Using <application>ISC
	    DHCP</application></title>

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

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

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

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

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

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

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

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

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

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

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

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

      <sect3>
	<title>Configuration Using BOOTP</title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	<para>If you are using <acronym>PXE</acronym> or
	  <application>Etherboot</application> configured to use
	  <acronym>TFTP</acronym>, you need to enable
	  <application>tftpd</application> on the file server:</para>

	<procedure>
	  <step>
	    <para>Create a directory from which
	      <application>tftpd</application> will serve the files,
	      e.g., <filename class="directory">/tftpboot</filename>.</para>
	  </step>

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

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

	    <note>
	      <para>It appears that at least some
		<acronym>PXE</acronym> versions want the
		<acronym>TCP</acronym> version of
		<acronym>TFTP</acronym>.  In this case, add a second
		line, replacing <literal>dgram udp</literal> with
		<literal>stream tcp</literal>.</para>
	    </note>
	  </step>

	  <step>
	    <para>Tell <application>inetd</application> to reread its
	      configuration file.  The
	      <option>inetd_enable="YES"</option> must be in the
	      <filename>/etc/rc.conf</filename> file for this command
	      to execute correctly:</para>

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

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

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

	<procedure>
	  <step>
	    <para>Add this to
	      <filename>/etc/rc.conf</filename>:</para>

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

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

	    <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting>
	  </step>

	  <step>
	    <para>Tell <application>mountd</application> to reread its
	      configuration file.  If you actually needed to enable
	      <acronym>NFS</acronym> in
	      <filename>/etc/rc.conf</filename> at the first step, you
	      probably want to reboot instead.</para>

	    <screen>&prompt.root; <userinput>service mountd restart</userinput></screen>
	  </step>
	</procedure>
      </sect3>

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

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

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

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

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

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

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

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

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

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

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

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

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

	<sect4>
	  <title>Using <command>make world</command> to Populate
	    Root</title>

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

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

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

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

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

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

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

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

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

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

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

	<sect4>
	  <title>Running with a Read-only
	    <filename class="directory">/usr</filename></title>

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

	  <para>If the diskless workstation is configured to run X,
	    you will have to adjust the
	    <application>XDM</application> configuration file, which
	    puts the error log
	    on <filename class="directory">/usr</filename> by
	    default.</para>
	</sect4>

	<sect4>
	  <title>Using a Non-FreeBSD Server</title>

	  <para>When the server for the root file system is not
	    running FreeBSD, you will have to create the root file
	    system on a FreeBSD machine, then copy it to its
	    destination, using <command>tar</command> or
	    <command>cpio</command>.</para>

	  <para>In this situation, there are sometimes problems with
	    the special files
	    in <filename class="directory">/dev</filename>, due to
	    differing major/minor integer sizes.  A solution to this
	    problem is to export a directory from the non-FreeBSD
	    server, mount this directory onto a FreeBSD machine, and
	    use &man.devfs.5; to allocate device nodes transparently
	    for the user.</para>
	</sect4>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="network-pxe-nfs">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Craig</firstname>
	  <surname>Rodrigues</surname>
	  <affiliation>
	    <address>rodrigc@FreeBSD.org</address>
	  </affiliation>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>PXE Booting with an NFS Root File System</title>

    <para>The &intel; Preboot eXecution Environment
      (<acronym>PXE</acronym>) allows booting the operating system
      over the network.  <acronym>PXE</acronym> support is usually
      provided in the <acronym>BIOS</acronym> of modern motherboards,
      where it can be enabled in the <acronym>BIOS</acronym> settings
      which enable booting from the network.  A fully functioning
      <acronym>PXE</acronym> setup also requires properly configured
      <acronym>DHCP</acronym> and <acronym>TFTP</acronym>
      servers.</para>

    <para>When the host computer boots, it receives information over
      <acronym>DHCP</acronym> about where to obtain the initial boot
      loader via TFTP.  After the host computer receives this
      information, it downloads the boot loader via
      <acronym>TFTP</acronym>, and then executes the boot loader.
      This is documented in section 2.2.1 of the <ulink
	url="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot
	Execution Environment (PXE) Specification</ulink>.  In &os;,
      the boot loader retrieved during the <acronym>PXE</acronym>
      process 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.
      Refer to <xref linkend="boot"/> for more information about the
      &os; booting process.</para>

    <sect2>
      <title>Setting Up the <command>chroot</command> Environment for
	the NFS Root File System</title>

      <procedure>
	<step>
	  <para>Choose a directory which will have a &os;
	    installation which will be NFS mountable.  For example, a
	    directory such as
	    <filename class="directory">/b/tftpboot/FreeBSD/install</filename> can be
	    used.</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 NFS server by following the instructions
	    in <xref linkend="network-configuring-nfs"/>.</para>
	</step>

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

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

	<step>
	  <para>Restart the NFS server:</para>

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

	<step>
	  <para>Enable &man.inetd.8; by following the steps outlined
	    in <xref linkend="network-inetd-settings"/>.</para>
	</step>

	<step>
	  <para>Add the following line to
	    <filename>/etc/inetd.conf</filename>:</para>

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

	<step>
	  <para>Restart inetd:</para>

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

	<step>
	  <para><link linkend="makeworld">Rebuild the &os; kernel and
	      userland</link>:</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 PXE:</para>

	  <screen>&prompt.root; <userinput>tftp localhost</userinput>
tftp> <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
	    NFS:</para>

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

	  <para>Replace
	    <replaceable>myhost.example.com</replaceable> with the
	    hostname or IP address of your <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 &man.chroot.8;
	    environment.</para>

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

	  <para>This will set the root password for client
	    machines which are <acronym>PXE</acronym>
	    booting.</para>
	</step>

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

	<step>
	  <para>Perform other customizations of the &man.chroot.8;
	    environment in ${NFSROOTDIR}.  These customizations could
	    include things like adding packages with &man.pkg.add.1;,
	    editing the password file with &man.vipw.8;, or editing
	    &man.amd.conf.5; maps for automounting.  For
	    example:</para>

	  <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput>
&prompt.root; <userinput>pkg_add -r bash</userinput></screen>
	</step>
      </procedure>
    </sect2>

    <sect2>
      <title>Configuring Memory File Systems Used by
	<filename>/etc/rc.initdiskless</filename></title>

      <para>If you boot from an NFS root volume,
	<filename>/etc/rc</filename> detects that you booted over NFS
	and runs the <filename>/etc/rc.initdiskless</filename> script.
	Read the comments in this script to understand what is going
	on.  We need to
	make <filename class="directory">/etc</filename>
	and <filename class="directory">/var</filename>
	memory backed file systems because
	these directories need to be writable, but the NFS 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 class="directory">/etc</filename>
	and <filename class="directory">/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 id="network-pxe-setting-up-dhcp">
      <title>Setting up the DHCP Server</title>

      <para>PXE requires a <acronym>TFTP</acronym> server and a
	<acronym>DHCP</acronym> server to be set up.  The
	<acronym>DHCP</acronym> server does not necessarily need to be
	the same machine as the <acronym>TFTP</acronym> server, but it
	needs to be accessible in your network.</para>

      <procedure>
	<step>
	  <para>Install the <acronym>DHCP</acronym> server by
	    following the instructions documented at
	    <xref linkend="network-dhcp-server"/>.  Make sure that
	    <filename>/etc/rc.conf</filename> and
	    <filename>/usr/local/etc/dhcpd.conf</filename> are
	    correctly configured.</para>
	</step>

	<step>
	  <para>In <filename>/usr/local/etc/dhcpd.conf</filename>,
	    configure the <literal>next-server</literal>,
	    <literal>filename</literal>, and
	    <literal>option root-path</literal> settings, to specify
	    your <acronym>TFTP</acronym> server IP address, the path
	    to <filename>/boot/pxeboot</filename> in
	    <acronym>TFTP</acronym>, and the path to the
	    <acronym>NFS</acronym> root file system.  Here is a sample
	    <filename>dhcpd.conf</filename> setup:</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-server 192.168.35.35, 192.168.35.36 ;
   option domain-name "example.com";

   # IP address of TFTP server
   next-server 192.168.0.1 ;

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

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

}</programlisting>
	</step>
      </procedure>
    </sect2>

    <sect2>
      <title>Configuring the PXE Client and Debugging Connection
	Problems</title>

      <procedure>
	<step>
	  <para>When the client machine boots up, enter the
	    <acronym>BIOS</acronym> configuration menu.  Configure the
	    <acronym>BIOS</acronym> to boot from the network.  If all
	    your previous configuration steps are correct, then
	    everything should &quot;just work&quot;.</para>
	</step>

	<step>

	  <para>Use the
	    <filename role="package">net/wireshark</filename> port to
	    debug the network traffic involved during the
	    <acronym>PXE</acronym> booting process, which is
	    illustrated in the diagram below.  In
	    <xref linkend="network-pxe-setting-up-dhcp"/>, an example
	    configuration is shown where the <acronym>DHCP</acronym>,
	    <acronym>TFTP</acronym>, and <acronym>NFS</acronym>
	    servers are actually on the same machine.  However, these
	    severs can be on separate machines.</para>

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

	    <mediaobjectco>
	      <imageobjectco>
		<areaspec units="calspair">
		  <area id="co-pxenfs1" coords="2873,8133 3313,7266"/>
		  <area id="co-pxenfs2" coords="3519,6333 3885,5500"/>
		  <area id="co-pxenfs3" coords="4780,5866 5102,5200"/>
		  <area id="co-pxenfs4" coords="4794,4333 5102,3600"/>
		  <area 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 DHCPDISCOVER.</para>
		  </callout>
		  <callout arearefs="co-pxenfs2">
		    <para>DHCP server responds with IP address,
		      <literal>next-server</literal>,
		      <literal>filename</literal>, and
		      <literal>root-path</literal>.</para>
		  </callout>
		  <callout arearefs="co-pxenfs3">
		    <para>Client sends <acronym>TFTP</acronym>
		      request to <literal>next-server</literal>
		      asking to retrieve
		      <literal>filename</literal>.</para>
		  </callout>
		  <callout arearefs="co-pxenfs4">
		    <para>TFTP server responds and sends
		      <literal>filename</literal> to client.</para>
		  </callout>
		  <callout arearefs="co-pxenfs5">
		    <para>Client executes
		      <literal>filename</literal> which is
		      &man.pxeboot.8;.  &man.pxeboot.8; loads the
		      kernel.  When the kernel executes, the root
		      filesystem specified by
		      <literal>root-path</literal> is mounted over
		      <acronym>NFS</acronym>.</para>
		  </callout>
		</calloutlist>
	      </imageobjectco>
	    </mediaobjectco>
	  </figure>
	</step>

	<step>
	  <para>Make sure that the <filename>pxeboot</filename> file
	    can be retrieved by <acronym>TFTP</acronym>.  On your
	    <acronym>TFTP</acronym> server, look in
	    <filename>/var/log/xferlog</filename> to ensure that the
	    <filename>pxeboot</filename> file is being retrieved from
	    the correct location.  To test the configuration from
	    <filename>dhcpd.conf</filename> above:</para>

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

	  <para>Read &man.tftpd.8; and &man.tftp.1;.  The
	    <literal>BUGS</literal> sections in these pages 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 configuration from
	    <filename>dhcpd.conf</filename> above:</para>

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

	<step>
	  <para>Read the code in
	    <filename>src/sys/boot/i386/libi386/pxe.c</filename> to
	    understand how the <filename>pxeboot</filename> loader
	    sets variables like <literal>boot.nfsroot.server</literal>
	    and <literal>boot.nfsroot.path</literal>.  These variables
	    are then used in the NFS diskless root mount code in
	    <filename>src/sys/nfsclient/nfs_diskless.c</filename>.</para>
	</step>

	<step>
	  <para>Read &man.pxeboot.8; and &man.loader.8;.</para>
	</step>
      </procedure>
    </sect2>
  </sect1>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      <para>Terminal adapters (TA), are to ISDN what modems are to
	regular phone lines.</para>

      <indexterm><primary>modem</primary></indexterm>
      <para>Most TA's use the standard Hayes modem AT command set, and
	can be used as a drop in replacement for a modem.</para>

      <para>A TA will operate basically the same as a modem except
	connection and throughput speeds will be much faster than your
	old modem.  You will need to configure
	<link linkend="ppp">PPP</link> exactly the same as for a modem
	setup.  Make sure you set your serial speed as high as
	possible.</para>

      <indexterm><primary>PPP</primary></indexterm>
      <para>The main advantage of using a TA to connect to an Internet
	Provider is that you can do Dynamic PPP.  As IP address space
	becomes more and more scarce, most providers are not willing
	to provide you with a static IP any more.  Most stand-alone
	routers are not able to accommodate dynamic IP
	allocation.</para>

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2>
      <title>Stand-alone ISDN Bridges/Routers</title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2 id="network-natoverview">
      <title>Overview</title>

      <indexterm>
	<primary><application>natd</application></primary>
      </indexterm>
      <para>FreeBSD's Network Address Translation daemon, commonly
	known as &man.natd.8; is a daemon that accepts incoming raw IP
	packets, changes the source to the local machine and
	re-injects these packets back into the outgoing IP packet
	stream.  &man.natd.8; does this by changing the source IP
	address and port such that when data is received back, it is
	able to determine the original location of the data and
	forward it back to its original requester.</para>

      <indexterm>
	<primary>Internet connection sharing</primary>
      </indexterm>
      <indexterm>
	<primary>NAT</primary>
      </indexterm>
      <para>The most common use of NAT is to perform what is commonly
	known as Internet Connection Sharing.</para>
    </sect2>

    <sect2 id="network-natsetup">
      <title>Setup</title>

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

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

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

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

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

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

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

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

    <sect2 id="network-natdloaderconfiguration">
      <title>Boot Loader Configuration</title>

      <indexterm>
	<primary>boot loader</primary>
	<secondary>configuration</secondary>
      </indexterm>

      <para>The kernel features for network address translation with
	&man.natd.8; are not enabled in the
	<filename>GENERIC</filename> kernel, but they can be preloaded
	at boot time, by adding a couple of options to
	<filename>/boot/loader.conf</filename>:</para>

      <programlisting>ipfw_load="YES"
ipdivert_load="YES"</programlisting>

      <para>Additionally, the
	<literal>net.inet.ip.fw.default_to_accept</literal> tunable
	option may be set to <literal>1</literal>:</para>

      <programlisting>net.inet.ip.fw.default_to_accept="1"</programlisting>

      <note>
	<para>It is a very good idea to set this option during the
	  first attempts to setup a firewall and NAT gateway.  This
	  way the default policy of &man.ipfw.8; will be
	  <literal>allow ip from any to any</literal> instead of the
	  less permissive <literal>deny ip from any to any</literal>,
	  and it will be slightly more difficult to get locked out of
	  the system right after a reboot.</para>
      </note>
    </sect2>

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

      <indexterm>
	<primary>kernel</primary>
	<secondary>configuration</secondary>
      </indexterm>
      <para>When modules are not an option or if it is preferrable to
	build all the required features into the running kernel, the
	following options must be in the kernel configuration
	file:</para>

      <programlisting>options IPFIREWALL
options IPDIVERT</programlisting>

      <para>Additionally, at choice, the following may also be
	suitable:</para>

      <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSE</programlisting>
    </sect2>

    <sect2 id="network-natdsystemconfiguration">
      <title>System Startup Configuration</title>

      <para>To enable firewall and NAT support at boot time, the
	following must be in <filename>/etc/rc.conf</filename>:</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      <para>The <option>-redirect_port</option> must be passed to
	&man.natd.8; with the proper options.  The syntax is as
	follows:</para>

      <programlisting>     -redirect_port proto targetIP:targetPORT[-targetPORT]
                 [aliasIP:]aliasPORT[-aliasPORT]
                 [remoteIP[:remotePORT[-remotePORT]]]</programlisting>

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

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

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

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

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

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

    <sect2 id="network-natdaddress-redirection">
      <title>Address Redirection</title>

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

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

      <programlisting>-redirect_address localIP publicIP</programlisting>


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

	    <row>
	      <entry>publicIP</entry>
	      <entry>The external IP address corresponding to the LAN
		client.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

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

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

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

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

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

    <title>IPv6</title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

      <para>There are different types of IPv6 addresses: Unicast,
	Anycast and Multicast.</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    <sect2>
      <title>Reading IPv6 Addresses</title>

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

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

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

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

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

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

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

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

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

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

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

	<listitem>
	  <para><ulink url="http://www.sixxs.net">SixXS</ulink> offers
	    tunnels with end-points all around the globe.</para>
	</listitem>

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

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

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

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

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

      <programlisting>MYHOSTNAME           AAAA    MYIPv6ADDR</programlisting>

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

    <sect2>
      <title>Applying the Needed Changes to
	<filename>/etc/rc.conf</filename></title>

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

	<para>These settings will help you configure a machine that
	  will be on your LAN and act as a client, not a router.  To
	  have &man.rtsol.8; autoconfigure your interface on boot on
	  &os;&nbsp;9.<replaceable>x</replaceable> and later,
	  add:</para>

	<programlisting>ipv6_prefer="YES"</programlisting>

	<para>to <filename>rc.conf</filename>.</para>

	<para>For &os;&nbsp;8.<replaceable>x</replaceable> and
	  earlier, add:</para>

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

	<para>To statically assign an IP address such as <hostid
	    role="ip6addr">2001:471:1f11:251:290:27ff:fee0:2093</hostid>,
	  to your <devicename>fxp0</devicename> interface, add the
	  following for
	  &os;&nbsp;9.<replaceable>x</replaceable>:</para>

	<programlisting>ifconfig_fxp0_ipv6="inet6 2001:471:1f11:251:290:27ff:fee0:2093 prefixlen <replaceable>64</replaceable>"</programlisting>

	<note>
	  <para>Be sure to change <replaceable>prefixlen
	      64</replaceable> to the appropriate value for the subnet
	    within which the computer is networked.</para>
	</note>

	<para>For &os;&nbsp;8<replaceable>x</replaceable> and earlier,
	  add:</para>

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

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

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

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

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

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

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

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

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

	<para>To apply the IPv6 address you have been assigned for use
	  as your IPv6 tunnel endpoint, add the following for
	  &os;&nbsp;9.<replaceable>x</replaceable> and later:</para>

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

	<para>For &os;&nbsp;8.<replaceable>x</replaceable> and
	  earlier, add:</para>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  <sect1 id="carp">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Common Address Redundancy Protocol (CARP)</title>

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

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

    <para>To enable support for <acronym>CARP</acronym>, the &os;
      kernel must be rebuilt as described in
      <xref linkend="kernelconfig"/> with the following option:</para>

    <programlisting>device	carp</programlisting>

    <para>Alternatively, the <filename>if_carp.ko</filename> module
      can be loaded at boot time.  Add the following line to the
      <filename>/boot/loader.conf</filename>:</para>

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

    <para><acronym>CARP</acronym> functionality should now be
      available and may be tuned via several <command>sysctl</command>
      <acronym>OID</acronym>s:</para>

    <informaltable frame="none" pgwide="1">
      <tgroup cols="2">
	<thead>
	  <row>
	    <entry>OID</entry>
	    <entry>Description</entry>
	  </row>
	</thead>

	<tbody>
	  <row>
	    <entry><varname>net.inet.carp.allow</varname></entry>
	    <entry>Accept incoming <acronym>CARP</acronym> packets.
	      Enabled by default.</entry>
	  </row>

	  <row>
	    <entry><varname>net.inet.carp.preempt</varname></entry>
	    <entry>This option downs all of the
	      <acronym>CARP</acronym> interfaces on the host when one
	      of them goes down.  Disabled by default</entry>
	  </row>

	  <row>
	    <entry><varname>net.inet.carp.log</varname></entry>
	    <entry>A value of <literal>0</literal> disables any
	      logging.  A Value of <literal>1</literal> enables
	      logging of bad <acronym>CARP</acronym> packets.  Values
	      greater than <literal>1</literal> enables logging of
	      state changes for the <acronym>CARP</acronym>
	      interfaces.  The default value is
	      <literal>1</literal>.</entry>
	  </row>

	  <row>
	    <entry><varname>net.inet.carp.arpbalance</varname></entry>
	    <entry>Balance local network traffic using
	      <acronym>ARP</acronym>.  Disabled by default.</entry>
	  </row>

	  <row>
	    <entry><varname>net.inet.carp.suppress_preempt</varname></entry>
	    <entry>A read only <acronym>OID</acronym> showing the
	      status of preemption suppression.  Preemption can be
	      suppressed if link on an interface is down.  A value of
	      <literal>0</literal>, means that preemption is not
	      suppressed.  Every problem increments this
	      <acronym>OID</acronym>.</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>

    <para>The <acronym>CARP</acronym> devices themselves may be
      created via the <command>ifconfig</command> command:</para>

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

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

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

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

      <para>The two machines should be configured identically other
	than their issued hostnames and <acronym>VHID</acronym>s.
	This example calls these machines
	<hostid>hosta.example.org</hostid> and
	<hostid>hostb.example.org</hostid> respectively.  First, the
	required lines for a <acronym>CARP</acronym> configuration
	have to be added to <filename>rc.conf</filename>.  For
	<hostid>hosta.example.org</hostid>, the
	<filename>rc.conf</filename> file should contain the following
	lines:</para>

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

      <para>On <hostid>hostb.example.org</hostid> the following lines
	should be in <filename>rc.conf</filename>:</para>

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

      <note>
	<para>It is very important that the passwords, specified by
	  the <option>pass</option> option to
	  <command>ifconfig</command>, are identical.  The
	  <devicename>carp</devicename> devices will only listen to
	  and accept advertisements from machines with the correct
	  password.  The <acronym>VHID</acronym> must also be
	  different for each machine.</para>
      </note>

      <para>The third machine, <hostid>provider.example.org</hostid>,
	should be prepared so that it may handle failover from either
	host.  This machine will require two
	<devicename>carp</devicename> devices, one to handle each
	host.  The appropriate <filename>rc.conf</filename>
	configuration lines will be similar to the following:</para>

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

      <para>Having the two <devicename>carp</devicename> devices will
	allow <hostid>provider.example.org</hostid> to notice and pick
	up the <acronym>IP</acronym> address of either machine should
	it stop responding.</para>

      <note>
	<para>The default &os; kernel <emphasis>may</emphasis> have
	  preemption enabled.  If so,
	  <hostid>provider.example.org</hostid> may not relinquish the
	  <acronym>IP</acronym> address back to the original content
	  server.  In this case, an administrator may have to manually
	  force the IP back to the master.  The following command
	  should be issued on
	  <hostid>provider.example.org</hostid>:</para>

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

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

      <para>At this point, <acronym>CARP</acronym> should be
	completely enabled and available for testing.  For testing,
	either networking has to be restarted or the machines need to
	be rebooted.</para>

      <para>More information is always available in the &man.carp.4;
	manual page.</para>
    </sect2>
  </sect1>
</chapter>