Attachment 67136 Details for Bug 99007 – chapter.sgml

chapter.sgml

chapter.sgml (text/plain), 159.71 KB, created by Dennis Olvany on 2006-06-16 06:50:10 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Dennis Olvany

Created: 2006-06-16 06:50:10 UTC

Size: 159.71 KB

patch

obsolete

>
>
><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 address translation.</para>
>      </listitem>
>
>      <listitem>
>	<para>How to connect two computers via PLIP.</para>
>      </listitem>
>
>      <listitem>
>	<para>How to set up IPv6 on a FreeBSD machine.</para>
>      </listitem>
>
>      <listitem>
>	<para>How to configure ATM.</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>You can easily define the default route via the
>	<filename>/etc/rc.conf</filename> file.  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 &man.route.8; manual page.</para>
>    </sect2>
>
>    <sect2>
>      <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>
>
>      <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>
>
><indexterm><primary>BGP</primary></indexterm>
><indexterm><primary>RIP</primary></indexterm>
><indexterm><primary>OSPF</primary></indexterm>
>    </sect2>
>
>    <sect2>
>      <sect2info>
>	<authorgroup>
>	  <author>
>	    <firstname>Al</firstname>
>	    <surname>Hoang</surname>
>	    <contrib>Contributed by </contrib>
>	  </author>
>	</authorgroup>
>      </sect2info>
>      
>      <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/24          link#1             UC          0        0    xl0
>192.168.1/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.  The way to handle the addition of a static route
>	  is to put it in your <filename>/etc/rc.conf</filename>
>	  file:</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>
>      <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>
>      <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>
>      <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>
>    </sect2>
>  </sect1>
>
>  <sect1 id="network-wireless">
>    <sect1info>
>      <authorgroup>
>        <author>
>          <firstname>Eric</firstname>
>          <surname>Anderson</surname>
>          <contrib>Written by </contrib>
>        </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>Introduction</title>
>      <para>It can be very useful to be able to use a computer without the
>      annoyance of having a network cable attached at all times.  FreeBSD can
>      be used as a wireless client, and even as a wireless <quote>access
>      point</quote>.</para>
>   </sect2>
>
>   <sect2>
>     <title>Wireless Modes of Operation</title>
>     <para>There are two different ways to configure 802.11 wireless devices:
>      BSS and IBSS.</para>
>
>     <sect3>
>       <title>BSS Mode</title>
>       <para>BSS mode is the mode that typically is used.  BSS mode is
>        also called infrastructure mode.  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.</para>
>
>       <para>Wireless clients connect to these wireless access
>        points. The IEEE 802.11 standard defines the protocol that
>        wireless networks use to connect.  A wireless client can be
>        tied to a specific network, when a SSID is set.  A wireless
>        client can also attach to any network by not explicitly
>        setting a SSID.</para>
>     </sect3>
>
>     <sect3>
>       <title>IBSS Mode</title>
>       <para>IBSS mode, also called ad-hoc mode, is designed for point
>         to point connections.  There are actually two types of ad-hoc
>         mode.  One is IBSS mode, also called ad-hoc or IEEE ad-hoc
>         mode.  This mode is defined by the IEEE 802.11 standards.
>         The second is called demo ad-hoc mode or Lucent ad-hoc mode
>         (and sometimes, confusingly, ad-hoc mode).  This is the old,
>         pre-802.11 ad-hoc mode and should only be used for legacy
>	 installations.  We will not cover either of the ad-hoc modes
>         further.</para>
>     </sect3>
>   </sect2>
>
>   <sect2>
>     <title>Infrastructure Mode</title>
>     <sect3>
>       <title>Access Points</title>
>
>       <para>Access points are wireless networking devices that allow
>        one or more wireless clients to use the device as a central
>        hub.  When using an access point, all clients communicate
>        through the access point.  Multiple access points are often
>        used to cover a complete area such as a house, business, or
>        park with a wireless network.</para>
>
>       <para>Access points typically have multiple network
>       connections: the wireless card, and one or more wired Ethernet
>       adapters for connection to the rest of the network.
>       </para>
>
>       <para>Access points can either be purchased prebuilt, or you
>        can build your own with FreeBSD and a supported wireless card.
>        Several vendors make wireless access points and wireless cards
>        with various features.</para>
>     </sect3>
>
>     <sect3>
>       <title>Building a FreeBSD Access Point</title>
>       <indexterm><primary>wireless networking</primary>
>         <secondary>access point</secondary>
>       </indexterm>
>
>       <sect4><title>Requirements</title>
>
>         <para>In order to set up a wireless access point with
>          FreeBSD, you need to have a compatible wireless card.
>          Currently, only cards with the Prism chipset are
>          supported. You will also need a wired network card that is
>          supported by FreeBSD (this should not be difficult to find,
>          FreeBSD supports a lot of different devices).  For this
>          guide, we will assume you want to &man.bridge.4; all traffic
>          between the wireless device and the network attached to the
>          wired network card.</para>
>
>	 <para>The hostap functionality that FreeBSD uses to implement
>           the access point works best with certain versions of
>           firmware.  Prism 2 cards should use firmware version 1.3.4
>           or newer.  Prism 2.5 and Prism 3 cards should use firmware
>           1.4.9.  Older versions of the firmware way or may not
>           function correctly.  At this time, the only way to update
>           cards is with &windows; firmware update utilities available
>           from your card's manufacturer.</para>
>       </sect4>
>
>       <sect4>
>         <title>Setting It Up</title>
>         <para>First, make sure your system can see the wireless card:</para>
>         <screen>&prompt.root; <userinput>ifconfig -a</userinput>
>wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
>        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
>        ether 00:09:2d:2d:c9:50
>        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
>        status: no carrier
>        ssid ""
>        stationname "FreeBSD Wireless node"
>        channel 10 authmode OPEN powersavemode OFF powersavesleep 100
>        wepmode OFF weptxkey 1</screen>
>
>         <para>Do not worry about the details now, just make sure it shows you
>          something to indicate you have a wireless card installed.
>	  If you have trouble seeing the wireless interface, and you
>	  are using a PC Card, you may want to check out
>	  &man.pccardc.8; and &man.pccardd.8; manual pages for more
>	  information.</para>
>
>         <para>Next, you will need to load a module in order to get
>          the bridging part of FreeBSD ready for the access point.
>          To load the &man.bridge.4; module, simply run the
>          following command:</para>
>
>         <screen>&prompt.root; <userinput>kldload bridge</userinput></screen>
>
>         <para>It should not have produced any errors when loading the
>          module.  If it did, you may need to compile the
>          &man.bridge.4; code into your kernel.  The <link
>          linkend="network-bridging">Bridging</link> section of this handbook
>          should be able to help you accomplish that task.</para>
>
>         <para>Now that you have the bridging stuff done, we need to
>          tell the FreeBSD kernel which interfaces to bridge together.
>          We do that by using &man.sysctl.8;:</para>
>
>	<screen>&prompt.root; <userinput>sysctl net.link.ether.bridge.enable=1</userinput>
>&prompt.root; <userinput>sysctl net.link.ether.bridge.config="wi0 xl0"</userinput>
>&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>
>
>	<para>On &os; versions earlier than 5.2, you
>	  need to use the following options instead:</para>
>
>	<screen>&prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput>
>&prompt.root; <userinput>sysctl net.link.ether.bridge_cfg="wi0,xl0"</userinput>
>&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>
>
>         <para>Now it is time for the wireless card setup.
>         The following command will set the card into an access point:</para>
>
>         <screen>
>&prompt.root; <userinput>ifconfig wi0 ssid <replaceable>my_net</replaceable> channel 11 media DS/11Mbps mediaopt hostap up stationname "<replaceable>FreeBSD AP</replaceable>"</userinput>
>         </screen>
>
>         <para>The &man.ifconfig.8; line brings the
>	  <devicename>wi0</devicename> interface up, sets its SSID to
>	  <replaceable>my_net</replaceable>, and sets the station name to
>	  <replaceable>FreeBSD AP</replaceable>.  The <option>media
>	  DS/11Mbps</option> sets the card into 11Mbps mode and is
>	  needed for any <option>mediaopt</option> to take effect.
>	  The <option>mediaopt hostap</option> option places the
>	  interface into access point mode.  The <option>channel
>	  11</option> option sets the 802.11b channel to use.  The
>	  &man.wicontrol.8; manual page has valid channel options for
>	  your regulatory domain.
>         </para>
>
>         <para>Now you should have a complete functioning access point
>          up and running.  You are encouraged to read
>          &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for
>          further information.
>         </para>
>
>         <para>It is also suggested that you read the section on encryption that follows.</para>
>       </sect4>
>
>       <sect4>
>         <title>Status Information</title>
>	 <para>Once the access point is configured and operational,
>	   operators will want to see the clients that are associated
>	   with the access point.  At any time, the operator may type:</para>
>
>         <screen>&prompt.root; <userinput>wicontrol -l</userinput>
>1 station:
>00:09:b7:7b:9d:16  asid=04c0, flags=3&lt;ASSOC,AUTH&gt;, caps=1&lt;ESS&gt;, rates=f&lt;1M,2M,5.5M,11M&gt;, sig=38/15
></screen>
>
>         <para>This shows that there is one station associated, along
>           with its parameters.  The signal indicated should be used
>           as a relative indication of strength only.  Its
>           translation to dBm or other units varies between different
>           firmware revisions.</para>
>       </sect4>
>     </sect3>
>
>     <sect3>
>       <title>Clients</title>
>
>       <para>A wireless client is a system that accesses an access
>       point or another client directly. </para>
>
>       <para>Typically, wireless clients only have one network device,
>       the wireless networking card.</para>
>
>       <para>There are a few different ways to configure a wireless
>        client.  These are based on the different wireless modes,
>        generally BSS (infrastructure mode, which requires an access
>        point), and IBSS (ad-hoc, or peer-to-peer mode).  In our
>        example, we will use the most popular of the two, BSS mode, to
>        talk to an access point.</para>
>
>       <sect4>
>       <title>Requirements</title>
>       <para>There is only one real requirement for setting up FreeBSD as a wireless client.
>        You will need a wireless card that is supported by FreeBSD.</para>
>       </sect4>
>
>       <sect4>
>       <title>Setting Up a Wireless FreeBSD Client</title>
>
>       <para>You will need to know a few things about the wireless
>        network you are joining before you start.  In this example, we
>        are joining a network that has a name of
>        <replaceable>my_net</replaceable>, and encryption turned off.</para>
>
>       <note><para>In this example, we are not using encryption, which
>        is a dangerous situation.  In the next section, you will learn
>        how to turn on encryption, why it is important to do so,
>        and why some encryption technologies still do not completely
>        protect you.</para></note>
>
>       <para>Make sure your card is recognized by FreeBSD:</para>
>
>       <screen>&prompt.root; <userinput>ifconfig -a</userinput>
>wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
>        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
>        ether 00:09:2d:2d:c9:50
>        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
>        status: no carrier
>        ssid ""
>        stationname "FreeBSD Wireless node"
>        channel 10 authmode OPEN powersavemode OFF powersavesleep 100
>        wepmode OFF weptxkey 1</screen>
>
>       <para>Now, we can set the card to the correct settings for our
>       network:</para>
>
>       <screen>&prompt.root; <userinput>ifconfig wi0 inet <replaceable>192.168.0.20</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>my_net</replaceable></userinput></screen>
>
>       <para>Replace <hostid role="ipaddr">192.168.0.20</hostid> and
>        <hostid role="netmask">255.255.255.0</hostid> with a valid IP
>        address and netmask on your wired network.  Remember, our
>        access point is bridging the data between the wireless
>        network, and the wired network, so it will appear to the other
>        devices on your network that you are on the wired network just
>        as they are.</para>
>
>       <para>Once you have done that, you should be able to ping hosts
>        on the wired network just as if you were connected using a
>        standard wired connection.</para>
>
>       <para>If you are experiencing problems with your wireless
>        connection, check to make sure that you are associated
>        (connected) to the access point:</para>
>
>       <screen>&prompt.root; <userinput>ifconfig wi0</userinput></screen>
>
>       <para>should return some information, and you should see:</para>
>       <screen>status: associated</screen>
>
>       <para>If it does not show <literal>associated</literal>, then you may be out of
>       range of the access point, have encryption on, or
>       possibly have a configuration problem.</para>
>
>       </sect4>
>     </sect3>
>
>     <sect3>
>      <title>Encryption</title>
>      <indexterm>
>        <primary>wireless networking</primary>
>        <secondary>encryption</secondary>
>      </indexterm>
>
>      <para>Encryption on a wireless network is important because you
>       no longer have the ability to keep the network contained in a
>       well protected area.  Your wireless data will be broadcast
>       across your entire neighborhood, so anyone who cares to read it
>       can.  This is where encryption comes in.  By encrypting the
>       data that is sent over the airwaves, you make it much more
>       difficult for any interested party to grab your data right out
>       of the air. </para>
>
>     <para>The two most common ways to encrypt the data between your
>      client and the access point are WEP, and &man.ipsec.4;.</para>
>
>     <sect4>
>     <title>WEP</title>
>      <indexterm><primary>WEP</primary></indexterm>
>
>      <para>WEP is an abbreviation for Wired Equivalency Protocol.
>       WEP is an attempt to make wireless networks as safe and secure
>       as a wired network.  Unfortunately, it has been cracked, and is
>       fairly trivial to break.  This also means it is not something
>       to rely on when it comes to encrypting sensitive data.  </para>
>
>      <para>It is better than nothing, so use the following to turn on
>       WEP on your new FreeBSD access point:</para>
>
>      <screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid <replaceable>my_net</replaceable> wepmode on wepkey <replaceable>0x1234567890</replaceable> media DS/11Mbps mediaopt hostap</userinput></screen>
>
>      <para>And you can turn on WEP on a client with this command:</para>
>
>      <screen>&prompt.root; <userinput>ifconfig wi0 inet <replaceable>192.168.0.20</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>my_net</replaceable> wepmode on wepkey <replaceable>0x1234567890</replaceable></userinput></screen>
>
>      <para>Note that you should replace the <replaceable>0x1234567890</replaceable> with a more unique key.</para>
>
>     </sect4>
>
>     <sect4>
>     <title>IPsec</title>
>
>     <para>&man.ipsec.4; is a much more robust and powerful tool for
>       encrypting data across a network.  This is definitely the
>       preferred way to encrypt data over a wireless network.  You can
>       read more about &man.ipsec.4; security and how to implement it
>       in the <link linkend="ipsec">IPsec</link> section of this
>       handbook.</para>
>     </sect4>
>    </sect3>
>
>    <sect3>
>    <title>Tools</title>
>
>    <para>There are a small number of tools available for use in
>      debugging and setting up your wireless network, and here we will
>      attempt to describe some of them and what they do.</para>
>
>    <sect4>
>    <title>The <application>bsd-airtools</application> Package</title>
>
>    <para>The <application>bsd-airtools</application> package is a
>      complete toolset that includes wireless auditing tools for WEP
>      key cracking, access point detection, etc.</para>
>
>    <para>The <application>bsd-airtools</application> utilities can be
>      installed from the <filename
>      role="package">net-mgmt/bsd-airtools</filename> port.  Information on
>      installing ports can be found in <xref linkend="ports"> of this
>      handbook.</para>
>
>    <para>The program <command>dstumbler</command> is the packaged
>      tool that allows for access point discovery and signal to noise
>      ratio graphing.  If you are having a hard time getting your
>      access point up and running, <command>dstumbler</command> may
>      help you get started.</para>
>
>    <para>To test your wireless network security, you may choose to
>      use <quote>dweputils</quote> (<command>dwepcrack</command>,
>      <command>dwepdump</command> and <command>dwepkeygen</command>)
>      to help you determine if WEP is the right solution to your
>      wireless security needs.</para>
>
>    </sect4>
>
>    <sect4>
>    <title>The <command>wicontrol</command>, <command>ancontrol</command> and <command>raycontrol</command> Utilities</title>
>
>    <para>These are the tools you can use to control how your wireless
>      card behaves on the wireless network.  In the examples above, we
>      have chosen to use &man.wicontrol.8;, since our wireless card is
>      a <devicename>wi0</devicename> interface.  If you had a Cisco
>      wireless device, it would come up as
>      <devicename>an0</devicename>, and therefore you would use
>      &man.ancontrol.8;.</para>
>
>    </sect4>
>
>    <sect4>
>    <title>The <command>ifconfig</command> Command</title>
>    <indexterm><primary>ifconfig</primary></indexterm>
>
>    <para>The &man.ifconfig.8; command can be used to do many of the same options
>      as &man.wicontrol.8;, however it does lack a few options.  Check
>      &man.ifconfig.8; for command line parameters and options.</para>
>
>    </sect4>
>
>    </sect3>
>
>    <sect3>
>    <title>Supported Cards</title>
>    <sect4>
>    <title>Access Points</title>
>
>    <para>The only cards that are currently supported for BSS (as an
>      access point) mode are devices based on the Prism 2, 2.5, or 3
>      chipsets. For a complete list, look at &man.wi.4;.</para>
>
>    </sect4>
>
>    <sect4>
>    <title>802.11b Clients</title>
>
>    <para>Almost all 802.11b wireless cards are currently supported
>      under FreeBSD.  Most cards based on Prism, Spectrum24, Hermes,
>      Aironet, and Raylink will work as a wireless network card in
>      IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>
>
>    </sect4>
>
>    <sect4>
>    <title>802.11a &amp; 802.11g Clients</title>
>
>    <para>The &man.ath.4; device driver supports 802.11a and 802.11g. 
>      If your card is based on an Atheros chipset, you may
>      be able to use this driver.</para>
>
>    <para>Unfortunately, there are still many vendors that do not
>      provide schematics for their drivers to the open source
>      community because they regard such information as trade
>      secrets. Consequently, the developers of FreeBSD and other
>      operating systems are left two choices: develop the drivers by
>      a long and pain-staking process of reverse engineering or using
>      the existing driver binaries available for the
>      &microsoft.windows; platforms. Most developers, including those
>      involved with FreeBSD, have taken the latter approach.</para>
>
>    <para>Thanks to the contributions of Bill Paul (wpaul), as of
>      FreeBSD&nbsp;5.3-RELEASE there is <quote>native</quote>
>      support for the Network Driver Interface Specification
>      (NDIS). The FreeBSD NDISulator (otherwise known as Project Evil)
>      takes a &windows; driver binary and basically tricks it into
>      thinking it is running on &windows;.  This feature is still
>      relatively new, but most test cases seem to work
>      adequately.</para>
>
>    <indexterm><primary>NDIS</primary></indexterm>
>    <indexterm><primary>NDISulator</primary></indexterm>
>    <indexterm><primary>&windows; drivers</primary></indexterm>
>    <indexterm><primary>Microsoft Windows</primary></indexterm>
>    <indexterm><primary>Microsoft Windows</primary>
>	<secondary>device drivers</secondary></indexterm>
>    <indexterm><primary>KLD (kernel loadable object)</primary></indexterm>
>
>
>    <para>In order to use the NDISulator, you need three things:</para>
>
>    <orderedlist>
>     <listitem>
>      <para>Kernel sources</para>
>     </listitem>
>     <listitem>
>      <para>&windowsxp; driver binary 
>        (<filename>.SYS</filename> extension)</para>
>     </listitem>
>     <listitem>
>      <para>&windowsxp; driver configuration file 
>        (<filename>.INF</filename> extension)</para>
>     </listitem>
>    </orderedlist>
> 
>      <para>You may need to compile the &man.ndis.4; mini port driver 
>        wrapper module. As <username>root</username>:</para> 
>
>    <screen>&prompt.root; <userinput>cd /usr/src/sys/modules/ndis</userinput>
>&prompt.root; <userinput>make &amp;&amp; make install</userinput></screen>
>
>    <para>Locate the files for your specific card. Generally, they can
>      be found on the included CDs or at the vendors' websites. In the
>      following examples, we will use
>      <filename>W32DRIVER.SYS</filename> and
>      <filename>W32DRIVER.INF</filename>.</para>
>
>    <para>The next step is to compile the driver binary into a
>      loadable kernel module. To accomplish this, as
>      <username>root</username>, go into the
>      <filename>if_ndis</filename> module directory and copy the
>      &windows; driver files into it:</para>
>
>   <screen>&prompt.root; <userinput>cd /usr/src/sys/modules/if_ndis</userinput>
>&prompt.root; <userinput>cp <replaceable>/path/to/driver/W32DRIVER.SYS</replaceable> ./</userinput>
>&prompt.root; <userinput>cp <replaceable>/path/to/driver/W32DRIVER.INF</replaceable> ./</userinput></screen>
>
>    <para>We will now use the <command>ndiscvt</command> utility to
>      create the driver definition header
>      <filename>ndis_driver_data.h</filename> to build the
>      module:</para>
>
>    <screen>&prompt.root; <userinput>ndiscvt -i <replaceable>W32DRIVER.INF</replaceable> -s <replaceable>W32DRIVER.SYS</replaceable> -o ndis_driver_data.h</userinput></screen>
>
>    <para>The <option>-i</option> and <option>-s</option> options specify 
>      the configuration and binary files, respectively. We use the 
>      <option>-o ndis_driver_data.h</option> option because the 
>      <filename>Makefile</filename> will be looking for this file when it 
>      comes time to build the module. </para>
>
>    <note>
>      <para>Some &windows; drivers require additional files to operate. You
>        may include them with <command>ndiscvt</command> by using the 
>        <option>-f</option> option. Consult the &man.ndiscvt.8; manual page 
>        for more information.</para>
>    </note>
>
>    <para>Finally, we can build and install the driver module:</para>
>
>    <screen>&prompt.root; <userinput>make &amp;&amp; make install</userinput></screen>
>
>    <para>To use the driver, you must load the appropriate modules:</para>
>
>    <screen>&prompt.root; <userinput>kldload ndis</userinput>
>&prompt.root; <userinput>kldload if_ndis</userinput></screen>
>
>    <para>The first command loads the NDIS miniport driver wrapper,
>      the second loads the actual network interface.  Check
>      &man.dmesg.8; to see if there were any errors loading.  If all
>      went well, you should get output resembling the
>      following:</para>
>
>    <screen>ndis0: &lt;Wireless-G PCI Adapter&gt; mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1
>ndis0: NDIS API version: 5.0
>ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5
>ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps
>ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen>
>  
>    <para>From here you can treat the <devicename>ndis0</devicename> device 
>      like any other wireless device (e.g. <devicename>wi0</devicename>) and 
>      consult the earlier sections of this chapter.</para>
>    
>    </sect4>
>
>    </sect3>
>   </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>
>
>      <note>
>	<para>The Bluetooth stack has to be started manually on &os; 6.0, and
>	  on &os; 5.X before 5.5.  It is done automatically from &man.devd.8;
>	  on &os; 5.5, 6.1 and newer.</para>
>
>      <para>Copy
>        <filename>/usr/share/examples/netgraph/bluetooth/rc.bluetooth</filename>
>        into some convenient place, like <filename>/etc/rc.bluetooth</filename>.
>        This script 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>/etc/rc.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>
>      </note>
>
>    </sect2>
>
>    <indexterm><primary>HCI</primary></indexterm>
>    <sect2>
>      <title>Host Controller Interface (HCI)</title>
>
>      <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>
>
>    <indexterm><primary>L2CAP</primary></indexterm>
>    <sect2>
>      <title>Logical Link Control and Adaptation Protocol (L2CAP)</title>
>
>      <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>
>
>    <indexterm><primary>RFCOMM</primary></indexterm>
>    <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>
>
>    <indexterm><primary>pairing</primary></indexterm>
>    <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>On &os; 5.5, 6.1 and newer, 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>
>
>    <indexterm><primary>SDP</primary></indexterm>
>    <sect2>
>      <title>Service Discovery Protocol (SDP)</title>
>      <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. On &os; 5.5, 6.1 and newer, 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>/etc/rc.d/sdpd start</userinput></screen>
>
>      <para>On &os; 6.0, and on &os; 5.X before 5.5,
>	<application>sdpd</application> is not integrated into the system
>	startup scripts.  It has to be started manually with:</para>
>
>      <screen>&prompt.root; <userinput>sdpd</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>
>
>    <indexterm><primary>OBEX</primary></indexterm>
>    <sect2>
>      <title>OBEX Object Push (OPUSH) Profile</title>
>      <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>/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>Steve</firstname>
>      	  <surname>Peterson</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 two common situations in which a bridge is used
>	today.</para>
>
>      <sect3>
>	<title>High Traffic on a Segment</title>
>
>	<para>Situation one is where your physical network segment is
>	  overloaded with traffic, but you do not want for whatever reason to
>	  subnet the network and interconnect the subnets with a
>	  router.</para>
>
>	<para>Let us consider an example of a newspaper where the Editorial and
>	  Production departments are on the same subnetwork.  The Editorial
>	  users all use server <hostid>A</hostid> for file service, and the Production users
>	  are on server <hostid>B</hostid>.  An Ethernet network is used to connect all users together,
>	  and high loads on the network are slowing things down.</para>
>
>	<para>If the Editorial users could be segregated on one
>	  network segment and the Production users on another, the two
>	  network segments could be connected with a bridge.  Only the
>	  network traffic destined for interfaces on the
>	  <quote>other</quote> side of the bridge would be sent to the
>	  other network, reducing congestion on each network
>	  segment.</para>
>      </sect3>
>
>      <sect3>
>	<title>Filtering/Traffic Shaping Firewall</title>
>	<indexterm><primary>firewall</primary></indexterm>
>	<indexterm><primary>NAT</primary></indexterm>
>
>	<para>The second common situation is where firewall functionality is
>	  needed without 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>
>    </sect2>
>
>    <sect2>
>      <title>Configuring a Bridge</title>
>
>      <sect3>
>	<title>Network Interface Card Selection</title>
>
>	<para>A bridge requires at least two network cards to function.
>	  Unfortunately, not all network interface cards
>	  support bridging.  Read &man.bridge.4; for details on the cards that
>	  are supported.</para>
>
>	<para>Install and test the two network cards before continuing.</para>
>      </sect3>
>
>      <sect3>
>	<title>Kernel Configuration Changes</title>
>	<indexterm>
>	  <primary>kernel options</primary>
>	  <secondary>BRIDGE</secondary>
>	</indexterm>
>
>	<para>To enable kernel support for bridging, add the:</para>
>
>	<programlisting>options BRIDGE</programlisting>
>
>	<para>statement to your kernel configuration file, and rebuild your
>	  kernel.</para>
>      </sect3>
>
>      <sect3>
>	<title>Firewall Support</title>
>	<indexterm><primary>firewall</primary></indexterm>
>	<para>If you are planning to use the bridge as a firewall, you
>	  will need to add the <literal>IPFIREWALL</literal> option as
>	  well.  Read <xref linkend="firewalls"> for general
>	  information on configuring the bridge as a firewall.</para>
>
>	<para>If you need to allow non-IP packets (such as ARP) to flow
>	  through the bridge, there is a firewall option that
>	  must be set.  This option is
>	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this
>	  changes the default rule for the firewall to accept any packet.
>	  Make sure you know how this changes the meaning of your ruleset
>	  before you set it.</para>
>      </sect3>
>
>      <sect3>
>	<title>Traffic Shaping Support</title>
>
>	<para>If you want to use the bridge as a traffic shaper, you will need
>	  to add the <literal>DUMMYNET</literal> option to your kernel
>	  configuration.  Read &man.dummynet.4; for further
>	  information.</para>
>      </sect3>
>    </sect2>
>
>    <sect2>
>      <title>Enabling the Bridge</title>
>
>      <para>Add the line:</para>
>
>      <programlisting>net.link.ether.bridge.enable=1</programlisting>
>
>      <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
>	runtime, and the line:</para>
>
>      <programlisting>net.link.ether.bridge.config=<replaceable>if1</replaceable>,<replaceable>if2</replaceable></programlisting>
>
>      <para>to enable bridging on the specified interfaces (replace
>	<replaceable>if1</replaceable> and
>	<replaceable>if2</replaceable> with the names of your two
>	network interfaces).  If you want the bridged packets to be
>	filtered by &man.ipfw.8;, you should add:</para>
>
>      <programlisting>net.link.ether.bridge.ipfw=1</programlisting>
>
>      <para>as well.</para>
>
>      <para>For versions prior to &os;&nbsp;5.2-RELEASE, use instead the following
>	lines:</para>
>
>      <programlisting>net.link.ether.bridge=1
>net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable>
>net.link.ether.bridge_ipfw=1</programlisting>
>
>    </sect2>
>    
>    <sect2>
>      <title>Other Information</title>
>
>      <para>If you want to be able to &man.ssh.1; into the bridge from the network,
>	it is correct to assign one of the network cards an IP address.  The
>	consensus is that assigning both cards an address is a bad
>	idea.</para>
>
>      <para>If you have multiple bridges on your network, there cannot be more
>	than one path between any two workstations.  Technically, this means
>	that there is no support for spanning tree link management.</para>
>
>      <para>A bridge can add latency to your &man.ping.8; times, especially for
>        traffic from one segment to another.</para>
>      
>    </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>/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>/</filename> file system, and a shared
>	  read-only <filename>/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
>  	    3.0</application> is not part of the base
>	    system.  You will first need to install the
>	    <filename role="package">net/isc-dhcp3-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 role="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>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 undocumented <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>/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>/etc/rc.d/inetd restart</userinput></screen>
>	  </step>
>        </procedure>
>
>	<para>You can place the <filename>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>/etc/rc.d/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
>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>/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>/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>/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-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 <filename>/usr/share/examples/isdn/</filename>
>	directory on your FreeBSD system or 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 anymore.  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 v.s. 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-natdkernconfiguration">
>      <indexterm>
>        <primary>kernel</primary>
>	<secondary>configuration</secondary>
>      </indexterm>
>      <title>Configuration</title>
>      <para>NAT configuration entails only a short series of commands:</para>
>      <programlisting>kldload ipfw
>kldload ipdivert
>sysctl net.inet.ip.forwarding=1
>natd -dynamic -n <replaceable>fxp0</replaceable>
>ipfw add divert natd ip4 from any to any via <replaceable>fxp0</replaceable>
>ipfw add allow ip from any to any</programlisting>
>
>      <para>Additionally, at choice, support may be compiled into the kernel:</para>
>      <programlisting>options IPFIREWALL
>options IPDIVERT
>options IPFIREWALL_DEFAULT_TO_ACCEPT
>options IPFIREWALL_VERBOSE</programlisting>
>
>      <para>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-plip">
>    <title>Parallel Line IP (PLIP)</title>
>
>    <indexterm><primary>PLIP</primary></indexterm>
>    <indexterm>
>      <primary>Parallel Line IP</primary>
>      <see>PLIP</see>
>    </indexterm>
>
>    <para>PLIP lets us run TCP/IP between parallel ports.  It is
>      useful on machines without network cards, or to install on
>      laptops.  In this section, we will discuss:</para>
>
>    <itemizedlist>
>      <listitem>
>	<para>Creating a parallel (laplink) cable.</para>
>      </listitem>
>
>      <listitem>
>	<para>Connecting two computers with PLIP.</para>
>      </listitem>
>    </itemizedlist>
>
>    <sect2 id="network-create-parallel-cable">
>      <title>Creating a Parallel Cable</title>
>
>      <para>You can purchase a parallel cable at most computer supply
>        stores.  If you cannot do that, or you just want to know how
>        it is done, the following table shows how to make one out of a normal parallel
>        printer cable.</para>
>
>      <table frame="none">
>	<title>Wiring a Parallel Cable for Networking</title>
>
>	<tgroup cols="5">
>	  <thead>
>	    <row>
>	      <entry>A-name</entry>
>
>	      <entry>A-End</entry>
>
>	      <entry>B-End</entry>
>
>	      <entry>Descr.</entry>
>
>	      <entry>Post/Bit</entry>
>	    </row>
>	  </thead>
>
>	  <tbody>
>	    <row>
>	      <entry><literallayout>DATA0
>-ERROR</literallayout></entry>
>
>	      <entry><literallayout>2
>15</literallayout></entry>
>
>	      <entry><literallayout>15
>2</literallayout></entry>
>
>	      <entry>Data</entry>
>
>	      <entry><literallayout>0/0x01
>1/0x08</literallayout></entry>
>	    </row>
>
>	    <row>
>	      <entry><literallayout>DATA1
>+SLCT</literallayout></entry>
>
>	      <entry><literallayout>3
>13</literallayout></entry>
>
>	      <entry><literallayout>13
>3</literallayout></entry>
>
>	      <entry>Data</entry>
>
>	      <entry><literallayout>0/0x02
>1/0x10</literallayout></entry>
>	    </row>
>
>	    <row>
>	      <entry><literallayout>DATA2
>+PE</literallayout></entry>
>
>	      <entry><literallayout>4
>12</literallayout></entry>
>
>	      <entry><literallayout>12
>4</literallayout></entry>
>
>	      <entry>Data</entry>
>
>	      <entry><literallayout>0/0x04
>1/0x20</literallayout></entry>
>	    </row>
>
>	    <row>
>	      <entry><literallayout>DATA3
>-ACK</literallayout></entry>
>
>	      <entry><literallayout>5
>10</literallayout></entry>
>
>	      <entry><literallayout>10
>5</literallayout></entry>
>
>	      <entry>Strobe</entry>
>
>	      <entry><literallayout>0/0x08
>1/0x40</literallayout></entry>
>	    </row>
>
>	    <row>
>	      <entry><literallayout>DATA4
>BUSY</literallayout></entry>
>
>	      <entry><literallayout>6
>11</literallayout></entry>
>
>	      <entry><literallayout>11
>6</literallayout></entry>
>
>	      <entry>Data</entry>
>
>	      <entry><literallayout>0/0x10
>1/0x80</literallayout></entry>
>	    </row>
>
>	    <row>
>	      <entry>GND</entry>
>
>	      <entry>18-25</entry>
>
>	      <entry>18-25</entry>
>
>	      <entry>GND</entry>
>
>	      <entry>-</entry>
>	    </row>
>	  </tbody>
>	</tgroup>
>      </table>
>    </sect2>
>
>    <sect2 id="network-plip-setup">
>      <title>Setting Up PLIP</title>
>
>      <para>First, you have to get a laplink cable.
>	Then, confirm that both computers have a kernel with &man.lpt.4; driver
>	support:</para>
>
>      <screen>&prompt.root; <userinput>grep lp /var/run/dmesg.boot</userinput>
>lpt0: &lt;Printer&gt; on ppbus0
>lpt0: Interrupt-driven port</screen>
>
>      <para>The parallel port must be an interrupt driven port,
>	you should have a line similar to the
>	following in your in the
>	<filename>/boot/device.hints</filename> file:</para>
>
>      <programlisting>hint.ppc.0.at="isa"
>hint.ppc.0.irq="7"</programlisting>
>
>      <para>Then check if the kernel configuration file has a
>	<literal>device plip</literal> line or if the
>	<filename>plip.ko</filename> kernel module is loaded.  In both
>	cases the parallel networking interface should appear when you
>	use the &man.ifconfig.8; command to display it:</para>
>
>      <screen>&prompt.root; <userinput>ifconfig plip0</userinput>
>plip0: flags=8810&lt;POINTOPOINT,SIMPLEX,MULTICAST&gt; mtu 1500</screen>
>
>      <para>Plug the laplink cable into the parallel interface on
>	both computers.</para>
>
>      <para>Configure the network interface parameters on both
>	sites as <username>root</username>.  For example, if you want to connect
>	the host <hostid>host1</hostid> with another machine <hostid>host2</hostid>:</para>
>
>      <programlisting>                 host1 &lt;-----&gt; host2
>IP Address    10.0.0.1      10.0.0.2</programlisting>
>
>      <para>Configure the interface on <hostid>host1</hostid> by doing:</para>
>
>      <screen>&prompt.root; <userinput>ifconfig plip0 10.0.0.1 10.0.0.2</userinput></screen>
>
>      <para>Configure the interface on <hostid>host2</hostid> by doing:</para>
>
>      <screen>&prompt.root; <userinput>ifconfig plip0 10.0.0.2 10.0.0.1</userinput></screen>
>
>
>      <para>You now should have a working connection.  Please read the
>        manual pages &man.lp.4; and &man.lpt.4; for more details.</para>
>
>      <para>You should also add both hosts to
>	<filename>/etc/hosts</filename>:</para>
>
>      <programlisting>127.0.0.1               localhost.my.domain localhost
>10.0.0.1                host1.my.domain host1
>10.0.0.2                host2.my.domain</programlisting>
>
>      <para>To confirm the connection works, go to each host and ping
>	the other.  For example, on <hostid>host1</hostid>:</para>
>
>          <screen>&prompt.root; <userinput>ifconfig plip0</userinput>
>plip0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
>        inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
>&prompt.root; <userinput>netstat -r</userinput>
>Routing tables
>
>Internet:
>Destination        Gateway          Flags     Refs     Use      Netif Expire
>host2              host1            UH          0       0       plip0
>&prompt.root; <userinput>ping -c 4 host2</userinput>
>PING host2 (10.0.0.2): 56 data bytes
>64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
>64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
>64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
>64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
>
>--- host2 ping statistics ---
>4 packets transmitted, 4 packets received, 0% packet loss
>round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>
>
>    </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 know as IPng <quote>IP next generation</quote>) is
>      the new version of the well known IP protocol (also know 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
>	  anymore 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>IPv6 overview at <ulink url="http://playground.sun.com/pub/ipng/html/ipng-main.html">playground.sun.com</ulink></para>
>      </listitem>
>
>      <listitem>
>	<para><ulink url="http://www.kame.net">KAME.net</ulink></para>
>      </listitem>
>
>      <listitem>
>	<para><ulink url="http://www.6bone.net">6bone.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>Join the experimental 6bone</para>
>	</listitem>
>
>	<listitem>
>	  <para>Getting an IPv6 network from your upstream provider.  Talk to your
>	    Internet provider for instructions.</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>
>
>      <para>Here we will talk on how to connect to the 6bone since it currently seems
>	to be the most popular way.</para>
>
>      <para>First take a look at the <ulink url="http://www.6bone.net/">6bone</ulink> site and find a 6bone connection nearest to
>	you.  Write to the responsible person and with a little bit of luck you
>	will be given instructions on how to set up your connection.  Usually this
>	involves setting up a GRE (gif) tunnel.</para>
>
>      <para>Here is a typical example on setting up a &man.gif.4; tunnel:</para>
>
>      <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput>
>&prompt.root; <userinput>ifconfig gif0</userinput>
>gif0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1280
>&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>MY_IPv4_ADDR MY_IPv4_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable></userinput>
>&prompt.root; <userinput>ifconfig gif0 inet6 alias <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable></userinput></screen>
>
>      <para>Replace the capitalized words by the information you received from the
>	upstream 6bone node.</para>
>
>      <para>This establishes the tunnel.  Check if the tunnel is working by &man.ping6.8;
>	'ing <hostid role="ip6addr">ff02::1%gif0</hostid>.  You should receive two ping replies.</para>
>
>	<note><para>In case you are intrigued by the address <hostid role="ip6addr">ff02:1%gif0</hostid>, this is a
>	  multicast address.  <literal>%gif0</literal> states that the multicast address at network
>	  interface <devicename>gif0</devicename> is to be used.  Since we <command>ping</command> a multicast address the
>	  other endpoint of the tunnel should reply as well.</para></note>
>
>      <para>By now setting up a route to your 6bone uplink should be rather
>	straightforward:</para>
>
>      <screen>&prompt.root; <userinput>route add -inet6 default -interface gif0</userinput>
>&prompt.root; <userinput>ping6 -n <replaceable>MY_UPLINK</replaceable></userinput></screen>
>
>      <screen>&prompt.root; <userinput>traceroute6 www.jp.FreeBSD.org</userinput>
>(3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
>     1  atnet-meta6  14.147 ms  15.499 ms  24.319 ms
>     2  6bone-gw2-ATNET-NT.ipv6.tilab.com  103.408 ms  95.072 ms *
>     3  3ffe:1831:0:ffff::4  138.645 ms  134.437 ms  144.257 ms
>     4  3ffe:1810:0:6:290:27ff:fe79:7677  282.975 ms  278.666 ms  292.811 ms
>     5  3ffe:1800:0:ff00::4  400.131 ms  396.324 ms  394.769 ms
>     6  3ffe:1800:0:3:290:27ff:fe14:cdee  394.712 ms  397.19 ms  394.102 ms</screen>
>
>      <para>This output will differ from machine to machine.  By now you should be
>	able to reach the IPv6 site <ulink url="http://www.kame.net">www.kame.net</ulink>
>	and see the dancing tortoise &mdash; that is if you have a IPv6 enabled browser such as
>	<filename role="package">www/mozilla</filename>, <application>Konqueror</application>,
>	which is part of <filename role="package">x11/kdebase3</filename>,
>	or <filename role="package">www/epiphany</filename>.</para>
>
>    </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 all you need to add is:</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:</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,
>	  such as the <ulink url="http://www.6bone.net/">6bone</ulink>, 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:</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>
></chapter>
>
>
>

Actions: View

Attachments on bug 99007: 67136