diff options
Diffstat (limited to 'en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml | 6493 |
1 files changed, 6493 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml new file mode 100644 index 0000000000..de262b5ddf --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml @@ -0,0 +1,6493 @@ +<?xml version="1.0" encoding="iso-8859-1" standalone="no"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="advanced-networking"> + <title>Advanced Networking</title> + + <sect1 id="advanced-networking-synopsis"> + <title>Synopsis</title> + + <para>This chapter will cover a number of advanced networking + topics.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The basics of gateways and routes.</para> + </listitem> + + <listitem> + <para>How to set up &ieee; 802.11 and &bluetooth; + devices.</para> + </listitem> + + <listitem> + <para>How to make FreeBSD act as a bridge.</para> + </listitem> + + <listitem> + <para>How to set up network booting on a diskless + machine.</para> + </listitem> + + <listitem> + <para>How to set up network PXE booting with an NFS root file + system.</para> + </listitem> + + <listitem> + <para>How to set up network address translation.</para> + </listitem> + + <listitem> + <para>How to 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> + + <listitem> + <para>How to enable and utilize the features of CARP, the + Common Address Redundancy Protocol in &os;</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand the basics of the + <filename>/etc/rc</filename> scripts.</para> + </listitem> + + <listitem> + <para>Be familiar with basic network terminology.</para> + </listitem> + + <listitem> + <para>Know how to configure and install a new FreeBSD kernel + (<xref linkend="kernelconfig"/>).</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports"/>).</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 id="network-routing"> + <sect1info> + <authorgroup> + <author> + <firstname>Coranth</firstname> + <surname>Gryphon</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Gateways and Routes</title> + + <indexterm><primary>routing</primary></indexterm> + <indexterm><primary>gateway</primary></indexterm> + <indexterm><primary>subnet</primary></indexterm> + + <para>For one machine to be able to find another over a network, + there must be a mechanism in place to describe how to get from + one to the other. This is called + <firstterm>routing</firstterm>. A <quote>route</quote> is a + defined pair of addresses: a <quote>destination</quote> and a + <quote>gateway</quote>. The pair indicates that if you are + trying to get to this <emphasis>destination</emphasis>, + communicate through this <emphasis>gateway</emphasis>. There + are three types of destinations: individual hosts, subnets, and + <quote>default</quote>. The <quote>default route</quote> is + used if none of the other routes apply. We will talk a little + bit more about default routes later on. There are also three + types of gateways: individual hosts, interfaces (also called + <quote>links</quote>), and Ethernet hardware addresses (MAC + addresses).</para> + + <sect2> + <title>An Example</title> + + <para>To illustrate different aspects of routing, we will use + the following example from <command>netstat</command>:</para> + + <screen>&prompt.user; <userinput>netstat -r</userinput> +Routing tables + +Destination Gateway Flags Refs Use Netif Expire + +default outside-gw UGSc 37 418 ppp0 +localhost localhost UH 0 181 lo0 +test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 +10.20.30.255 link#1 UHLW 1 2421 +example.com link#1 UC 0 0 +host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 +host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => +host2.example.com link#1 UC 0 0 +224 link#1 UC 0 0</screen> + + <indexterm><primary>default route</primary></indexterm> + <para>The first two lines specify the default route (which we + will cover in the + <link linkend="network-routing-default">next section</link>) + and the <hostid>localhost</hostid> route.</para> + + <indexterm><primary>loopback device</primary></indexterm> + <para>The interface (<literal>Netif</literal> column) that this + routing table specifies to use for + <literal>localhost</literal> is <devicename>lo0</devicename>, + also known as the loopback device. This says to keep all + traffic for this destination internal, rather than sending it + out over the LAN, since it will only end up back where it + started.</para> + + <indexterm> + <primary>Ethernet</primary> + <secondary>MAC address</secondary> + </indexterm> + <para>The next thing that stands out are the addresses beginning + with <hostid role="mac">0:e0:</hostid>. These are Ethernet + hardware addresses, which are also known as MAC addresses. + FreeBSD will automatically identify any hosts + (<hostid>test0</hostid> in the example) on the local Ethernet + and add a route for that host, directly to it over the + Ethernet interface, <devicename>ed0</devicename>. There is + also a timeout (<literal>Expire</literal> column) associated + with this type of route, which is used if we fail to hear from + the host in a specific amount of time. When this happens, the + route to this host will be automatically deleted. These hosts + are identified using a mechanism known as RIP (Routing + Information Protocol), which figures out routes to local hosts + based upon a shortest path determination.</para> + + <indexterm><primary>subnet</primary></indexterm> + + <para>FreeBSD will also add subnet routes for the local subnet + (<hostid role="ipaddr">10.20.30.255</hostid> is the broadcast + address for the subnet + <hostid role="ipaddr">10.20.30</hostid>, and + <hostid role="domainname">example.com</hostid> is the domain + name associated with that subnet). The designation + <literal>link#1</literal> refers to the first Ethernet card in + the machine. You will notice no additional interface is + specified for those.</para> + + <para>Both of these groups (local network hosts and local + subnets) have their routes automatically configured by a + daemon called <application>routed</application>. If this is + not run, then only routes which are statically defined (i.e., + entered explicitly) will exist.</para> + + <para>The <literal>host1</literal> line refers to our host, + which it knows by Ethernet address. Since we are the sending + host, FreeBSD knows to use the loopback interface + (<devicename>lo0</devicename>) rather than sending it out over + the Ethernet interface.</para> + + <para>The two <literal>host2</literal> lines are an example of + what happens when we use an &man.ifconfig.8; alias (see the + section on Ethernet for reasons why we would do this). The + <literal>=></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] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [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 id="network-dual-homed-hosts"> + <title>Dual Homed Hosts</title> + + <indexterm><primary>dual homed hosts</primary></indexterm> + + <para>There is one other type of configuration that we should + cover, and that is a host that sits on two different networks. + Technically, any machine functioning as a gateway (in the + example above, using a PPP connection) counts as a dual-homed + host. But the term is really only used to refer to a machine + that sits on two local-area networks.</para> + + <para>In one case, the machine has two Ethernet cards, each + having an address on the separate subnets. Alternately, the + machine may only have one Ethernet card, and be using + &man.ifconfig.8; aliasing. The former is used if two + physically separate Ethernet networks are in use, the latter + if there is one physical network segment, but two logically + separate subnets.</para> + + <para>Either way, routing tables are set up so that each subnet + knows that this machine is the defined gateway (inbound route) + to the other subnet. This configuration, with the machine + acting as a router between the two subnets, is often used when + we need to implement packet filtering or firewall security in + either or both directions.</para> + + <para>If you want this machine to actually forward packets + between the two interfaces, you need to tell FreeBSD to enable + this ability. See the next section for more details on how + to do this.</para> + </sect2> + + <sect2 id="network-dedicated-router"> + <title>Building a Router</title> + + <indexterm><primary>router</primary></indexterm> + + <para>A network router is simply a system that forwards packets + from one interface to another. Internet standards and good + engineering practice prevent the FreeBSD Project from enabling + this by default in FreeBSD. You can enable this feature by + changing the following variable to <literal>YES</literal> in + &man.rc.conf.5;:</para> + + <programlisting>gateway_enable="YES" # Set to YES if this host will be a gateway</programlisting> + + <para>This option will set the &man.sysctl.8; variable + <varname>net.inet.ip.forwarding</varname> to + <literal>1</literal>. If you should need to stop routing + temporarily, you can reset this to <literal>0</literal> + temporarily.</para> + + <indexterm><primary>BGP</primary></indexterm> + <indexterm><primary>RIP</primary></indexterm> + <indexterm><primary>OSPF</primary></indexterm> + <para>Your new router will need routes to know where to send the + traffic. If your network is simple enough you can use static + routes. FreeBSD also comes with the standard BSD routing + daemon &man.routed.8;, which speaks RIP (both version 1 and + version 2) and IRDP. Support for BGP v4, OSPF v2, and other + sophisticated routing protocols is available with the + <filename role="package">net/zebra</filename> package. + Commercial products such as <application>&gated;</application> + are also available for more complex network routing + solutions.</para> + </sect2> + + <sect2 id="network-static-routes"> + <sect2info> + <authorgroup> + <author> + <firstname>Al</firstname> + <surname>Hoang</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <!-- Feb 2004 --> + <title>Setting Up Static Routes</title> + + <sect3> + <title>Manual Configuration</title> + + <para>Let us assume we have a network as follows:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/static-routes"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> + INTERNET + | (10.0.0.1/24) Default Router to Internet + | + |Interface xl0 + |10.0.0.10/24 + +------+ + | | RouterA + | | (FreeBSD gateway) + +------+ + | Interface xl1 + | 192.168.1.1/24 + | + +--------------------------------+ + Internal Net 1 | 192.168.1.2/24 + | + +------+ + | | RouterB + | | + +------+ + | 192.168.2.1/24 + | + Internal Net 2</literallayout> + </textobject> + </mediaobject> + + <para>In this scenario, <hostid>RouterA</hostid> is our &os; + machine that is acting as a router to the rest of the + Internet. It has a default route set to + <hostid role="ipaddr">10.0.0.1</hostid> which allows it to + connect with the outside world. We will assume that + <hostid>RouterB</hostid> is already configured properly and + knows how to get wherever it needs to go. (This is simple + in this picture. Just add a default route on + <hostid>RouterB</hostid> using + <hostid role="ipaddr">192.168.1.1</hostid> as the + gateway.)</para> + + <para>If we look at the routing table for + <hostid>RouterA</hostid> we would see something like the + following:</para> + + <screen>&prompt.user; <userinput>netstat -nr</userinput> +Routing tables + +Internet: +Destination Gateway Flags Refs Use Netif Expire +default 10.0.0.1 UGS 0 49378 xl0 +127.0.0.1 127.0.0.1 UH 0 6 lo0 +10.0.0.0/24 link#1 UC 0 0 xl0 +192.168.1.0/24 link#2 UC 0 0 xl1</screen> + + <para>With the current routing table <hostid>RouterA</hostid> + will not be able to reach our Internal Net 2. It does not + have a route for + <hostid role="ipaddr">192.168.2.0/24</hostid>. One way to + alleviate this is to manually add the route. The following + command would add the Internal Net 2 network to + <hostid>RouterA</hostid>'s routing table using + <hostid role="ipaddr">192.168.1.2</hostid> as the next + hop:</para> + + <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen> + + <para>Now <hostid>RouterA</hostid> can reach any hosts on the + <hostid role="ipaddr">192.168.2.0/24</hostid> + network.</para> + </sect3> + + <sect3> + <title>Persistent Configuration</title> + + <para>The above example is perfect for configuring a static + route on a running system. However, one problem is that the + routing information will not persist if you reboot your &os; + machine. 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 id="network-routing-propagation"> + <title>Routing Propagation</title> + + <indexterm><primary>routing propagation</primary></indexterm> + <para>We have already talked about how we define our routes to + the outside world, but not about how the outside world finds + us.</para> + + <para>We already know that routing tables can be set up so that + all traffic for a particular address space (in our examples, a + class-C subnet) can be sent to a particular host on that + network, which will forward the packets inbound.</para> + + <para>When you get an address space assigned to your site, your + service provider will set up their routing tables so that all + traffic for your subnet will be sent down your PPP link to + your site. But how do sites across the country know to send + to your ISP?</para> + + <para>There is a system (much like the distributed DNS + information) that keeps track of all assigned address-spaces, + and defines their point of connection to the Internet + Backbone. The <quote>Backbone</quote> are the main trunk + lines that carry Internet traffic across the country, and + around the world. Each backbone machine has a copy of a + master set of tables, which direct traffic for a particular + network to a specific backbone carrier, and from there down + the chain of service providers until it reaches your + network.</para> + + <para>It is the task of your service provider to advertise to + the backbone sites that they are the point of connection (and + thus the path inward) for your site. This is known as route + propagation.</para> + </sect2> + + <sect2 id="network-routing-troubleshooting"> + <title>Troubleshooting</title> + + <indexterm> + <primary><command>traceroute</command></primary> + </indexterm> + + <para>Sometimes, there is a problem with routing propagation, + and some sites are unable to connect to you. Perhaps the most + useful command for trying to figure out where routing is + breaking down is the &man.traceroute.8; command. It is + equally useful if you cannot seem to make a connection to a + remote machine (i.e., &man.ping.8; fails).</para> + + <para>The &man.traceroute.8; command is run with the name of the + remote host you are trying to connect to. It will show the + gateway hosts along the path of the attempt, eventually either + reaching the target host, or terminating because of a lack of + connection.</para> + + <para>For more information, see the manual page for + &man.traceroute.8;.</para> + </sect2> + + <sect2 id="network-routing-multicast"> + <title>Multicast Routing</title> + + <indexterm> + <primary>multicast routing</primary> + </indexterm> + <indexterm> + <primary>kernel options</primary> + <secondary>MROUTING</secondary> + </indexterm> + <para>FreeBSD supports both multicast applications and multicast + routing natively. Multicast applications do not require any + special configuration of FreeBSD; applications will generally + run out of the box. Multicast routing + requires that support be compiled into the kernel:</para> + + <programlisting>options MROUTING</programlisting> + + <para>In addition, the multicast routing daemon, &man.mrouted.8; + must be configured to set up tunnels and + <acronym>DVMRP</acronym> via + <filename>/etc/mrouted.conf</filename>. More details on + multicast configuration may be found in the manual page for + &man.mrouted.8;.</para> + + <note> + <para>The &man.mrouted.8; multicast routing daemon implements + the <acronym>DVMRP</acronym> multicast routing protocol, + which has largely been replaced by &man.pim.4; in many + multicast installations. &man.mrouted.8; and the related + &man.map-mbone.8; and &man.mrinfo.8; utilities are available + in the &os; Ports Collection as + <filename role="package">net/mrouted</filename>.</para> + </note> + </sect2> + </sect1> + + <sect1 id="network-wireless"> + <sect1info> + <authorgroup> + <author> + <othername>Loader</othername> + </author> + + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + </author> + + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + </author> + </authorgroup> + </sect1info> + <title>Wireless Networking</title> + + <indexterm><primary>wireless networking</primary></indexterm> + <indexterm> + <primary>802.11</primary> + <see>wireless networking</see> + </indexterm> + + <sect2> + <title>Wireless Networking Basics</title> + + <para>Most wireless networks are based on the &ieee; 802.11 + standards. A basic wireless network consists of multiple + stations communicating with radios that broadcast in either + the 2.4GHz or 5GHz band (though this varies according to the + locale and is also changing to enable communication in the + 2.3GHz and 4.9GHz ranges).</para> + + <para>802.11 networks are organized in two ways: in + <emphasis>infrastructure mode</emphasis> one station acts as a + master with all the other stations associating to it; the + network is known as a BSS and the master station is termed an + access point (AP). In a BSS all communication passes through + the AP; even when one station wants to communicate with + another wireless station messages must go through the AP. In + the second form of network there is no master and stations + communicate directly. This form of network is termed an IBSS + and is commonly known as an + <emphasis>ad-hoc network</emphasis>.</para> + + <para>802.11 networks were first deployed in the 2.4GHz band + using protocols defined by the &ieee; 802.11 and 802.11b + standard. These specifications include the operating + frequencies, MAC layer characteristics including framing and + transmission rates (communication can be done at various + rates). Later the 802.11a standard defined operation in the + 5GHz band, including different signalling mechanisms and + higher transmission rates. Still later the 802.11g standard + was defined to enable use of 802.11a signalling and + transmission mechanisms in the 2.4GHz band in such a way as to + be backwards compatible with 802.11b networks.</para> + + <para>Separate from the underlying transmission techniques + 802.11 networks have a variety of security mechanisms. The + original 802.11 specifications defined a simple security + protocol called WEP. This protocol uses a fixed pre-shared key + and the RC4 cryptographic cipher to encode data transmitted on + a network. Stations must all agree on the fixed key in order + to communicate. This scheme was shown to be easily broken and + is now rarely used except to discourage transient users from + joining networks. Current security practice is given by the + &ieee; 802.11i specification that defines new cryptographic + ciphers and an additional protocol to authenticate stations to + an access point and exchange keys for doing data + communication. Further, cryptographic keys are periodically + refreshed and there are mechanisms for detecting intrusion + attempts (and for countering intrusion attempts). Another + security protocol specification commonly used in wireless + networks is termed WPA. This was a precursor to 802.11i + defined by an industry group as an interim measure while + waiting for 802.11i to be ratified. WPA specifies a subset of + the requirements found in 802.11i and is designed for + implementation on legacy hardware. Specifically WPA requires + only the TKIP cipher that is derived from the original WEP + cipher. 802.11i permits use of TKIP but also requires support + for a stronger cipher, AES-CCM, for encrypting data. (The AES + cipher was not required in WPA because it was deemed too + computationally costly to be implemented on legacy + hardware.)</para> + + <para>Other than the above protocol standards the other + important standard to be aware of is 802.11e. This defines + protocols for deploying multi-media applications such as + streaming video and voice over IP (VoIP) in an 802.11 network. + Like 802.11i, 802.11e also has a precursor specification + termed WME (later renamed WMM) that has been defined by an + industry group as a subset of 802.11e that can be deployed now + to enable multi-media applications while waiting for the final + ratification of 802.11e. The most important thing to know + about 802.11e and WME/WMM is that it enables prioritized + traffic use of a wireless network through Quality of Service + (QoS) protocols and enhanced media access protocols. Proper + implementation of these protocols enable high speed bursting + of data and prioritized traffic flow.</para> + + <para>&os; supports networks that operate + using 802.11a, 802.11b, and 802.11g. The WPA and 802.11i + security protocols are likewise supported (in conjunction with + any of 11a, 11b, and 11g) and QoS and traffic prioritization + required by the WME/WMM protocols are supported for a limited + set of wireless devices.</para> + </sect2> + + <sect2 id="network-wireless-basic"> + <title>Basic Setup</title> + + <sect3> + <title>Kernel Configuration</title> + + <para>To use wireless networking, you need a wireless + networking card and to configure the kernel with the + appropriate wireless networking support. The latter is + separated into multiple modules so that you only need to + configure the software you are actually going to use.</para> + + <para>The first thing you need is a wireless device. The most + commonly used devices are those that use parts made by + Atheros. These devices are supported by the &man.ath.4; + driver and require the following line to be added to the + <filename>/boot/loader.conf</filename> file:</para> + + <programlisting>if_ath_load="YES"</programlisting> + + <para>The Atheros driver is split up into three separate + pieces: the proper driver (&man.ath.4;), the hardware + support layer that handles chip-specific functions + (&man.ath.hal.4;), and an algorithm for selecting which of + several possible rates for transmitting frames + (ath_rate_sample here). When this support is loaded as + kernel modules, these dependencies are automatically handled + for you. If, instead of an Atheros device, you had another + device you would select the module for that device; + e.g.:</para> + + <programlisting>if_wi_load="YES"</programlisting> + + <para>for devices based on the Intersil Prism parts + (&man.wi.4; driver).</para> + + <note> + <para>In the rest of this document, we will use an + &man.ath.4; device, the device name in the examples must + be changed according to your configuration. A list of + available wireless drivers and supported adapters can be + found in the &os; Hardware Notes. Copies of these notes + for various releases and architectures are available on + the <ulink + url="http://www.FreeBSD.org/releases/index.html">Release + Information</ulink> page of the &os; Web site. If a + native &os; driver for your wireless device does not + exist, it may be possible to directly use the &windows; + driver with the help of the + <link linkend="config-network-ndis">NDIS</link> driver + wrapper.</para> + </note> + + <para>Under &os; 7.X, with a device driver you need to + also bring in the 802.11 networking support required by the + driver. For the &man.ath.4; driver these are at least the + &man.wlan.4;, <literal>wlan_scan_ap</literal> and + <literal>wlan_scan_sta</literal> modules; the &man.wlan.4; + module is automatically loaded with the wireless device + driver, the remaining modules must be loaded at boot time + via the <filename>/boot/loader.conf</filename> file:</para> + + <programlisting>wlan_scan_ap_load="YES" +wlan_scan_sta_load="YES"</programlisting> + + <para>Since &os; 8.0, these modules are part of the + base &man.wlan.4; driver which is dynamically loaded with + the adapter driver.</para> + + <para>With that, you will need the modules that implement + cryptographic support for the security protocols you intend + to use. These are intended to be dynamically loaded on + demand by the &man.wlan.4; module but for now they must be + manually configured. The following modules are available: + &man.wlan.wep.4;, &man.wlan.ccmp.4; and &man.wlan.tkip.4;. + Both &man.wlan.ccmp.4; and &man.wlan.tkip.4; drivers are + only needed if you intend to use the WPA and/or 802.11i + security protocols. If your network does not use + encryption, you will not need &man.wlan.wep.4; support. To + load these modules at boot time, add the following lines to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>wlan_wep_load="YES" +wlan_ccmp_load="YES" +wlan_tkip_load="YES"</programlisting> + + <para>With this information in the system bootstrap + configuration file (i.e., + <filename>/boot/loader.conf</filename>), you have to reboot + your &os; box. If you do not want to reboot your machine + for the moment, you can load the modules by hand using + &man.kldload.8;.</para> + + <note> + <para>If you do not want to use modules, it is possible to + compile these drivers into the kernel by adding the + following lines to your kernel configuration file:</para> + + <programlisting>device wlan # 802.11 support +device wlan_wep # 802.11 WEP support +device wlan_ccmp # 802.11 CCMP support +device wlan_tkip # 802.11 TKIP support +device wlan_amrr # AMRR transmit rate control algorithm +device ath # Atheros pci/cardbus NIC's +device ath_hal # pci/cardbus chip support +options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors +device ath_rate_sample # SampleRate tx rate control for ath</programlisting> + + <para>Both following lines are also required by + &os; 7.X, other &os; versions do not need + them:</para> + + <programlisting>device wlan_scan_ap # 802.11 AP mode scanning +device wlan_scan_sta # 802.11 STA mode scanning</programlisting> + + <para>With this information in the kernel configuration + file, recompile the kernel and reboot your &os; + machine.</para> + </note> + + <para>When the system is up, we could find some information + about the wireless device in the boot messages, like + this:</para> + + <screen>ath0: <Atheros 5212> mem 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1 +ath0: [ITHREAD] +ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen> + </sect3> + </sect2> + + <sect2> + <title>Infrastructure Mode</title> + + <para>The infrastructure mode or BSS mode is the mode that is + typically used. In this mode, a number of wireless access + points are connected to a wired network. Each wireless + network has its own name, this name is called the SSID of the + network. Wireless clients connect to the wireless access + points.</para> + + <sect3> + <title>&os; Clients</title> + + <sect4> + <title>How to Find Access Points</title> + + <para>To scan for networks, use the + <command>ifconfig</command> command. This request may + take a few moments to complete as it requires that the + system switches to each available wireless frequency and + probes for available access points. Only the super-user + can initiate such a scan:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> +SSID/MESH ID BSSID CHAN RATE S:N INT CAPS +dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME +freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen> + + <note> + <para>You must mark the interface <option>up</option> + before you can scan. Subsequent scan requests do not + require you to mark the interface up again.</para> + </note> + + <note> + <para>Under &os; 7.X, the adapter device, for example + <devicename><replaceable>ath0</replaceable></devicename>, + is used directly instead of the + <devicename>wlan<replaceable>0</replaceable></devicename> + device. This requires you to replace the both previous + lines with:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput></screen> + + <para>In the rest of this document, &os; 7.X users + will need to change the command and configuration lines + according to that scheme.</para> + </note> + + <para>The output of a scan request lists each BSS/IBSS + network found. Beside the name of the network, + <literal>SSID</literal>, we find the + <literal>BSSID</literal> which is the MAC address of the + access point. The <literal>CAPS</literal> field + identifies the type of each network and the capabilities + of the stations operating there:</para> + + <table frame="none" pgwide="0"> + <title>Station Capability Codes</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Capability Code</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>E</literal></entry> + <entry>Extended Service Set (ESS). Indicates that + the station is part of an infrastructure network + (in contrast to an IBSS/ad-hoc network).</entry> + </row> + + <row> + <entry><literal>I</literal></entry> + <entry>IBSS/ad-hoc network. Indicates that the + station is part of an ad-hoc network (in contrast + to an ESS network).</entry> + </row> + + <row> + <entry><literal>P</literal></entry> + <entry>Privacy. Data confidentiality is required + for all data frames exchanged within the BSS. + This means that this BSS requires the station to + use cryptographic means such as WEP, TKIP or + AES-CCMP to encrypt/decrypt data frames being + exchanged with others.</entry> + </row> + + <row> + <entry><literal>S</literal></entry> + <entry>Short Preamble. Indicates that the network + is using short preambles (defined in 802.11b High + Rate/DSSS PHY, short preamble utilizes a 56 bit + sync field in contrast to a 128 bit field used in + long preamble mode).</entry> + </row> + + <row> + <entry><literal>s</literal></entry> + <entry>Short slot time. Indicates that the 802.11g + network is using a short slot time because there + are no legacy (802.11b) stations present.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>One can also display the current list of known + networks with:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list scan</userinput></screen> + + <para>This information may be updated automatically by the + adapter or manually with a <option>scan</option> request. + Old data is automatically removed from the cache, so over + time this list may shrink unless more scans are + done.</para> + </sect4> + + <sect4> + <title>Basic Settings</title> + + <para>This section provides a simple example of how to make + the wireless network adapter work in &os; without + encryption. After you are familiar with these concepts, + we strongly recommend using + <link linkend="network-wireless-wpa">WPA</link> to set up + your wireless network.</para> + + <para>There are three basic steps to configure a wireless + network: selecting an access point, authenticating your + station, and configuring an IP address. The following + sections discuss each step.</para> + + <sect5> + <title>Selecting an Access Point</title> + + <para>Most of time it is sufficient to let the system + choose an access point using the builtin heuristics. + This is the default behaviour when you mark an interface + up or otherwise configure an interface by listing it in + <filename>/etc/rc.conf</filename>, e.g.:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="DHCP"</programlisting> + + <note> + <para>As previously mentioned, &os; 7.X will only + require a line related to the adapter device:</para> + + <programlisting>ifconfig_ath0="DHCP"</programlisting> + </note> + + <para>If there are multiple access points and you want to + select a specific one, you can select it by its + SSID:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting> + + <para>In an environment where there are multiple access + points with the same SSID (often done to simplify + roaming) it may be necessary to associate to one + specific device. In this case you can also specify the + BSSID of the access point (you can also leave off the + SSID):</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting> + + <para>There are other ways to constrain the choice of an + access point such as limiting the set of frequencies the + system will scan on. This may be useful if you have a + multi-band wireless card as scanning all the possible + channels can be time-consuming. To limit operation to a + specific band you can use the <option>mode</option> + parameter; e.g.:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting> + + <para>will force the card to operate in 802.11g which is + defined only for 2.4GHz frequencies so any 5GHz channels + will not be considered. Other ways to do this are the + <option>channel</option> parameter, to lock operation to + one specific frequency, and the + <option>chanlist</option> parameter, to specify a list + of channels for scanning. More information about these + parameters can be found in the &man.ifconfig.8; manual + page.</para> + </sect5> + + <sect5> + <title>Authentication</title> + + <para>Once you have selected an access point your station + needs to authenticate before it can pass data. + Authentication can happen in several ways. The most + common scheme used is termed open authentication and + allows any station to join the network and communicate. + This is the authentication you should use for test + purpose the first time you set up a wireless network. + Other schemes require cryptographic handshakes be + completed before data traffic can flow; either using + pre-shared keys or secrets, or more complex schemes that + involve backend services such as RADIUS. Most users + will use open authentication which is the default + setting. Next most common setup is WPA-PSK, also known + as WPA Personal, which is described <link + linkend="network-wireless-wpa-wpa-psk">below</link>.</para> + + <note> + <para>If you have an &apple; &airport; Extreme base + station for an access point you may need to configure + shared-key authentication together with a WEP key. + This can be done in the + <filename>/etc/rc.conf</filename> file or using the + &man.wpa.supplicant.8; program. If you have a single + &airport; base station you can setup access with + something like:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting> + + <para>In general shared key authentication is to be + avoided because it uses the WEP key material in a + highly-constrained manner making it even easier to + crack the key. If WEP must be used (e.g., for + compatibility with legacy devices) it is better to use + WEP with <literal>open</literal> authentication. More + information regarding WEP can be found in the + <xref linkend="network-wireless-wep"/>.</para> + </note> + </sect5> + + <sect5> + <title>Getting an IP Address with DHCP</title> + + <para>Once you have selected an access point and set the + authentication parameters, you will have to get an IP + address to communicate. Most of time you will obtain + your wireless IP address via DHCP. To achieve that, + edit <filename>/etc/rc.conf</filename> and add + <literal>DHCP</literal> to the configuration for your + device as shown in various examples above:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="DHCP"</programlisting> + + <para>At this point, you are ready to bring up the + wireless interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput></screen> + + <para>Once the interface is running, use + <command>ifconfig</command> to see the status of the + interface <devicename>ath0</devicename>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 + media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g + status: associated + ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76 + country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 + scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 + roam:rate 5 protmode CTS wme burst</screen> + + <para>The <literal>status: associated</literal> means you + are connected to the wireless network (to the + <literal>dlinkap</literal> network in our case). The + <literal>bssid 00:13:46:49:41:76</literal> part is the + MAC address of your access point; the + <literal>authmode OPEN</literal> part informs you that + the communication is not encrypted.</para> + </sect5> + + <sect5> + <title>Static IP Address</title> + + <para>In the case you cannot obtain an IP address from a + DHCP server, you can set a fixed IP address. Replace + the <literal>DHCP</literal> keyword shown above with the + address information. Be sure to retain any other + parameters you have set up for selecting an access + point:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting> + </sect5> + </sect4> + + <sect4 id="network-wireless-wpa"> + <title>WPA</title> + + <para>WPA (Wi-Fi Protected Access) is a security protocol + used together with 802.11 networks to address the lack of + proper authentication and the weakness of + <link linkend="network-wireless-wep">WEP</link>. WPA + leverages the 802.1X authentication protocol and uses one + of several ciphers instead of WEP for data integrity. The + only cipher required by WPA is TKIP (Temporary Key + Integrity Protocol). TKIP is a cipher that extends the + basic RC4 cipher used by WEP by adding integrity checking, + tamper detection, and measures for responding to any + detected intrusions. TKIP is designed to work on legacy + hardware with only software modification; it represents a + compromise that improves security but is still not + entirely immune to attack. WPA also specifies the + AES-CCMP cipher as an alternative to TKIP and that is + preferred when possible; for this specification the term + WPA2 (or RSN) is commonly used.</para> + + <para>WPA defines authentication and encryption protocols. + Authentication is most commonly done using one of two + techniques: by 802.1X and a backend authentication service + such as RADIUS, or by a minimal handshake between the + station and the access point using a pre-shared secret. + The former is commonly termed WPA Enterprise with the + latter known as WPA Personal. Since most people will not + set up a RADIUS backend server for their wireless network, + WPA-PSK is by far the most commonly encountered + configuration for WPA.</para> + + <para>The control of the wireless connection and the + authentication (key negotiation or authentication with a + server) is done with the &man.wpa.supplicant.8; utility. + This program requires a configuration file, + <filename>/etc/wpa_supplicant.conf</filename>, to run. + More information regarding this file can be found in the + &man.wpa.supplicant.conf.5; manual page.</para> + + <sect5 id="network-wireless-wpa-wpa-psk"> + <title>WPA-PSK</title> + + <para>WPA-PSK, also known as WPA-Personal, is based on a + pre-shared key (PSK) generated from a given password and + that will be used as the master key in the wireless + network. This means every wireless user will share the + same key. WPA-PSK is intended for small networks where + the use of an authentication server is not possible or + desired.</para> + + <warning> + <para>Always use strong passwords that are + sufficiently long and made from a rich alphabet so + they will not be guessed and/or attacked.</para> + </warning> + + <para>The first step is the configuration of the + <filename>/etc/wpa_supplicant.conf</filename> file with + the SSID and the pre-shared key of your network:</para> + + <programlisting>network={ + ssid="freebsdap" + psk="freebsdmall" +}</programlisting> + + <para>Then, in <filename>/etc/rc.conf</filename>, we + indicate that the wireless device configuration will be + done with WPA and the IP address will be obtained with + DHCP:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="WPA DHCP"</programlisting> + + <para>Then we can bring up the interface:</para> + + <screen>&prompt.root; <userinput><filename>/etc/rc.d/netif</filename> start</userinput> +Starting wpa_supplicant. +DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5 +DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6 +DHCPOFFER from 192.168.0.1 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + + <para>Or you can try to configure it manually using the + same <filename>/etc/wpa_supplicant.conf</filename> <link + linkend="network-wireless-wpa-wpa-psk">above</link>, and + run:</para> + + <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput> +Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz) +Associated with 00:11:95:c3:0d:ac +WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP] +CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=]</screen> + + <para>The next operation is the launch of the + <command>dhclient</command> command to get the IP + address from the DHCP server:</para> + + <screen>&prompt.root; <userinput>dhclient <replaceable>wlan0</replaceable></userinput> +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + + <note> + <para>If <filename>/etc/rc.conf</filename> has an + <literal>ifconfig_wlan0</literal> entry with the + <literal>DHCP</literal> string (like + <literal>ifconfig_wlan0="DHCP"</literal>), + <command>dhclient</command> will be launched + automatically after <command>wpa_supplicant</command> + associates with the access point.</para> + </note> + + <para>If DHCP is not possible or desired, + you can set a static IP address after + <command>wpa_supplicant</command> has authenticated the + station:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + + <para>When DHCP is not used, you also have to manually set + the default gateway and the nameserver:</para> + + <screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput> +&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" >> /etc/resolv.conf</userinput></screen> + </sect5> + + <sect5 id="network-wireless-wpa-eap-tls"> + <title>WPA with EAP-TLS</title> + + <para>The second way to use WPA is with an 802.1X backend + authentication server. In this case WPA is called + WPA-Enterprise to differentiate it from the less secure + WPA-Personal with its pre-shared key. + Authentication in WPA-Enterprise is based on the + Extensible Authentication Protocol (EAP).</para> + + <para>EAP does not come with an encryption method. + Instead, it was decided to embed EAP inside an encrypted + tunnel. There are many EAP authentication methods, but + EAP-TLS, EAP-TTLS, and EAP-PEAP are the most + common.</para> + + <para>EAP-TLS (EAP with Transport Layer Security) is a + very well-supported authentication protocol in the + wireless world since it was the first EAP method to be + certified by the <ulink + url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>. + EAP-TLS will require three certificates to run: the CA + certificate (installed on all machines), the server + certificate for your authentication server, and one + client certificate for each wireless client. In this + EAP method, both authentication server and wireless + client authenticate each other in presenting their + respective certificates, and they verify that these + certificates were signed by your organization's + certificate authority (CA).</para> + + <para>As previously, the configuration is done via + <filename>/etc/wpa_supplicant.conf</filename>:</para> + + <programlisting>network={ + ssid="freebsdap" <co id="co-tls-ssid"/> + proto=RSN <co id="co-tls-proto"/> + key_mgmt=WPA-EAP <co id="co-tls-kmgmt"/> + eap=TLS <co id="co-tls-eap"/> + identity="loader" <co id="co-tls-id"/> + ca_cert="/etc/certs/cacert.pem" <co id="co-tls-cacert"/> + client_cert="/etc/certs/clientcert.pem" <co id="co-tls-clientcert"/> + private_key="/etc/certs/clientkey.pem" <co id="co-tls-pkey"/> + private_key_passwd="freebsdmallclient" <co id="co-tls-pwd"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-tls-ssid"> + <para>This field indicates the network name + (SSID).</para> + </callout> + + <callout arearefs="co-tls-proto"> + <para>Here, we use RSN (&ieee; 802.11i) protocol, + i.e., WPA2.</para> + </callout> + + <callout arearefs="co-tls-kmgmt"> + <para>The <literal>key_mgmt</literal> line refers to + the key management protocol we use. In our case it + is WPA using EAP authentication: + <literal>WPA-EAP</literal>.</para> + </callout> + + <callout arearefs="co-tls-eap"> + <para>In this field, we mention the EAP method for our + connection.</para> + </callout> + + <callout arearefs="co-tls-id"> + <para>The <literal>identity</literal> field contains + the identity string for EAP.</para> + </callout> + + <callout arearefs="co-tls-cacert"> + <para>The <literal>ca_cert</literal> field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificate.</para> + </callout> + + <callout arearefs="co-tls-clientcert"> + <para>The <literal>client_cert</literal> line gives + the pathname to the client certificate file. This + certificate is unique to each wireless client of the + network.</para> + </callout> + + <callout arearefs="co-tls-pkey"> + <para>The <literal>private_key</literal> field is the + pathname to the client certificate private key + file.</para> + </callout> + + <callout arearefs="co-tls-pwd"> + <para>The <literal>private_key_passwd</literal> field + contains the passphrase for the private key.</para> + </callout> + </calloutlist> + + <para>Then add the following lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="WPA DHCP"</programlisting> + + <para>The next step is to bring up the interface with the + help of the <filename>rc.d</filename> facility:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + + <para>As previously shown, it is also possible to bring up + the interface manually with both + <command>wpa_supplicant</command> and + <command>ifconfig</command> commands.</para> + </sect5> + + <sect5 id="network-wireless-wpa-eap-ttls"> + <title>WPA with EAP-TTLS</title> + + <para>With EAP-TLS both the authentication server and the + client need a certificate, with EAP-TTLS (EAP-Tunneled + Transport Layer Security) a client certificate is + optional. This method is close to what some secure web + sites do , where the web server can create a secure SSL + tunnel even if the visitors do not have client-side + certificates. EAP-TTLS will use the encrypted TLS + tunnel for safe transport of the authentication + data.</para> + + <para>The configuration is done via the + <filename>/etc/wpa_supplicant.conf</filename> + file:</para> + + <programlisting>network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=TTLS <co id="co-ttls-eap"/> + identity="test" <co id="co-ttls-id"/> + password="test" <co id="co-ttls-passwd"/> + ca_cert="/etc/certs/cacert.pem" <co id="co-ttls-cacert"/> + phase2="auth=MD5" <co id="co-ttls-pha2"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ttls-eap"> + <para>In this field, we mention the EAP method for our + connection.</para> + </callout> + + <callout arearefs="co-ttls-id"> + <para>The <literal>identity</literal> field contains + the identity string for EAP authentication inside + the encrypted TLS tunnel.</para> + </callout> + + <callout arearefs="co-ttls-passwd"> + <para>The <literal>password</literal> field contains + the passphrase for the EAP authentication.</para> + </callout> + + <callout arearefs="co-ttls-cacert"> + <para>The <literal>ca_cert</literal> field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificate.</para> + </callout> + + <callout arearefs="co-ttls-pha2"> + <para>In this field, we mention the authentication + method used in the encrypted TLS tunnel. In our + case, EAP with MD5-Challenge has been used. The + <quote>inner authentication</quote> phase is often + called <quote>phase2</quote>.</para> + </callout> + </calloutlist> + + <para>You also have to add the following lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="WPA DHCP"</programlisting> + + <para>The next step is to bring up the interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + </sect5> + + <sect5 id="network-wireless-wpa-eap-peap"> + <title>WPA with EAP-PEAP</title> + + <note> + <para>PEAPv0/EAP-MSCHAPv2 is the most common PEAP + method. In the rest of this document, we will use the + PEAP term to refer to that method.</para> + </note> + + <para>PEAP (Protected EAP) has been designed as an + alternative to EAP-TTLS, and is the most used EAP + standard after EAP-TLS. In other words, if you have a + network with mixed OSes, PEAP should be the most + supported standard after EAP-TLS.</para> + + <para>PEAP is similar to EAP-TTLS: it uses a server-side + certificate to authenticate clients by creating an + encrypted TLS tunnel between the client and the + authentication server, which protects the ensuing + exchange of authentication information. In terms of + security, the difference between EAP-TTLS and PEAP is + that PEAP authentication broadcasts the username in the + clear, with only the password sent in the encrypted TLS + tunnel. EAP-TTLS will use the TLS tunnel for both + username and password.</para> + + <para>We have to edit the + <filename>/etc/wpa_supplicant.conf</filename> file and + add the EAP-PEAP related settings:</para> + + <programlisting>network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=PEAP <co id="co-peap-eap"/> + identity="test" <co id="co-peap-id"/> + password="test" <co id="co-peap-passwd"/> + ca_cert="/etc/certs/cacert.pem" <co id="co-peap-cacert"/> + phase1="peaplabel=0" <co id="co-peap-pha1"/> + phase2="auth=MSCHAPV2" <co id="co-peap-pha2"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-peap-eap"> + <para>In this field, we mention the EAP method for our + connection.</para> + </callout> + + <callout arearefs="co-peap-id"> + <para>The <literal>identity</literal> field contains + the identity string for EAP authentication inside + the encrypted TLS tunnel.</para> + </callout> + + <callout arearefs="co-peap-passwd"> + <para>The <literal>password</literal> field contains + the passphrase for the EAP authentication.</para> + </callout> + + <callout arearefs="co-peap-cacert"> + <para>The <literal>ca_cert</literal> field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificate.</para> + </callout> + + <callout arearefs="co-peap-pha1"> + <para>This field contains the parameters for the + first phase of authentication (the TLS tunnel). + According to the authentication server used, you + will have to specify a specific label for + authentication. Most of the time, the label will be + <quote>client EAP encryption</quote> which is set by + using <literal>peaplabel=0</literal>. More + information can be found in the + &man.wpa.supplicant.conf.5; manual page.</para> + </callout> + + <callout arearefs="co-peap-pha2"> + <para>In this field, we mention the authentication + protocol used in the encrypted TLS tunnel. In the + case of PEAP, it is + <literal>auth=MSCHAPV2</literal>.</para> + </callout> + </calloutlist> + + <para>The following must be added to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="WPA DHCP"</programlisting> + + <para>Then we can bring up the interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 7 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + </sect5> + </sect4> + + <sect4 id="network-wireless-wep"> + <title>WEP</title> + + <para>WEP (Wired Equivalent Privacy) is part of the original + 802.11 standard. There is no authentication mechanism, + only a weak form of access control, and it is easily + cracked.</para> + + <para>WEP can be set up with + <command>ifconfig</command>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> \ + ssid <replaceable>my_net</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable></userinput></screen> + + <itemizedlist> + <listitem> + + <para>The <literal>weptxkey</literal> means which WEP + key will be used in the transmission. Here we used + the third key. This must match the setting in the + access point. If you do not have any idea of which + key is used by the access point, try + <literal>1</literal> (i.e., the first key) for this + value.</para> + </listitem> + + <listitem> + <para>The <literal>wepkey</literal> selects one of the + WEP keys. It should be in the format + <replaceable>index:key</replaceable>. Key + <literal>1</literal> is used by default; the index + only needs to be set if we use a key other + than the first key.</para> + + <note> + <para>You must replace the + <literal>0x3456789012</literal> with the key + configured for use on the access point.</para> + </note> + </listitem> + </itemizedlist> + + <para>You are encouraged to read the &man.ifconfig.8; manual + page for further information.</para> + + <para>The <command>wpa_supplicant</command> facility also + can be used to configure your wireless interface with WEP. + The example above can be set up by adding the following + lines to + <filename>/etc/wpa_supplicant.conf</filename>:</para> + + <programlisting>network={ + ssid="my_net" + key_mgmt=NONE + wep_key3=3456789012 + wep_tx_keyidx=3 +}</programlisting> + + <para>Then:</para> + + <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput> +Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz) +Associated with 00:13:46:49:41:76</screen> + </sect4> + </sect3> + </sect2> + + <sect2> + <title>Ad-hoc Mode</title> + + <para>IBSS mode, also called ad-hoc mode, is designed for point + to point connections. For example, to establish an ad-hoc + network between the machine <hostid>A</hostid> and the machine + <hostid>B</hostid>, we will just need to choose two IP + addresses and a SSID.</para> + + <para>On the box <hostid>A</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:c3:0d:ac + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc> + status: running + ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 + protmode CTS wme burst</screen> + + <para>The <literal>adhoc</literal> parameter indicates the + interface is running in the IBSS mode.</para> + + <para>On <hostid>B</hostid>, we should be able to detect + <hostid>A</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> + SSID/MESH ID BSSID CHAN RATE S:N INT CAPS + freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME</screen> + + <para>The <literal>I</literal> in the output confirms the + machine <hostid>A</hostid> is in ad-hoc mode. We just have to + configure <hostid>B</hostid> with a different IP + address:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc> + status: running + ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 + protmode CTS wme burst</screen> + + <para>Both <hostid>A</hostid> and <hostid>B</hostid> are now + ready to exchange information.</para> + </sect2> + + <sect2 id="network-wireless-ap"> + <title>&os; Host Access Points</title> + + <para>&os; can act as an Access Point (AP) which eliminates the + need to buy a hardware AP or run an ad-hoc network. This can + be particularly useful when your &os; machine is acting as a + gateway to another network (e.g., the Internet).</para> + + <sect3 id="network-wireless-ap-basic"> + <title>Basic Settings</title> + + <para>Before configuring your &os; machine as an AP, the + kernel must be configured with the appropriate wireless + networking support for your wireless card. You also have to + add support for the security protocols you intend to + use. For more details, see + <xref linkend="network-wireless-basic"/>.</para> + + <note> + <para>The use of the NDIS driver wrapper and the &windows; + drivers do not currently allow AP operation. Only native + &os; wireless drivers support AP mode.</para> + </note> + + <para>Once wireless networking support is loaded, you can + check if your wireless device supports the host-based access + point mode (also known as hostap mode):</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput> +drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG> +cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC></screen> + + <para>This output displays the card capabilities; the + <literal>HOSTAP</literal> word confirms this wireless card + can act as an Access Point. Various supported ciphers are + also mentioned: WEP, TKIP, AES, etc. This information + is important to know what security protocols can be used + on the Access Point.</para> + + <para>The wireless device can only be put into hostap mode + during the creation of the network pseudo-device, so a + previously created device must be destroyed first:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> destroy</userinput></screen> + + <para>then regenerated with the correct option before setting + the other parameters:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen> + + <para>Use <command>ifconfig</command> again to see the status + of the <devicename>wlan0</devicename> interface:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:c3:0d:ac + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: running + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 + protmode CTS wme burst dtimperiod 1 -dfs</screen> + + <para>The <literal>hostap</literal> parameter indicates the + interface is running in the host-based access point + mode.</para> + + <para>The interface configuration can be done automatically at + boot time by adding the following lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +create_args_wlan0="wlanmode hostap" +ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel <replaceable>1</replaceable>"</programlisting> + </sect3> + + <sect3> + <title>Host-based Access Point Without Authentication or + Encryption</title> + + <para>Although it is not recommended to run an AP without any + authentication or encryption, this is a simple way to check + if your AP is working. This configuration is also important + for debugging client issues.</para> + + <para>Once the AP configured as previously shown, it is + possible from another wireless machine to initiate a scan to + find the AP:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> +SSID/MESH ID BSSID CHAN RATE S:N INT CAPS +freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen> + + <para>The client machine found the Access Point and can be + associated with it:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 + scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 + roam:rate 5 protmode CTS wme burst</screen> + </sect3> + + <sect3> + <title>WPA Host-based Access Point</title> + + <para>This section will focus on setting up &os; Access Point + using the WPA security protocol. More details regarding WPA + and the configuration of WPA-based wireless clients can be + found in the <xref linkend="network-wireless-wpa"/>.</para> + + <para>The <application>hostapd</application> daemon is used to + deal with client authentication and keys management on the + WPA enabled Access Point.</para> + + <para>In the following, all the configuration operations will + be performed on the &os; machine acting as AP. Once the + AP is correctly working, <application>hostapd</application> + should be automatically enabled at boot with the following + line in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>hostapd_enable="YES"</programlisting> + + <para>Before trying to configure + <application>hostapd</application>, be sure you have done + the basic settings introduced in the + <xref linkend="network-wireless-ap-basic"/>.</para> + + <sect4> + <title>WPA-PSK</title> + + <para>WPA-PSK is intended for small networks where the use + of an backend authentication server is not possible or + desired.</para> + + <para>The configuration is done in the + <filename>/etc/hostapd.conf</filename> file:</para> + + <programlisting>interface=wlan0 <co id="co-ap-wpapsk-iface"/> +debug=1 <co id="co-ap-wpapsk-dbug"/> +ctrl_interface=/var/run/hostapd <co id="co-ap-wpapsk-ciface"/> +ctrl_interface_group=wheel <co id="co-ap-wpapsk-cifacegrp"/> +ssid=freebsdap <co id="co-ap-wpapsk-ssid"/> +wpa=1 <co id="co-ap-wpapsk-wpa"/> +wpa_passphrase=freebsdmall <co id="co-ap-wpapsk-pass"/> +wpa_key_mgmt=WPA-PSK <co id="co-ap-wpapsk-kmgmt"/> +wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> + + <calloutlist> + <callout arearefs="co-ap-wpapsk-iface"> + <para>This field indicates the wireless interface used + for the Access Point.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-dbug"> + <para>This field sets the level of verbosity during the + execution of <application>hostapd</application>. A + value of <literal>1</literal> represents the minimal + level.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-ciface"> + <para>The <literal>ctrl_interface</literal> field gives + the pathname of the directory used by + <application>hostapd</application> to stores its + domain socket files for the communication with + external programs such as &man.hostapd.cli.8;. The + default value is used here.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-cifacegrp"> + <para>The <literal>ctrl_interface_group</literal> line + sets the group (here, it is the + <groupname>wheel</groupname> group) allowed to access + to the control interface files.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-ssid"> + <para>This field sets the network name.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-wpa"> + <para>The <literal>wpa</literal> field enables WPA and + specifies which WPA authentication protocol will be + required. A value of <literal>1</literal> configures + the AP for WPA-PSK.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-pass"> + <para>The <literal>wpa_passphrase</literal> field + contains the ASCII passphrase for the WPA + authentication.</para> + + <warning> + <para>Always use strong passwords that are + sufficiently long and made from a rich alphabet so + they will not be guessed and/or attacked.</para> + </warning> + </callout> + + <callout arearefs="co-ap-wpapsk-kmgmt"> + <para>The <literal>wpa_key_mgmt</literal> line refers to + the key management protocol we use. In our case it is + WPA-PSK.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-pwise"> + <para>The <literal>wpa_pairwise</literal> field + indicates the set of accepted encryption algorithms by + the Access Point. Here both TKIP (WPA) and CCMP + (WPA2) ciphers are accepted. CCMP cipher is an + alternative to TKIP and that is strongly preferred + when possible; TKIP should be used solely for stations + incapable of doing CCMP.</para> + </callout> + </calloutlist> + + <para>The next step is to start + <application>hostapd</application>:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/hostapd forcestart</userinput></screen> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 2290 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 + ether 00:11:95:c3:0d:ac + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen> + + <para>The Access Point is running, the clients can now be + associated with it, see + <xref linkend="network-wireless-wpa"/> for more details. + It is possible to see the stations associated with the AP + using the <command>ifconfig + <replaceable>wlan0</replaceable> list sta</command> + command.</para> + </sect4> + </sect3> + + <sect3> + <title>WEP Host-based Access Point</title> + + <para>It is not recommended to use WEP for setting up an + Access Point since there is no authentication mechanism and + it is easily to be cracked. Some legacy wireless cards only + support WEP as security protocol, these cards will only + allow to set up AP without authentication or encryption or + using the WEP protocol.</para> + + <para>The wireless device can now be put into hostap mode and + configured with the correct SSID and IP address:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \ + ssid <replaceable>freebsdap</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable> mode 11g</userinput></screen> + + <itemizedlist> + <listitem> + <para>The <literal>weptxkey</literal> means which WEP + key will be used in the transmission. Here we used the + third key (note that the key numbering starts with + <literal>1</literal>). This parameter must be specified + to really encrypt the data.</para> + </listitem> + + <listitem> + <para>The <literal>wepkey</literal> means setting the + selected WEP key. It should in the format + <replaceable>index:key</replaceable>, if the index is + not given, key <literal>1</literal> is set. That is + to say we need to set the index if we use keys other + than the first key.</para> + </listitem> + </itemizedlist> + + <para>Use again <command>ifconfig</command> to see the status + of the <devicename>wlan0</devicename> interface:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:c3:0d:ac + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: running + ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit + txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs</screen> + + <para>From another wireless machine, it is possible to + initiate a scan to find the AP:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> +SSID BSSID CHAN RATE S:N INT CAPS +freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen> + + <para>The client machine found the Access Point and can be + associated with it using the correct parameters (key, etc.), + see <xref linkend="network-wireless-wep"/> for more + details.</para> + </sect3> + </sect2> + + <sect2> + <title>Using Both Wired and Wireless Connection</title> + + <para>Wired connection provides better performance and + reliability, while wireless connection provides flexibility + and mobility, users of laptop computers usually want to + combine these together and roam seamlessly between the + two.</para> + + <para>On &os;, it is possible to combine two or even more + network interfaces together in a <quote>failover</quote> + fashion, that is, to use the most preferred and available + connection from a group of network interfaces, and have the + operating system switch automatically when the link state + changes.</para> + + <para>We will cover link aggregation and failover in + <xref linkend="network-aggregation"/> where an example for + using both wired and wireless connection is also provided at + <xref linkend="networking-lagg-wired-and-wireless"/>.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <para>If you are having trouble with wireless networking, there + are a number of steps you can take to help troubleshoot the + problem.</para> + + <itemizedlist> + <listitem> + <para>If you do not see the access point listed when + scanning be sure you have not configured your wireless + device to a limited set of channels.</para> + </listitem> + + <listitem> + <para>If you cannot associate to an access point verify the + configuration of your station matches the one of the + access point. This includes the authentication scheme and + any security protocols. Simplify your configuration as + much as possible. If you are using a security protocol + such as WPA or WEP configure the access point for open + authentication and no security to see if you can get + traffic to pass.</para> + </listitem> + + <listitem> + <para>Once you can associate to the access point diagnose + any security configuration using simple tools like + &man.ping.8;.</para> + + <para>The <command>wpa_supplicant</command> has much + debugging support; try running it manually with the + <option>-dd</option> option and look at the system + logs.</para> + </listitem> + + <listitem> + <para>There are also many lower-level debugging tools. You + can enable debugging messages in the 802.11 protocol + support layer using the <command>wlandebug</command> + program found in + <filename>/usr/src/tools/tools/net80211</filename>. For + example:</para> + + <screen>&prompt.root; <userinput>wlandebug -i <replaceable>ath0</replaceable> +scan+auth+debug+assoc</userinput> + net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan></screen> + + <para>can be used to enable console messages related to + scanning for access points and doing the 802.11 protocol + handshakes required to arrange communication.</para> + + <para>There are also many useful statistics maintained by + the 802.11 layer; the <command>wlanstats</command> tool + will dump this information. These statistics should + identify all errors identified by the 802.11 layer. + Beware however that some errors are identified in the + device drivers that lie below the 802.11 layer so they may + not show up. To diagnose device-specific problems you + need to refer to the drivers' documentation.</para> + </listitem> + </itemizedlist> + + <para>If the above information does not help to clarify the + problem, please submit a problem report and include output + from the above tools.</para> + </sect2> + </sect1> + + <sect1 id="network-bluetooth"> + <sect1info> + <authorgroup> + <author> + <firstname>Pav</firstname> + <surname>Lucistnik</surname> + <contrib>Written by </contrib> + <affiliation> + <address><email>pav@FreeBSD.org</email></address> + </affiliation> + </author> + </authorgroup> + </sect1info> + + <title>Bluetooth</title> + + <indexterm><primary>Bluetooth</primary></indexterm> + <sect2> + <title>Introduction</title> + + <para>Bluetooth is a wireless technology for creating personal + networks operating in the 2.4 GHz unlicensed band, with a + range of 10 meters. Networks are usually formed ad-hoc from + portable devices such as cellular phones, handhelds and + laptops. Unlike the other popular wireless technology, Wi-Fi, + Bluetooth offers higher level service profiles, e.g., FTP-like + file servers, file pushing, voice transport, serial line + emulation, and more.</para> + + <para>The Bluetooth stack in &os; is implemented using the + Netgraph framework (see &man.netgraph.4;). A broad variety of + Bluetooth USB dongles is supported by the &man.ng.ubt.4; + driver. The Broadcom BCM2033 chip based Bluetooth devices are + supported via the &man.ubtbcmfw.4; and &man.ng.ubt.4; drivers. + The 3Com Bluetooth PC Card 3CRWB60-A is supported by the + &man.ng.bt3c.4; driver. Serial and UART based Bluetooth + devices are supported via &man.sio.4;, &man.ng.h4.4; and + &man.hcseriald.8;. This section describes the use of the USB + Bluetooth dongle.</para> + </sect2> + + <sect2> + <title>Plugging in the Device</title> + + <para>By default Bluetooth device drivers are available as + kernel modules. Before attaching a device, you will need to + load the driver into the kernel:</para> + + <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen> + + <para>If the Bluetooth device is present in the system during + system startup, load the module from + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>ng_ubt_load="YES"</programlisting> + + <para>Plug in your USB dongle. The output similar to the + following will appear on the console (or in syslog):</para> + + <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2 +ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2 +ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3, + wMaxPacketSize=49, nframes=6, buffer size=294</screen> + + <para>The <filename>/etc/rc.d/bluetooth</filename> 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.d/bluetooth start ubt0</userinput> +BD_ADDR: 00:02:72:00:d4:1a +Features: 0xff 0xff 0xf 00 00 00 00 00 +<3-Slot> <5-Slot> <Encryption> <Slot offset> +<Timing accuracy> <Switch> <Hold mode> <Sniff mode> +<Park mode> <RSSI> <Channel quality> <SCO link> +<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD> +<Paging scheme> <Power control> <Transparent SCO data> +Max. ACL packet size: 192 bytes +Number of ACL packets: 8 +Max. SCO packet size: 64 bytes +Number of SCO packets: 8</screen> + </sect2> + + <sect2> + <title>Host Controller Interface (HCI)</title> + <indexterm><primary>HCI</primary></indexterm> + + <para>Host Controller Interface (HCI) provides a command + interface to the baseband controller and link manager, and + access to hardware status and control registers. This + interface provides a uniform method of accessing the Bluetooth + baseband capabilities. HCI layer on the Host exchanges data + and commands with the HCI firmware on the Bluetooth hardware. + The Host Controller Transport Layer (i.e., physical bus) + driver provides both HCI layers with the ability to exchange + information with each other.</para> + + <para>A single Netgraph node of type <emphasis>hci</emphasis> is + created for a single Bluetooth device. The HCI node is + normally connected to the Bluetooth device driver node + (downstream) and the L2CAP node (upstream). All HCI + operations must be performed on the HCI node and not on the + device driver node. Default name for the HCI node is + <quote>devicehci</quote>. For more details refer to the + &man.ng.hci.4; manual page.</para> + + <para>One of the most common tasks is discovery of Bluetooth + devices in RF proximity. This operation is called + <emphasis>inquiry</emphasis>. Inquiry and other HCI related + operations are done with the &man.hccontrol.8; utility. The + example below shows how to find out which Bluetooth devices + are in range. You should receive the list of devices in a few + seconds. Note that a remote device will only answer the + inquiry if it put into <emphasis>discoverable</emphasis> + mode.</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput> +Inquiry result, num_responses=1 +Inquiry result #0 + BD_ADDR: 00:80:37:29:19:a4 + Page Scan Rep. Mode: 0x1 + Page Scan Period Mode: 00 + Page Scan Mode: 00 + Class: 52:02:04 + Clock offset: 0x78ef +Inquiry complete. Status: No error [00]</screen> + + <para><literal>BD_ADDR</literal> is unique address of a + Bluetooth device, similar to MAC addresses of a network card. + This address is needed for further communication with a + device. It is possible to assign human readable name to a + BD_ADDR. The <filename>/etc/bluetooth/hosts</filename> file + contains information regarding the known Bluetooth hosts. The + following example shows how to obtain human readable name that + was assigned to the remote device:</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput> +BD_ADDR: 00:80:37:29:19:a4 +Name: Pav's T39</screen> + + <para>If you perform an inquiry on a remote Bluetooth device, it + will find your computer as + <quote>your.host.name (ubt0)</quote>. The name assigned to the + local device can be changed at any time.</para> + + <para>The Bluetooth system provides a point-to-point connection + (only two Bluetooth units involved), or a point-to-multipoint + connection. In the point-to-multipoint connection the + connection is shared among several Bluetooth devices. The + following example shows how to obtain the list of active + baseband connections for the local device:</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput> +Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State +00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN</screen> + + <para>A <emphasis>connection handle</emphasis> is useful when + termination of the baseband connection is required. Note, + that it is normally not required to do it by hand. The stack + will automatically terminate inactive baseband + connections.</para> + + <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput> +Connection handle: 41 +Reason: Connection terminated by local host [0x16]</screen> + + <para>Refer to <command>hccontrol help</command> for a complete + listing of available HCI commands. Most of the HCI commands + do not require superuser privileges.</para> + </sect2> + + <sect2> + <title>Logical Link Control and Adaptation Protocol + (L2CAP)</title> + + <indexterm><primary>L2CAP</primary></indexterm> + + <para>Logical Link Control and Adaptation Protocol (L2CAP) + provides connection-oriented and connectionless data services + to upper layer protocols with protocol multiplexing capability + and segmentation and reassembly operation. L2CAP permits + higher level protocols and applications to transmit and + receive L2CAP data packets up to 64 kilobytes in + length.</para> + + <para>L2CAP is based around the concept of + <emphasis>channels</emphasis>. Channel is a logical + connection on top of baseband connection. Each channel is + bound to a single protocol in a many-to-one fashion. Multiple + channels can be bound to the same protocol, but a channel + cannot be bound to multiple protocols. Each L2CAP packet + received on a channel is directed to the appropriate higher + level protocol. Multiple channels can share the same baseband + connection.</para> + + <para>A single Netgraph node of type <emphasis>l2cap</emphasis> + is created for a single Bluetooth device. The L2CAP node is + normally connected to the Bluetooth HCI node (downstream) and + Bluetooth sockets nodes (upstream). Default name for the + L2CAP node is <quote>devicel2cap</quote>. For more details + refer to the &man.ng.l2cap.4; manual page.</para> + + <para>A useful command is &man.l2ping.8;, which can be used to + ping other devices. Some Bluetooth implementations might not + return all of the data sent to them, so + <literal>0 bytes</literal> in the following example is + normal.</para> + + <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput> +0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen> + + <para>The &man.l2control.8; utility is used to perform various + operations on L2CAP nodes. This example shows how to obtain + the list of logical connections (channels) and the list of + baseband connections for the local device:</para> + + <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput> +L2CAP channels: +Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State +00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN +&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput> +L2CAP connections: +Remote BD_ADDR Handle Flags Pending State +00:07:e0:00:0b:ca 41 O 0 OPEN</screen> + + <para>Another diagnostic tool is &man.btsockstat.1;. It does a + job similar to as &man.netstat.1; does, but for Bluetooth + network-related data structures. The example below shows the + same logical connection as &man.l2control.8; above.</para> + + <screen>&prompt.user; <userinput>btsockstat</userinput> +Active L2CAP sockets +PCB Recv-Q Send-Q Local address/PSM Foreign address CID State +c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN +Active RFCOMM sessions +L2PCB PCB Flag MTU Out-Q DLCs State +c2afe900 c2b53380 1 127 0 Yes OPEN +Active RFCOMM sockets +PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State +c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</screen> + </sect2> + + <sect2> + <title>RFCOMM Protocol</title> + + <para>The RFCOMM protocol provides emulation of serial ports + over the L2CAP protocol. The protocol is based on the ETSI + standard TS 07.10. RFCOMM is a simple transport protocol, + with additional provisions for emulating the 9 circuits of + RS-232 (EIATIA-232-E) serial ports. The RFCOMM protocol + supports up to 60 simultaneous connections (RFCOMM channels) + between two Bluetooth devices.</para> + + <para>For the purposes of RFCOMM, a complete communication path + involves two applications running on different devices (the + communication endpoints) with a communication segment between + them. RFCOMM is intended to cover applications that make use + of the serial ports of the devices in which they reside. The + communication segment is a Bluetooth link from one device to + another (direct connect).</para> + + <para>RFCOMM is only concerned with the connection between the + devices in the direct connect case, or between the device and + a modem in the network case. RFCOMM can support other + configurations, such as modules that communicate via Bluetooth + wireless technology on one side and provide a wired interface + on the other side.</para> + + <para>In &os; the RFCOMM protocol is implemented at the + Bluetooth sockets layer.</para> + </sect2> + + <sect2> + <title>Pairing of Devices</title> + + <para>By default, Bluetooth communication is not authenticated, + and any device can talk to any other device. A Bluetooth + device (for example, cellular phone) may choose to require + authentication to provide a particular service (for example, + Dial-Up service). Bluetooth authentication is normally done + with <emphasis>PIN codes</emphasis>. A PIN code is an ASCII + string up to 16 characters in length. User is required to + enter the same PIN code on both devices. Once user has + entered the PIN code, both devices will generate a + <emphasis>link key</emphasis>. After that the link key can be + stored either in the devices themselves or in a persistent + storage. Next time both devices will use previously generated + link key. The described above procedure is called + <emphasis>pairing</emphasis>. Note that if the link key is + lost by any device then pairing must be repeated.</para> + + <para>The &man.hcsecd.8; daemon is responsible for handling of + all Bluetooth authentication requests. The default + configuration file is + <filename>/etc/bluetooth/hcsecd.conf</filename>. An example + section for a cellular phone with the PIN code arbitrarily set + to <quote>1234</quote> is shown below:</para> + + <programlisting>device { + bdaddr 00:80:37:29:19:a4; + name "Pav's T39"; + key nokey; + pin "1234"; + }</programlisting> + + <para>There is no limitation on PIN codes (except length). Some + devices (for example Bluetooth headsets) may have a fixed PIN + code built in. The <option>-d</option> switch forces the + &man.hcsecd.8; daemon to stay in the foreground, so it is easy + to see what is happening. Set the remote device to receive + pairing and initiate the Bluetooth connection to the remote + device. The remote device should say that pairing was + accepted, and request the PIN code. Enter the same PIN code + as you have in <filename>hcsecd.conf</filename>. Now your PC + and the remote device are paired. Alternatively, you can + initiate pairing on the remote device.</para> + + <para>The following line can be added to the + <filename>/etc/rc.conf</filename> file to have + <application>hcsecd</application> started automatically on + system start:</para> + + <programlisting>hcsecd_enable="YES"</programlisting> + + <para>The following is a sample of the + <application>hcsecd</application> daemon output:</para> + + <programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist +hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists +hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting> + </sect2> + + <sect2> + <title>Service Discovery Protocol (SDP)</title> + + <indexterm><primary>SDP</primary></indexterm> + + <para>The Service Discovery Protocol (SDP) provides the means + for client applications to discover the existence of services + provided by server applications as well as the attributes of + those services. The attributes of a service include the type + or class of service offered and the mechanism or protocol + information needed to utilize the service.</para> + + <para>SDP involves communication between a SDP server and a SDP + client. The server maintains a list of service records that + describe the characteristics of services associated with the + server. Each service record contains information about a + single service. A client may retrieve information from a + service record maintained by the SDP server by issuing a SDP + request. If the client, or an application associated with the + client, decides to use a service, it must open a separate + connection to the service provider in order to utilize the + service. SDP provides a mechanism for discovering services + and their attributes, but it does not provide a mechanism for + utilizing those services.</para> + + <para>Normally, a SDP client searches for services based on some + desired characteristics of the services. However, there are + times when it is desirable to discover which types of services + are described by an SDP server's service records without any a + priori information about the services. This process of + looking for any offered services is called + <emphasis>browsing</emphasis>.</para> + + <para>The Bluetooth SDP server &man.sdpd.8; and command line + client &man.sdpcontrol.8; are included in the standard &os; + installation. The following example shows how to perform a + SDP browse query.</para> + + <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput> +Record Handle: 00000000 +Service Class ID List: + Service Discovery Server (0x1000) +Protocol Descriptor List: + L2CAP (0x0100) + Protocol specific parameter #1: u/int/uuid16 1 + Protocol specific parameter #2: u/int/uuid16 1 + +Record Handle: 0x00000001 +Service Class ID List: + Browse Group Descriptor (0x1001) + +Record Handle: 0x00000002 +Service Class ID List: + LAN Access Using PPP (0x1102) +Protocol Descriptor List: + L2CAP (0x0100) + RFCOMM (0x0003) + Protocol specific parameter #1: u/int8/bool 1 +Bluetooth Profile Descriptor List: + LAN Access Using PPP (0x1102) ver. 1.0</screen> + + <para>... and so on. Note that each service has a list of + attributes (RFCOMM channel for example). Depending on the + service you might need to make a note of some of the + attributes. Some Bluetooth implementations do not support + service browsing and may return an empty list. In this case + it is possible to search for the specific service. The + example below shows how to search for the OBEX Object Push + (OPUSH) service:</para> + + <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen> + + <para>Offering services on &os; to Bluetooth clients is done + with the &man.sdpd.8; server. The following line can be added + to the <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>sdpd_enable="YES"</programlisting> + + <para>Then the <application>sdpd</application> daemon can be + started with:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sdpd start</userinput></screen> + + <para>The local server application that wants to provide + Bluetooth service to the remote clients will register service + with the local SDP daemon. The example of such application is + &man.rfcomm.pppd.8;. Once started it will register Bluetooth + LAN service with the local SDP daemon.</para> + + <para>The list of services registered with the local SDP server + can be obtained by issuing SDP browse query via local control + channel:</para> + + <screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen> + </sect2> + + <sect2> + <title>Dial-Up Networking (DUN) and Network Access with PPP + (LAN) Profiles</title> + + <para>The Dial-Up Networking (DUN) profile is mostly used with + modems and cellular phones. The scenarios covered by this + profile are the following:</para> + + <itemizedlist> + <listitem> + <para>use of a cellular phone or modem by a computer as a + wireless modem for connecting to a dial-up Internet access + server, or using other dial-up services;</para> + </listitem> + + <listitem> + <para>use of a cellular phone or modem by a computer to + receive data calls.</para> + </listitem> + </itemizedlist> + + <para>Network Access with PPP (LAN) profile can be used in the + following situations:</para> + + <itemizedlist> + <listitem> + <para>LAN access for a single Bluetooth device;</para> + </listitem> + + <listitem> + <para>LAN access for multiple Bluetooth devices;</para> + </listitem> + + <listitem> + <para>PC to PC (using PPP networking over serial cable + emulation).</para> + </listitem> + </itemizedlist> + + <para>In &os; both profiles are implemented with &man.ppp.8; and + &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth + connection into something PPP can operate with. Before any + profile can be used, a new PPP label in the + <filename>/etc/ppp/ppp.conf</filename> must be created. + Consult &man.rfcomm.pppd.8; manual page for examples.</para> + + <para>In the following example &man.rfcomm.pppd.8; will be used + to open RFCOMM connection to remote device with BD_ADDR + 00:80:37:29:19:a4 on DUN RFCOMM channel. The actual RFCOMM + channel number will be obtained from the remote device via + SDP. It is possible to specify RFCOMM channel by hand, and in + this case &man.rfcomm.pppd.8; will not perform SDP query. Use + &man.sdpcontrol.8; to find out RFCOMM channel on the remote + device.</para> + + <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen> + + <para>In order to provide Network Access with PPP (LAN) service + the &man.sdpd.8; server must be running. A new entry for LAN + clients must be created in the + <filename>/etc/ppp/ppp.conf</filename> file. Consult + &man.rfcomm.pppd.8; manual page for examples. Finally, start + RFCOMM PPP server on valid RFCOMM channel number. The RFCOMM + PPP server will automatically register Bluetooth LAN service + with the local SDP daemon. The example below shows how to + start RFCOMM PPP server.</para> + + <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen> + </sect2> + + <sect2> + <title>OBEX Object Push (OPUSH) Profile</title> + + <indexterm><primary>OBEX</primary></indexterm> + <para>OBEX is a widely used protocol for simple file transfers between + 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> get telecom/devinfo.txt devinfo-t39.txt +Success, response: OK, Success (0x20) +obex> put new.vcf +Success, response: OK, Success (0x20) +obex> 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>Andrew</firstname> + <surname>Thompson</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Bridging</title> + + <sect2> + <title>Introduction</title> + + <indexterm><primary>IP subnet</primary></indexterm> + <indexterm><primary>bridge</primary></indexterm> + <para>It is sometimes useful to divide one physical network + (such as an Ethernet segment) into two separate network + segments without having to create IP subnets and use a router + to connect the segments together. A device that connects two + networks together in this fashion is called a + <quote>bridge</quote>. A FreeBSD system with two network + interface cards can act as a bridge.</para> + + <para>The bridge works by learning the MAC layer addresses + (Ethernet addresses) of the devices on each of its network + interfaces. It forwards traffic between two networks only + when its source and destination are on different + networks.</para> + + <para>In many respects, a bridge is like an Ethernet switch with + very few ports.</para> + </sect2> + + <sect2> + <title>Situations Where Bridging Is Appropriate</title> + + <para>There are many common situations in which a bridge is used + today.</para> + + <sect3> + <title>Connecting Networks</title> + + <para>The basic operation of a bridge is to join two or more + network segments together. There are many reasons to use a + host based bridge over plain networking equipment such as + cabling constraints, firewalling or connecting pseudo + networks such as a Virtual Machine interface. A bridge can + also connect a wireless interface running in hostap mode to + a wired network and act as an access point.</para> + </sect3> + + <sect3> + <title>Filtering/Traffic Shaping Firewall</title> + + <indexterm><primary>firewall</primary></indexterm> + <indexterm><primary>NAT</primary></indexterm> + + <para>A common situation is where firewall functionality is + needed without routing or network address translation + (NAT).</para> + + <para>An example is a small company that is connected via DSL + or ISDN to their ISP. They have a 13 globally-accessible IP + addresses from their ISP and have 10 PCs on their network. + In this situation, using a router-based firewall is + difficult because of subnetting issues.</para> + + <indexterm><primary>router</primary></indexterm> + <indexterm><primary>DSL</primary></indexterm> + <indexterm><primary>ISDN</primary></indexterm> + <para>A bridge-based firewall can be configured and dropped + into the path just downstream of their DSL/ISDN router + without any IP numbering issues.</para> + </sect3> + + <sect3> + <title>Network Tap</title> + + <para>A bridge can join two network segments and be used to + inspect all Ethernet frames that pass between them. This + can either be from using &man.bpf.4;/&man.tcpdump.1; on the + bridge interface or by sending a copy of all frames out an + additional interface (span port).</para> + </sect3> + + <sect3> + <title>Layer 2 VPN</title> + + <para>Two Ethernet networks can be joined across an IP link by + bridging the networks to an EtherIP tunnel or a &man.tap.4; + based solution such as OpenVPN.</para> + </sect3> + + <sect3> + <title>Layer 2 Redundancy</title> + + <para>A network can be connected together with multiple links + and use the Spanning Tree Protocol to block redundant paths. + For an Ethernet network to function properly only one active + path can exist between two devices, Spanning Tree will + detect loops and put the redundant links into a blocked + state. Should one of the active links fail then the + protocol will calculate a different tree and reenable one of + the blocked paths to restore connectivity to all points in + the network.</para> + </sect3> + </sect2> + + <sect2> + <title>Kernel Configuration</title> + + <para>This section covers &man.if.bridge.4; bridge + implementation, a netgraph bridging driver is also available, + for more information see &man.ng.bridge.4; manual page.</para> + + <para>The bridge driver is a kernel module and will be + automatically loaded by &man.ifconfig.8; when creating a + bridge interface. It is possible to compile the bridge in to + the kernel by adding <literal>device if_bridge</literal> to + your kernel configuration file.</para> + + <para>Packet filtering can be used with any firewall package + that hooks in via the &man.pfil.9; framework. The firewall + can be loaded as a module or compiled into the kernel.</para> + + <para>The bridge can be used as a traffic shaper with + &man.altq.4; or &man.dummynet.4;.</para> + </sect2> + + <sect2> + <title>Enabling the Bridge</title> + + <para>The bridge is created using interface cloning. To create + a bridge use &man.ifconfig.8;, if the bridge driver is not + present in the kernel then it will be loaded + automatically.</para> + + <screen>&prompt.root; <userinput>ifconfig bridge create</userinput> +bridge0 +&prompt.root; <userinput>ifconfig bridge0</userinput> +bridge0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 96:3d:4b:f1:79:7a + id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15 + maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 + root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0</screen> + + <para>A bridge interface is created and is automatically + assigned a randomly generated Ethernet address. The + <literal>maxaddr</literal> and <literal>timeout</literal> + parameters control how many MAC addresses the bridge will keep + in its forwarding table and how many seconds before each entry + is removed after it is last seen. The other parameters + control how Spanning Tree operates.</para> + + <para>Add the member network interfaces to the bridge. For the + bridge to forward packets all member interfaces and the bridge + need to be up:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 up</userinput> +&prompt.root; <userinput>ifconfig fxp0 up</userinput> +&prompt.root; <userinput>ifconfig fxp1 up</userinput></screen> + + <para>The bridge is now forwarding Ethernet frames between + <devicename>fxp0</devicename> and + <devicename>fxp1</devicename>. The equivalent configuration + in <filename>/etc/rc.conf</filename> so the bridge is created + at startup is:</para> + + <programlisting>cloned_interfaces="bridge0" +ifconfig_bridge0="addm fxp0 addm fxp1 up" +ifconfig_fxp0="up" +ifconfig_fxp1="up"</programlisting> + + <para>If the bridge host needs an IP address then the correct + place to set this is on the bridge interface itself rather + than one of the member interfaces. This can be set statically + or via DHCP:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen> + + <para>It is also possible to assign an IPv6 address to a bridge + interface.</para> + </sect2> + + <sect2> + <title>Firewalling</title> + + <indexterm><primary>firewall</primary></indexterm> + + <para>When packet filtering is enabled, bridged packets will + pass through the filter inbound on the originating interface, + on the bridge interface and outbound on the appropriate + interfaces. Either stage can be disabled. When direction of + the packet flow is important it is best to firewall on the + member interfaces rather than the bridge itself.</para> + + <para>The bridge has several configurable settings for passing + non-IP and ARP packets, and layer2 firewalling with IPFW. See + &man.if.bridge.4; for more information.</para> + </sect2> + + <sect2> + <title>Spanning Tree</title> + + <para>The bridge driver implements the Rapid Spanning Tree + Protocol (RSTP or 802.1w) with backwards compatibility with + the legacy Spanning Tree Protocol (STP). Spanning Tree is + used to detect and remove loops in a network topology. RSTP + provides faster Spanning Tree convergence than legacy STP, the + protocol will exchange information with neighbouring switches + to quickly transition to forwarding without creating + loops. + &os; supports RSTP and STP as operating modes, with RSTP + being the default mode.</para> + + <para>Spanning Tree can be enabled on member interfaces using + the <literal>stp</literal> command. For a bridge with + <devicename>fxp0</devicename> and + <devicename>fxp1</devicename> as the current interfaces, + enable STP with the following:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput> +bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether d6:cf:d5:a0:94:6d + id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15 + maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 + root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0 + member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 3 priority 128 path cost 200000 proto rstp + role designated state forwarding + member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 4 priority 128 path cost 200000 proto rstp + role designated state forwarding</screen> + + <para>This bridge has a spanning tree ID of + <literal>00:01:02:4b:d4:50</literal> and a priority of + <literal>32768</literal>. As the <literal>root id</literal> + is the same it indicates that this is the root bridge for the + tree.</para> + + <para>Another bridge on the network also has spanning tree + enabled:</para> + + <screen>bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 96:3d:4b:f1:79:7a + id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15 + maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 + root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4 + member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 4 priority 128 path cost 200000 proto rstp + role root state forwarding + member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 5 priority 128 path cost 200000 proto rstp + role designated state forwarding</screen> + + <para>The line <literal>root id 00:01:02:4b:d4:50 priority 32768 + ifcost 400000 port 4</literal> shows that the root bridge is + <literal>00:01:02:4b:d4:50</literal> as above and has a path + cost of <literal>400000</literal> from this bridge, the path + to the root bridge is via <literal>port 4</literal> which is + <devicename>fxp0</devicename>.</para> + </sect2> + + <sect2> + <title>Advanced Bridging</title> + + <sect3> + <title>Reconstruct Traffic Flows</title> + + <para>The bridge supports monitor mode, where the packets are + discarded after &man.bpf.4; processing, and are not + processed or forwarded further. This can be used to + multiplex the input of two or more interfaces into a single + &man.bpf.4; stream. This is useful for reconstructing the + traffic for network taps that transmit the RX/TX signals out + through two separate interfaces.</para> + + <para>To read the input from four network interfaces as one + stream:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up</userinput> +&prompt.root; <userinput>tcpdump -i bridge0</userinput></screen> + </sect3> + + <sect3> + <title>Span Ports</title> + + <para>A copy of every Ethernet frame received by the bridge + will be transmitted out a designated span port. The number + of span ports configured on a bridge is unlimited, if an + interface is designated as a span port then it may not also + be used as a regular bridge port. This is most useful for + snooping a bridged network passively on another host + connected to one of the span ports of the bridge.</para> + + <para>To send a copy of all frames out the interface named + <devicename>fxp4</devicename>:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 span fxp4</userinput></screen> + </sect3> + + <sect3> + <title>Private Interfaces</title> + + <para>A private interface does not forward any traffic to any + other port that is also a private interface. The traffic is + blocked unconditionally so no Ethernet frames will be + forwarded, including ARP. If traffic needs to be + selectively blocked then a firewall should be used + instead.</para> + </sect3> + + <sect3> + <title>Sticky Interfaces</title> + + <para>If a bridge member interface is marked as sticky then + dynamically learned address entries are treated at static + once entered into the forwarding cache. Sticky entries are + never aged out of the cache or replaced, even if the address + is seen on a different interface. This gives the benefit of + static address entries without the need to pre-populate the + forwarding table, clients learnt on a particular segment of + the bridge can not roam to another segment.</para> + + <para>Another example of using sticky addresses would be to + combine the bridge with VLANs to create a router where + customer networks are isolated without wasting IP address + space. Consider that + <hostid role="hostname">CustomerA</hostid> is on + <literal>vlan100</literal> and + <hostid role="hostname">CustomerB</hostid> is on + <literal>vlan101</literal>. The bridge has the address + <hostid role="ipaddr">192.168.0.1</hostid> and is also an + internet router.</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput> +&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen> + + <para>Both clients see + <hostid role="ipaddr">192.168.0.1</hostid> as their default + gateway and since the bridge cache is sticky they can not + spoof the MAC address of the other customer to intercept + their traffic.</para> + + <para>Any communication between the VLANs can be blocked using + private interfaces (or a firewall):</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen> + + <para>The customers are completely isolated from each other, + the full <hostid role="netmask">/24</hostid> address range + can be allocated without subnetting.</para> + </sect3> + + <sect3> + <title>Address Limits</title> + + <para>The number of unique source MAC addresses behind an + interface can be limited. Once the limit is reached packets + with unknown source addresses are dropped until an + existing host cache entry expires or is removed.</para> + + <para>The following example sets the maximum number of + Ethernet devices for + <hostid role="hostname">CustomerA</hostid> on + <literal>vlan100</literal> to 10.</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen> + </sect3> + + <sect3> + <title>SNMP Monitoring</title> + + <para>The bridge interface and STP parameters can be monitored + via the SNMP daemon which is included in the &os; base + system. The exported bridge MIBs conform to the IETF + standards so any SNMP client or monitoring package can be + used to retrieve the data.</para> + + <para>On the bridge machine uncomment the + <literal>begemotSnmpdModulePath."bridge" = + "/usr/lib/snmp_bridge.so"</literal> line from + <filename>/etc/snmp.config</filename> and start the + <application>bsnmpd</application> daemon. Other + configuration such as community names and access lists may + need to be modified. See &man.bsnmpd.1; and + &man.snmp.bridge.3; for more information.</para> + + <para>The following examples use the + <application>Net-SNMP</application> software + (<filename role="package">net-mgmt/net-snmp</filename>) to + query a bridge, the + <filename role="package">net-mgmt/bsnmptools</filename> port + can also be used. From the SNMP client host add to + <filename>$HOME/.snmp/snmp.conf</filename> the following + lines to import the bridge MIB definitions in to + <application>Net-SNMP</application>:</para> + + <programlisting>mibdirs +/usr/share/snmp/mibs +mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB</programlisting> + + <para>To monitor a single bridge via the IETF BRIDGE-MIB + (RFC4188) do</para> + + <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge</userinput> +BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44 +BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports +BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds +BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2 +BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50 +... +BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5) +BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1) +BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000 +BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 +BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0 +BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 +BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80 +BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1 +RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)</screen> + + <para>The <literal>dot1dStpTopChanges.0</literal> value is two + which means that the STP bridge topology has changed twice, + a topology change means that one or more links in the + network have changed or failed and a new tree has been + calculated. The + <literal>dot1dStpTimeSinceTopologyChange.0</literal> value + will show when this happened.</para> + + <para>To monitor multiple bridge interfaces one may use the + private BEGEMOT-BRIDGE-MIB:</para> + + <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com</userinput> +enterprises.fokus.begemot.begemotBridge +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1 +... +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1 +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1 +BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31 +BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9</screen> + + <para>To change the bridge interface being monitored via the + <literal>mib-2.dot1dBridge</literal> subtree do:</para> + + <screen>&prompt.user; <userinput>snmpset -v 2c -c private bridge1.example.com</userinput> +BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen> + </sect3> + </sect2> + </sect1> + + <sect1 id="network-aggregation"> + <sect1info> + <authorgroup> + <author> + <firstname>Andrew</firstname> + <surname>Thompson</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Link Aggregation and Failover</title> + + <indexterm><primary>lagg</primary></indexterm> + <indexterm><primary>failover</primary></indexterm> + <indexterm><primary>fec</primary></indexterm> + <indexterm><primary>lacp</primary></indexterm> + <indexterm><primary>loadbalance</primary></indexterm> + <indexterm><primary>roundrobin</primary></indexterm> + + <sect2> + <title>Introduction</title> + + <para>The &man.lagg.4; interface allows aggregation of multiple + network interfaces as one virtual interface for the purpose of + providing fault-tolerance and high-speed links.</para> + </sect2> + + <sect2> + <title>Operating Modes</title> + + <variablelist> + <varlistentry> + <term>Failover</term> + <listitem> + <para>Sends and receives traffic only through the master + port. If the master port becomes unavailable, the next + active port is used. The first interface added is the + master port; any interfaces added after that are used as + failover devices. If failover to a non-master port + occurs, the original port will become master when it + becomes available again.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&cisco; Fast ðerchannel;</term> + <listitem> + <para>&cisco; Fast ðerchannel; (FEC), is a static setup + and does not negotiate aggregation with the peer or + exchange frames to monitor the link. If the switch + supports LACP then that should be used instead.</para> + + <para><acronym>FEC</acronym> balances outgoing traffic + across the active ports based on hashed protocol header + information and accepts incoming traffic from any active + port. The hash includes the Ethernet source and + destination address, and, if available, the VLAN tag, + and the IPv4/IPv6 source and destination address.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>LACP</term> + <listitem> + <para>The &ieee; 802.3ad Link Aggregation Control Protocol + (LACP) and the Marker Protocol. LACP will negotiate a + set of aggregable links with the peer in to one or more + Link Aggregated Groups (LAG). Each LAG is composed of + ports of the same speed, set to full-duplex operation. + The traffic will be balanced across the ports in the LAG + with the greatest total speed, in most cases there will + only be one LAG which contains all ports. In the event + of changes in physical connectivity, Link Aggregation + will quickly converge to a new configuration.</para> + + <para><acronym>LACP</acronym> balances outgoing traffic + across the active ports based on hashed protocol header + information and accepts incoming traffic from any active + port. The hash includes the Ethernet source and + destination address, and, if available, the VLAN tag, + and the IPv4/IPv6 source and destination address.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Loadbalance</term> + <listitem> + <para>This is an alias of <emphasis>FEC</emphasis> + mode.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Round-robin</term> + <listitem> + <para>Distributes outgoing traffic using a round-robin + scheduler through all active ports and accepts incoming + traffic from any active port. This mode violates + Ethernet Frame ordering and should be used with + caution.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Examples</title> + + <example id="networking-lacp-aggregation-cisco"> + <title>LACP Aggregation with a &cisco; Switch</title> + + <para>This example connects two interfaces on a &os; machine + to the switch as a single load balanced and fault tolerant + link. More interfaces can be added to increase throughput + and fault tolerance. Since frame ordering is mandatory on + Ethernet links then any traffic between two stations always + flows over the same physical link limiting the maximum speed + to that of one interface. The transmit algorithm attempts + to use as much information as it can to distinguish + different traffic flows and balance across the available + interfaces.</para> + + <para>On the &cisco; switch add the + <replaceable>FastEthernet0/1</replaceable> and + <replaceable>FastEthernet0/2</replaceable> interfaces to the + channel-group <replaceable>1</replaceable>:</para> + + <screen><userinput>interface <replaceable>FastEthernet0/1</replaceable> + channel-group <replaceable>1</replaceable> mode active + channel-protocol lacp</userinput> +! +<userinput>interface <replaceable>FastEthernet0/2</replaceable> + channel-group <replaceable>1</replaceable> mode active + channel-protocol lacp</userinput></screen> + + <para>Create the &man.lagg.4; interface using + <replaceable>fxp0</replaceable> and + <replaceable>fxp1</replaceable>, and bring the interfaces up + with the IP Address of + <replaceable>10.0.0.3/24</replaceable>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create </userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable></userinput></screen> + + <para>View the interface status by running:</para> + + <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput></screen> + + <para>Ports marked as <emphasis>ACTIVE</emphasis> are part of + the active aggregation group that has been negotiated with + the remote switch and traffic will be transmitted and + received. Use the verbose output of &man.ifconfig.8; to + view the LAG identifiers.</para> + + <screen>lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:05:5d:71:8d:b8 + media: Ethernet autoselect + status: active + laggproto lacp + laggport: fxp1 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING> + laggport: fxp0 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING></screen> + + <para>To see the port status on the switch, use + <userinput>show lacp neighbor</userinput>:</para> + + <screen>switch# show lacp neighbor +Flags: S - Device is requesting Slow LACPDUs + F - Device is requesting Fast LACPDUs + A - Device is in Active mode P - Device is in Passive mode + +Channel group 1 neighbors + +Partner's information: + + LACP port Oper Port Port +Port Flags Priority Dev ID Age Key Number State +Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D +Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D</screen> + + <para>For more detail use the <userinput>show lacp neighbor + detail</userinput> command.</para> + + <para>To retain this configuration across reboots, the + following entries can be added to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="up" +ifconfig_<replaceable>fxp1</replaceable>="up" +cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" +ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting> + </example> + + <example id="networking-lagg-failover"> + <title>Failover Mode</title> + + <para>Failover mode can be used to switch over to a secondary + interface if the link is lost on the master interface. + Bring the underlying physical interfaces up. Create the + &man.lagg.4; interface, using + <replaceable>fxp0</replaceable> as the master interface and + <replaceable>fxp1</replaceable> as the secondary interface + and assign an IP Address of + <replaceable>10.0.0.15/24</replaceable>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen> + + <para>The interface will look something like this, the major + differences will be the <acronym>MAC</acronym> address and + the device names:</para> + + <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput> +lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:05:5d:71:8d:b8 + inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255 + media: Ethernet autoselect + status: active + laggproto failover + laggport: fxp1 flags=0<> + laggport: fxp0 flags=5<MASTER,ACTIVE></screen> + + <para>Traffic will be transmitted and received on + <replaceable>fxp0</replaceable>. If the link is lost on + <replaceable>fxp0</replaceable> then + <replaceable>fxp1</replaceable> will become the active link. + If the link is restored on the master interface then it will + once again become the active link.</para> + + <para>To retain this configuration across reboots, the + following entries can be added to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="up" +ifconfig_<replaceable>fxp1</replaceable>="up" +cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" +ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>"</programlisting> + </example> + + <example id="networking-lagg-wired-and-wireless"> + <title>Failover Mode Between Wired and Wireless + Interfaces</title> + + <para>For laptop users, it is usually desirable to make + wireless as a secondary interface, which is to be used when + the wired connection is not available. With &man.lagg.4;, + it is possible to use one IP address, prefer the wired + connection for both performance and security reasons, while + maintaining the ability to transfer data over the wireless + connection.</para> + + <para>In this setup, we will need to override the underlying + wireless interface's <acronym>MAC</acronym> address to match + the &man.lagg.4;'s, which is inherited from the master + interface being used, the wired interface.</para> + + <para>In this setup, we will treat the wired interface, + <replaceable>bge0</replaceable>, as the master, and the + wireless interface, <replaceable>wlan0</replaceable>, as the + failover interface. The <replaceable>wlan0</replaceable> + was created from <replaceable>iwn0</replaceable> which we + will set up with the wired connection's + <acronym>MAC</acronym> address. The first step would be to + obtain the <acronym>MAC</acronym> address from the wired + interface:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput> +bge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=19b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4> + ether 00:21:70:da:ae:37 + inet6 fe80::221:70ff:feda:ae37%bge0 prefixlen 64 scopeid 0x2 + nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL> + media: Ethernet autoselect (1000baseT <full-duplex>) + status: active</screen> + + <para>You can replace the <replaceable>bge0</replaceable> to + match your reality, and will get a different + <literal>ether</literal> line which is the + <acronym>MAC</acronym> address of your wired interface. + Now, we change the underlying wireless interface, + <replaceable>iwn0</replaceable>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen> + + <para>Bring up the wireless interface but don't set up any IP + address on it:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen> + + <para>Bring the <replaceable>bge0</replaceable> interface up. + Create the &man.lagg.4; interface with + <replaceable>bge0</replaceable> as master, and failover to + <replaceable>wlan0</replaceable> if necessary:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen> + + <para>The interface will look something like this, the major + differences will be the <acronym>MAC</acronym> address and + the device names:</para> + + <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput> +lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:21:70:da:ae:37 + media: Ethernet autoselect + status: active + laggproto failover + laggport: wlan0 flags=0<> + laggport: bge0 flags=5<MASTER,ACTIVE></screen> + + <para>Then start the DHCP client to obtain an IP + address:</para> + + <screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen> + + <para>To retain this configuration across reboots, the + following entries can be added to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_bge0="up" +ifconfig_iwn0="ether 00:21:70:da:ae:37" +wlans_iwn0="wlan0" +ifconfig_wlan0="WPA" +cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" +ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport bge0 laggport wlan0 DHCP"</programlisting> + </example> + </sect2> + </sect1> + + <sect1 id="network-diskless"> + <sect1info> + <authorgroup> + <author> + <firstname>Jean-François</firstname> + <surname>Dockè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 4.2</application> is not part of + the base system. You will first need to install the + <filename role="package">net/isc-dhcp42-server</filename> + port or the corresponding package.</para> + + <para>Once <application>ISC DHCP</application> is installed, + it needs a configuration file to run (normally named + <filename>/usr/local/etc/dhcpd.conf</filename>). Here + follows a commented example, where host + <hostid>margaux</hostid> uses + <application>Etherboot</application> and host + <hostid>corbieres</hostid> uses + <acronym>PXE</acronym>:</para> + + <programlisting>default-lease-time 600; +max-lease-time 7200; +authoritative; + +option domain-name "example.com"; +option domain-name-servers 192.168.4.1; +option routers 192.168.4.1; + +subnet 192.168.4.0 netmask 255.255.255.0 { + use-host-decl-names on; <co id="co-dhcp-host-name"/> + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.4.255; + + host margaux { + hardware ethernet 01:23:45:67:89:ab; + fixed-address margaux.example.com; + next-server 192.168.4.4; <co id="co-dhcp-next-server"/> + filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename"/> + option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path"/> + } + host corbieres { + hardware ethernet 00:02:b3:27:62:df; + fixed-address corbieres.example.com; + next-server 192.168.4.4; + filename "pxeboot"; + option root-path "192.168.4.4:/data/misc/diskless"; + } +}</programlisting> + + <calloutlist> + <callout arearefs="co-dhcp-host-name"> + <para>This option tells <application>dhcpd</application> + to send the value in the <literal>host</literal> + declarations as the hostname for the diskless host. + An alternate way would be to add an <literal>option + host-name + <replaceable>margaux</replaceable></literal> inside + the <literal>host</literal> declarations.</para> + </callout> + + <callout arearefs="co-dhcp-next-server"> + <para>The <literal>next-server</literal> directive + designates the <acronym>TFTP</acronym> or + <acronym>NFS</acronym> server to use for loading + loader or kernel file (the default is to use the same + host as the <acronym>DHCP</acronym> server).</para> + </callout> + + <callout arearefs="co-dhcp-filename"> + <para>The <literal>filename</literal> directive + defines the file that + <application>Etherboot</application> or + <acronym>PXE</acronym> will load for the next execution + step. It must be specified according to the transfer + method used. <application>Etherboot</application> can + be compiled to use <acronym>NFS</acronym> or + <acronym>TFTP</acronym>. The &os; port configures + <acronym>NFS</acronym> by default. + <acronym>PXE</acronym> uses <acronym>TFTP</acronym>, + which is why a relative filename is used here (this may + depend on the <acronym>TFTP</acronym> server + configuration, but would be fairly typical). Also, + <acronym>PXE</acronym> loads + <filename>pxeboot</filename>, not the kernel. There are + other interesting possibilities, like loading + <filename>pxeboot</filename> from a &os; CD-ROM + <filename class="directory">/boot</filename> directory + (as &man.pxeboot.8; can load a + <filename>GENERIC</filename> kernel, this makes it + possible to use <acronym>PXE</acronym> to boot from a + remote CD-ROM).</para> + </callout> + + <callout arearefs="co-dhcp-root-path"> + <para>The <literal>root-path</literal> option defines + the path to the root file system, in usual + <acronym>NFS</acronym> notation. When using + <acronym>PXE</acronym>, it is possible to leave off the + host's IP as long as you do not enable the kernel option + BOOTP. The <acronym>NFS</acronym> server will then be + the same as the <acronym>TFTP</acronym> one.</para> + </callout> + </calloutlist> + </sect3> + + <sect3> + <title>Configuration Using BOOTP</title> + + <indexterm> + <primary>BOOTP</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>Here follows an equivalent + <application>bootpd</application> configuration (reduced to + one client). This would be found in + <filename>/etc/bootptab</filename>.</para> + + <para>Please note that <application>Etherboot</application> + must be compiled with the non-default option + <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, + and that <acronym>PXE</acronym> <emphasis>needs</emphasis> + <acronym>DHCP</acronym>. The only obvious advantage of + <application>bootpd</application> is that it exists in the + base system.</para> + + <programlisting>.def100:\ + :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\ + :sm=255.255.255.0:\ + :ds=192.168.4.1:\ + :gw=192.168.4.1:\ + :hd="/tftpboot":\ + :bf="/kernel.diskless":\ + :rp="192.168.4.4:/data/misc/diskless": + +margaux:ha=0123456789ab:tc=.def100</programlisting> + </sect3> + + <sect3> + <title>Preparing a Boot Program with + <application>Etherboot</application></title> + + <indexterm> + <primary>Etherboot</primary> + </indexterm> + + <para><ulink + url="http://etherboot.sourceforge.net">Etherboot's Web + site</ulink> contains <ulink + url="http://etherboot.sourceforge.net/doc/html/userman/t1.html"> + extensive documentation</ulink> mainly intended for Linux + systems, but nonetheless containing useful information. The + following will just outline how you would use + <application>Etherboot</application> on a FreeBSD + system.</para> + + <para>You must first install the + <filename role="package">net/etherboot</filename> package or + port.</para> + + <para>You can change the <application>Etherboot</application> + configuration (i.e., to use <acronym>TFTP</acronym> instead + of <acronym>NFS</acronym>) by editing the + <filename>Config</filename> file in the + <application>Etherboot</application> source + directory.</para> + + <para>For our setup, we shall use a boot floppy. For other + methods (PROM, or &ms-dos; program), please refer to the + <application>Etherboot</application> documentation.</para> + + <para>To make a boot floppy, insert a floppy in the drive on + the machine where you installed + <application>Etherboot</application>, then change your + current directory to the <filename>src</filename> directory + in the <application>Etherboot</application> tree and + type:</para> + + <screen>&prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput></screen> + + <para><replaceable>devicetype</replaceable> depends on the + type of the Ethernet card in the diskless workstation. + Refer to the <filename>NIC</filename> file in the same + directory to determine the right + <replaceable>devicetype</replaceable>.</para> + </sect3> + + <sect3> + <title>Booting with <acronym>PXE</acronym></title> + + <para>By default, the &man.pxeboot.8; loader loads the kernel + via <acronym>NFS</acronym>. It can be compiled to use + <acronym>TFTP</acronym> instead by specifying the + <literal>LOADER_TFTP_SUPPORT</literal> option in + <filename>/etc/make.conf</filename>. See the comments in + <filename>/usr/share/examples/etc/make.conf</filename> for + instructions.</para> + + <para>There are two other <filename>make.conf</filename> + options which may be useful for setting up a serial console + diskless machine: + <literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and + <literal>BOOT_PXELDR_ALWAYS_SERIAL</literal>.</para> + + <para>To use <acronym>PXE</acronym> when the machine starts, + you will usually need to select the <literal>Boot from + network</literal> option in your <acronym>BIOS</acronym> + setup, or type a function key during the PC + initialization.</para> + </sect3> + + <sect3> + <title>Configuring the <acronym>TFTP</acronym> and + <acronym>NFS</acronym> Servers</title> + + <indexterm> + <primary>TFTP</primary> + <secondary>diskless operation</secondary> + </indexterm> + <indexterm> + <primary>NFS</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>If you are using <acronym>PXE</acronym> or + <application>Etherboot</application> configured to use + <acronym>TFTP</acronym>, you need to enable + <application>tftpd</application> on the file server:</para> + + <procedure> + <step> + <para>Create a directory from which + <application>tftpd</application> will serve the files, + e.g., <filename>/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 && make buildkernel +make installworld && make installkernel +cd /usr/src/etc; make distribution</programlisting> + + <para>Once done, you may need to customize your + <filename>/etc/rc.conf</filename> and + <filename>/etc/fstab</filename> placed into + <envar>DESTDIR</envar> according to your needs.</para> + </sect4> + </sect3> + + <sect3> + <title>Configuring Swap</title> + + <para>If needed, a swap file located on the server can be + accessed via <acronym>NFS</acronym>.</para> + + <sect4> + <title><acronym>NFS</acronym> Swap</title> + + <para>The kernel does not support enabling + <acronym>NFS</acronym> swap at boot time. Swap must be + enabled by the startup scripts, by mounting a writable + file system and creating and enabling a swap file. To + create a swap file of appropriate size, you can do like + this:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen> + + <para>To enable it you have to add the following line to + your <filename>rc.conf</filename>:</para> + + <programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting> + </sect4> + </sect3> + + <sect3> + <title>Miscellaneous Issues</title> + + <sect4> + <title>Running with a Read-only + <filename>/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-pxe-nfs"> + <sect1info> + <authorgroup> + <author> + <firstname>Craig</firstname> + <surname>Rodrigues</surname> + <affiliation> + <address>rodrigc@FreeBSD.org</address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>PXE Booting with an NFS Root File System</title> + + <para>The &intel; Preboot eXecution Environment + (<acronym>PXE</acronym>) allows booting the operating system + over the network. <acronym>PXE</acronym> support is usually + provided in the <acronym>BIOS</acronym> of modern motherboards, + where it can be enabled in the <acronym>BIOS</acronym> settings + which enable booting from the network. A fully functioning + <acronym>PXE</acronym> setup also requires properly configured + <acronym>DHCP</acronym> and <acronym>TFTP</acronym> + servers.</para> + + <para>When the host computer boots, it receives information over + <acronym>DHCP</acronym> about where to obtain the initial boot + loader via TFTP. After the host computer receives this + information, it downloads the boot loader via + <acronym>TFTP</acronym>, and then executes the boot loader. + This is documented in section 2.2.1 of the <ulink + url="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot + Execution Environment (PXE) Specification</ulink>. In &os;, + the boot loader retrieved during the <acronym>PXE</acronym> + process is <filename>/boot/pxeboot</filename>. After + <filename>/boot/pxeboot</filename> executes, the &os; kernel is + loaded, and the rest of the &os; bootup sequence proceeds. + Refer to <xref linkend="boot"/> for more information about the + &os; booting process.</para> + + <sect2> + <title>Setting Up the <command>chroot</command> Environment for + the NFS Root File System</title> + + <procedure> + <step> + <para>Choose a directory which will have a &os; + installation which will be NFS mountable. For example, a + directory such as + <filename>/b/tftpboot/FreeBSD/install</filename> can be + used.</para> + + <screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput> +&prompt.root; <userinput>mkdir -p ${NFSROOTDIR}</userinput></screen> + </step> + + <step> + <para>Enable the NFS server by following the instructions + in <xref linkend="network-configuring-nfs"/>.</para> + </step> + + <step> + <para>Export the directory via NFS by adding the following + to <filename>/etc/exports</filename>:</para> + + <programlisting>/b -ro -alldirs</programlisting> + </step> + + <step> + <para>Restart the NFS server:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/nfsd restart</userinput></screen> + </step> + + <step> + <para>Enable &man.inetd.8; by following the steps outlined + in <xref linkend="network-inetd-settings"/>.</para> + </step> + + <step> + <para>Add the following line to + <filename>/etc/inetd.conf</filename>:</para> + + <programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /b/tftpboot</programlisting> + </step> + + <step> + <para>Restart inetd:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/inetd restart</userinput></screen> + </step> + + <step> + <para><link linkend="makeworld">Rebuild the &os; kernel and + userland</link>:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make buildworld</userinput> +&prompt.root; <userinput>make buildkernel</userinput></screen> + </step> + + <step> + <para>Install &os; into the directory mounted over + <acronym>NFS</acronym>:</para> + + <screen>&prompt.root; <userinput>make installworld DESTDIR=${NFSROOTDIR}</userinput> +&prompt.root; <userinput>make installkernel DESTDIR=${NFSROOTDIR}</userinput> +&prompt.root; <userinput>make distribution DESTDIR=${NFSROOTDIR}</userinput></screen> + </step> + + <step> + <para>Test that the <acronym>TFTP</acronym> server works and + can download the boot loader which will be obtained + via PXE:</para> + + <screen>&prompt.root; <userinput>tftp localhost</userinput> +tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> +Received 264951 bytes in 0.1 seconds</screen> + </step> + + <step> + <para>Edit <filename>${NFSROOTDIR}/etc/fstab</filename> and + create an entry to mount the root file system over + NFS:</para> + + <programlisting># Device Mountpoint FSType Options Dump Pass +myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0</programlisting> + + <para>Replace + <replaceable>myhost.example.com</replaceable> with the + hostname or IP address of your <acronym>NFS</acronym> + server. In this example, the root file system is mounted + "read-only" in order to prevent <acronym>NFS</acronym> + clients from potentially deleting the contents of the root + file system.</para> + </step> + + <step> + <para>Set the root password in the &man.chroot.8; + environment.</para> + + <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput> +&prompt.root; <userinput>passwd</userinput></screen> + + <para>This will set the root password for client + machines which are <acronym>PXE</acronym> + booting.</para> + </step> + + <step> + <para>Enable ssh root logins for client machines which are + <acronym>PXE</acronym> booting by editing + <filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename> and + enabling the <literal>PermitRootLogin</literal> option. + This is documented in &man.sshd.config.5;.</para> + </step> + + <step> + <para>Perform other customizations of the &man.chroot.8; + environment in ${NFSROOTDIR}. These customizations could + include things like adding packages with &man.pkg.add.1;, + editing the password file with &man.vipw.8;, or editing + &man.amd.conf.5; maps for automounting. For + example:</para> + + <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput> +&prompt.root; <userinput>pkg_add -r bash</userinput></screen> + </step> + </procedure> + </sect2> + + <sect2> + <title>Configuring Memory File Systems Used by + <filename>/etc/rc.initdiskless</filename></title> + + <para>If you boot from an NFS root volume, + <filename>/etc/rc</filename> detects that you booted over NFS + and runs the <filename>/etc/rc.initdiskless</filename> script. + Read the comments in this script to understand what is going + on. We need to make <filename>/etc</filename> and + <filename>/var</filename> memory backed file systems because + these directories need to be writable, but the NFS root + directory is read-only.</para> + + <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput> +&prompt.root; <userinput>mkdir -p conf/base</userinput> +&prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput> +&prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen> + + <para>When the system boots, memory file systems for + <filename>/etc</filename> and <filename>/var</filename> will + be created and mounted, and the contents of the + <filename>cpio.gz</filename> files will be copied into + them.</para> + </sect2> + + <sect2 id="network-pxe-setting-up-dhcp"> + <title>Setting up the DHCP Server</title> + + <para>PXE requires a <acronym>TFTP</acronym> server and a + <acronym>DHCP</acronym> server to be set up. The + <acronym>DHCP</acronym> server does not necessarily need to be + the same machine as the <acronym>TFTP</acronym> server, but it + needs to be accessible in your network.</para> + + <procedure> + <step> + <para>Install the <acronym>DHCP</acronym> server by + following the instructions documented at + <xref linkend="network-dhcp-server"/>. Make sure that + <filename>/etc/rc.conf</filename> and + <filename>/usr/local/etc/dhcpd.conf</filename> are + correctly configured.</para> + </step> + + <step> + <para>In <filename>/usr/local/etc/dhcpd.conf</filename>, + configure the <literal>next-server</literal>, + <literal>filename</literal>, and + <literal>option root-path</literal> settings, to specify + your <acronym>TFTP</acronym> server IP address, the path + to <filename>/boot/pxeboot</filename> in + <acronym>TFTP</acronym>, and the path to the + <acronym>NFS</acronym> root file system. Here is a sample + <filename>dhcpd.conf</filename> setup:</para> + + <programlisting>subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.2 192.168.0.3 ; + option subnet-mask 255.255.255.0 ; + option routers 192.168.0.1 ; + option broadcast-address 192.168.0.255 ; + option domain-name-server 192.168.35.35, 192.168.35.36 ; + option domain-name "example.com"; + + # IP address of TFTP server + next-server 192.168.0.1 ; + + # path of boot loader obtained + # via tftp + filename "FreeBSD/install/boot/pxeboot" ; + + # pxeboot boot loader will try to NFS mount this directory for root FS + option root-path "192.168.0.1:/b/tftpboot/FreeBSD/install/" ; + +}</programlisting> + </step> + </procedure> + </sect2> + + <sect2> + <title>Configuring the PXE Client and Debugging Connection + Problems</title> + + <procedure> + <step> + <para>When the client machine boots up, enter the + <acronym>BIOS</acronym> configuration menu. Configure the + <acronym>BIOS</acronym> to boot from the network. If all + your previous configuration steps are correct, then + everything should "just work".</para> + </step> + + <step> + + <para>Use the + <filename role="package">net/wireshark</filename> port to + debug the network traffic involved during the + <acronym>PXE</acronym> booting process, which is + illustrated in the diagram below. In + <xref linkend="network-pxe-setting-up-dhcp"/>, an example + configuration is shown where the <acronym>DHCP</acronym>, + <acronym>TFTP</acronym>, and <acronym>NFS</acronym> + servers are actually on the same machine. However, these + severs can be on separate machines.</para> + + <figure> + <title>PXE Booting process with NFS root mount</title> + + <mediaobjectco> + <imageobjectco> + <areaspec units="calspair"> + <area id="co-pxenfs1" coords="2873,8133 3313,7266"/> + <area id="co-pxenfs2" coords="3519,6333 3885,5500"/> + <area id="co-pxenfs3" coords="4780,5866 5102,5200"/> + <area id="co-pxenfs4" coords="4794,4333 5102,3600"/> + <area id="co-pxenfs5" coords="3108,2666 3519,1800"/> + </areaspec> + <imageobject> + <imagedata fileref="advanced-networking/pxe-nfs"/> + </imageobject> + <calloutlist> + <callout arearefs="co-pxenfs1"> + <para>Client broadcasts DHCPDISCOVER.</para> + </callout> + <callout arearefs="co-pxenfs2"> + <para>DHCP server responds with IP address, + <literal>next-server</literal>, + <literal>filename</literal>, and + <literal>root-path</literal>.</para> + </callout> + <callout arearefs="co-pxenfs3"> + <para>Client sends <acronym>TFTP</acronym> + request to <literal>next-server</literal> + asking to retrieve + <literal>filename</literal>.</para> + </callout> + <callout arearefs="co-pxenfs4"> + <para>TFTP server responds and sends + <literal>filename</literal> to client.</para> + </callout> + <callout arearefs="co-pxenfs5"> + <para>Client executes + <literal>filename</literal> which is + &man.pxeboot.8;. &man.pxeboot.8; loads the + kernel. When the kernel executes, the root + filesystem specified by + <literal>root-path</literal> is mounted over + <acronym>NFS</acronym>.</para> + </callout> + </calloutlist> + </imageobjectco> + </mediaobjectco> + </figure> + </step> + + <step> + <para>Make sure that the <filename>pxeboot</filename> file + can be retrieved by <acronym>TFTP</acronym>. On your + <acronym>TFTP</acronym> server, look in + <filename>/var/log/xferlog</filename> to ensure that the + <filename>pxeboot</filename> file is being retrieved from + the correct location. To test the configuration from + <filename>dhcpd.conf</filename> above:</para> + + <screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput> +tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> +Received 264951 bytes in 0.1 seconds</screen> + + <para>Read &man.tftpd.8; and &man.tftp.1;. The + <literal>BUGS</literal> sections in these pages document + some limitations with <acronym>TFTP</acronym>.</para> + </step> + + <step> + <para>Make sure that the root file system can be mounted + via <acronym>NFS</acronym>. To test configuration from + <filename>dhcpd.conf</filename> above:</para> + + <screen>&prompt.root; <userinput>mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt</userinput></screen> + </step> + + <step> + <para>Read the code in + <filename>src/sys/boot/i386/libi386/pxe.c</filename> to + understand how the <filename>pxeboot</filename> loader + sets variables like <literal>boot.nfsroot.server</literal> + and <literal>boot.nfsroot.path</literal>. These variables + are then used in the NFS diskless root mount code in + <filename>src/sys/nfsclient/nfs_diskless.c</filename>.</para> + </step> + + <step> + <para>Read &man.pxeboot.8; and &man.loader.8;.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="network-isdn"> + <title>ISDN</title> + + <indexterm> + <primary>ISDN</primary> + </indexterm> + + <para>A good resource for information on ISDN technology and + hardware is + <ulink url="http://www.alumni.caltech.edu/~dank/isdn/">Dan + Kegel's ISDN Page</ulink>.</para> + + <para>A quick simple road map to ISDN follows:</para> + + <itemizedlist> + <listitem> + <para>If you live in Europe you might want to investigate the + ISDN card section.</para> + </listitem> + + <listitem> + <para>If you are planning to use ISDN primarily to connect to + the Internet with an Internet Provider on a dial-up + non-dedicated basis, you might look into Terminal Adapters. + This will give you the most flexibility, with the fewest + problems, if you change providers.</para> + </listitem> + + <listitem> + <para>If you are connecting two LANs together, or connecting + to the Internet with a dedicated ISDN connection, you might + consider the stand alone router/bridge option.</para> + </listitem> + </itemizedlist> + + <para>Cost is a significant factor in determining what solution + you will choose. The following options are listed from least + expensive to most expensive.</para> + + <sect2 id="network-isdn-cards"> + <sect2info> + <authorgroup> + <author> + <firstname>Hellmuth</firstname> + <surname>Michaelis</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>ISDN Cards</title> + + <indexterm> + <primary>ISDN</primary> + <secondary>cards</secondary> + </indexterm> + + <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931 + (or Euro-ISDN) standard using passive cards. Some active + cards are supported where the firmware also supports other + signaling protocols; this also includes the first supported + Primary Rate (PRI) ISDN card.</para> + + <para>The <application>isdn4bsd</application> software allows + you to connect to other ISDN routers using either IP over raw + HDLC or by using synchronous PPP: either by using kernel PPP + with <literal>isppp</literal>, a modified &man.sppp.4; driver, + or by using userland &man.ppp.8;. By using userland + &man.ppp.8;, channel bonding of two or more ISDN B-channels is + possible. A telephone answering machine application is also + available as well as many utilities such as a software 300 + Baud modem.</para> + + <para>Some growing number of PC ISDN cards are supported under + FreeBSD and the reports show that it is successfully used all + over Europe and in many other parts of the world.</para> + + <para>The passive ISDN cards supported are mostly the ones with + the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, + but also ISDN cards with chips from Cologne Chip (ISA bus + only), PCI cards with Winbond W6692 chips, some cards with the + Tiger300/320/ISAC chipset combinations and some vendor + specific chipset based cards such as the AVM Fritz!Card PCI + V.1.0 and the AVM Fritz!Card PnP.</para> + + <para>Currently the active supported ISDN cards are the AVM B1 + (ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para> + + <para>For documentation on <application>isdn4bsd</application>, + have a look at the + <ulink url="http://www.freebsd-support.de/i4b/">homepage of + isdn4bsd</ulink> which also has pointers to hints, erratas + and much more documentation such as the <ulink + url="http://people.FreeBSD.org/~hm/">isdn4bsd + handbook</ulink>.</para> + + <para>In case you are interested in adding support for a + different ISDN protocol, a currently unsupported ISDN PC card + or otherwise enhancing <application>isdn4bsd</application>, + please get in touch with &a.hm;.</para> + + <para>For questions regarding the installation, configuration + and troubleshooting <application>isdn4bsd</application>, a + &a.isdn.name; mailing list is available.</para> + </sect2> + + <sect2> + <title>ISDN Terminal Adapters</title> + + <para>Terminal adapters (TA), are to ISDN what modems are to + regular phone lines.</para> + + <indexterm><primary>modem</primary></indexterm> + <para>Most TA's use the standard Hayes modem AT command set, and + can be used as a drop in replacement for a modem.</para> + + <para>A TA will operate basically the same as a modem except + connection and throughput speeds will be much faster than your + old modem. You will need to configure + <link linkend="ppp">PPP</link> exactly the same as for a modem + setup. Make sure you set your serial speed as high as + possible.</para> + + <indexterm><primary>PPP</primary></indexterm> + <para>The main advantage of using a TA to connect to an Internet + Provider is that you can do Dynamic PPP. As IP address space + becomes more and more scarce, most providers are not willing + to provide you with a static IP 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 Kbs, even though you have a + 128 Kbs connection. To fully utilize the 128 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 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—one for connecting to the Internet router, the + other connecting to a LAN. All the machines on the LAN are + connected through a hub or switch.</para> + + <note> + <para>There are many ways to get a LAN connected to the + Internet through a &os; gateway. This example will only + cover a gateway with at least two NICs.</para> + </note> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/natd"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> _______ __________ ________ + | | | | | | + | Hub |-----| Client B |-----| Router |----- Internet + |_______| |__________| |________| + | + ____|_____ +| | +| Client A | +|__________|</literallayout> + </textobject> + + <textobject> + <phrase>Network Layout</phrase> + </textobject> + </mediaobject> + + <para>A setup like this is commonly used to share an Internet + connection. One of the <acronym>LAN</acronym> machines is + connected to the Internet. The rest of the machines access + the Internet through that <quote>gateway</quote> + machine.</para> + </sect2> + + <sect2 id="network-natdloaderconfiguration"> + <title>Boot Loader Configuration</title> + + <indexterm> + <primary>boot loader</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>The kernel features for network address translation with + &man.natd.8; are not enabled in the + <filename>GENERIC</filename> kernel, but they can be preloaded + at boot time, by adding a couple of options to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>ipfw_load="YES" +ipdivert_load="YES"</programlisting> + + <para>Additionally, the + <literal>net.inet.ip.fw.default_to_accept</literal> tunable + option may be set to <literal>1</literal>:</para> + + <programlisting>net.inet.ip.fw.default_to_accept="1"</programlisting> + + <note> + <para>It is a very good idea to set this option during the + first attempts to setup a firewall and NAT gateway. This + way the default policy of &man.ipfw.8; will be + <literal>allow ip from any to any</literal> instead of the + less permissive <literal>deny ip from any to any</literal>, + and it will be slightly more difficult to get locked out of + the system right after a reboot.</para> + </note> + </sect2> + + <sect2 id="network-natdkernconfiguration"> + <title>Kernel Configuration</title> + + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> + <para>When modules are not an option or if it is preferrable to + build all the required features into the running kernel, the + following options must be in the kernel configuration + file:</para> + + <programlisting>options IPFIREWALL +options IPDIVERT</programlisting> + + <para>Additionally, at choice, the following may also be + suitable:</para> + + <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT +options IPFIREWALL_VERBOSE</programlisting> + </sect2> + + <sect2 id="network-natdsystemconfiguration"> + <title>System Startup Configuration</title> + + <para>To enable firewall and NAT support at boot time, the + following must be in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"/> +firewall_enable="YES" <co id="co-natd-firewall-enable"/> +firewall_type="OPEN" <co id="co-natd-firewall-type"/> +natd_enable="YES" +natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface"/> +natd_flags="" <co id="co-natd-natd-flags"/></programlisting> + + <calloutlist> + <callout arearefs="co-natd-gateway-enable"> + <para>Sets up the machine to act as a gateway. Running + <command>sysctl net.inet.ip.forwarding=1</command> would + have the same effect.</para> + </callout> + + <callout arearefs="co-natd-firewall-enable"> + <para>Enables the firewall rules in + <filename>/etc/rc.firewall</filename> at boot.</para> + </callout> + + <callout arearefs="co-natd-firewall-type"> + <para>This specifies a predefined firewall ruleset that + allows anything in. See + <filename>/etc/rc.firewall</filename> for additional + types.</para> + </callout> + + <callout arearefs="co-natd-natd-interface"> + <para>Indicates which interface to forward packets through + (the interface connected to the Internet).</para> + </callout> + + <callout arearefs="co-natd-natd-flags"> + <para>Any additional configuration options passed to + &man.natd.8; on boot.</para> + </callout> + </calloutlist> + + <para>Having the previous options defined in + <filename>/etc/rc.conf</filename> would run + <command>natd -interface fxp0</command> at boot. This can + also be run manually.</para> + + <note> + <para>It is also possible to use a configuration file for + &man.natd.8; when there are too many options to pass. In + this case, the configuration file must be defined by adding + the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>natd_flags="-f /etc/natd.conf"</programlisting> + + <para>The <filename>/etc/natd.conf</filename> file will + contain a list of configuration options, one per line. For + example the next section case would use the following + file:</para> + + <programlisting>redirect_port tcp 192.168.0.2:6667 6667 +redirect_port tcp 192.168.0.3:80 80</programlisting> + + <para>For more information about the configuration file, + consult the &man.natd.8; manual page about the + <option>-f</option> option.</para> + </note> + + <para>Each machine and interface behind the LAN should be + assigned IP address numbers in the private network space as + defined by + <ulink url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC + 1918</ulink> and have a default gateway of the + <application>natd</application> machine's internal IP + address.</para> + + <para>For example, client <hostid>A</hostid> and + <hostid>B</hostid> behind the LAN have IP addresses of + <hostid role="ipaddr">192.168.0.2</hostid> and + <hostid role="ipaddr">192.168.0.3</hostid>, while the natd + machine's LAN interface has an IP address of + <hostid role="ipaddr">192.168.0.1</hostid>. Client + <hostid>A</hostid> and <hostid>B</hostid>'s default gateway + must be set to that of the <application>natd</application> + machine, <hostid role="ipaddr">192.168.0.1</hostid>. The + <application>natd</application> machine's external, or + Internet interface does not require any special modification + for &man.natd.8; to work.</para> + </sect2> + + <sect2 id="network-natdport-redirection"> + <title>Port Redirection</title> + + <para>The drawback with &man.natd.8; is that the LAN clients are + not accessible from the Internet. Clients on the LAN can make + outgoing connections to the world but cannot receive incoming + ones. This presents a problem if trying to run Internet + services on one of the LAN client machines. A simple way + around this is to redirect selected Internet ports on the + <application>natd</application> machine to a LAN + client.</para> + + <para>For example, an IRC server runs on client + <hostid>A</hostid>, and a web server runs on client + <hostid>B</hostid>. For this to work properly, connections + received on ports 6667 (IRC) and 80 (web) must be redirected + to the respective machines.</para> + + <para>The <option>-redirect_port</option> must be passed to + &man.natd.8; with the proper options. The syntax is as + follows:</para> + + <programlisting> -redirect_port proto targetIP:targetPORT[-targetPORT] + [aliasIP:]aliasPORT[-aliasPORT] + [remoteIP[:remotePORT[-remotePORT]]]</programlisting> + + <para>In the above example, the argument should be:</para> + + <programlisting> -redirect_port tcp 192.168.0.2:6667 6667 + -redirect_port tcp 192.168.0.3:80 80</programlisting> + + <para>This will redirect the proper <emphasis>tcp</emphasis> + ports to the LAN client machines.</para> + + <para>The <option>-redirect_port</option> argument can be used + to indicate port ranges over individual ports. For example, + <replaceable>tcp 192.168.0.2:2000-3000 2000-3000</replaceable> + would redirect all connections received on ports 2000 to 3000 + to ports 2000 to 3000 on client <hostid>A</hostid>.</para> + + <para>These options can be used when directly running + &man.natd.8;, placed within the + <literal>natd_flags=""</literal> option in + <filename>/etc/rc.conf</filename>, or passed via a + configuration file.</para> + + <para>For further configuration options, consult + &man.natd.8;</para> + </sect2> + + <sect2 id="network-natdaddress-redirection"> + <title>Address Redirection</title> + + <indexterm><primary>address redirection</primary></indexterm> + <para>Address redirection is useful if several IP addresses are + available, yet they must be on one machine. With this, + &man.natd.8; can assign each LAN client its own external IP + address. &man.natd.8; then rewrites outgoing packets from the + LAN clients with the proper external IP address and redirects + all traffic incoming on that particular IP address back to the + specific LAN client. This is also known as static NAT. For + example, the IP addresses + <hostid role="ipaddr">128.1.1.1</hostid>, + <hostid role="ipaddr">128.1.1.2</hostid>, and + <hostid role="ipaddr">128.1.1.3</hostid> belong to the + <application>natd</application> gateway machine. + <hostid role="ipaddr">128.1.1.1</hostid> can be used as the + <application>natd</application> gateway machine's external IP + address, while <hostid role="ipaddr">128.1.1.2</hostid> and + <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to + LAN clients <hostid>A</hostid> and <hostid>B</hostid>.</para> + + <para>The <option>-redirect_address</option> syntax is as + follows:</para> + + <programlisting>-redirect_address localIP publicIP</programlisting> + + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <tbody> + <row> + <entry>localIP</entry> + <entry>The internal IP address of the LAN + client.</entry> + </row> + + <row> + <entry>publicIP</entry> + <entry>The external IP address corresponding to the LAN + client.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>In the example, this argument would read:</para> + + <programlisting>-redirect_address 192.168.0.2 128.1.1.2 +-redirect_address 192.168.0.3 128.1.1.3</programlisting> + + <para>Like <option>-redirect_port</option>, these arguments are + also placed within the <literal>natd_flags=""</literal> option + of <filename>/etc/rc.conf</filename>, or passed via a + configuration file. With address redirection, there is no + need for port redirection since all data received on a + particular IP address is redirected.</para> + + <para>The external IP addresses on the + <application>natd</application> machine must be active and + aliased to the external interface. Look at &man.rc.conf.5; to + do so.</para> + </sect2> + </sect1> + + <sect1 id="network-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: <Printer> on ppbus0 +lpt0: Interrupt-driven port</screen> + + <para>The parallel port must be an interrupt driven port, you + should have lines 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<POINTOPOINT,SIMPLEX,MULTICAST> 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 <-----> 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 host2</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<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.1 --> 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 known as IPng <quote>IP next generation</quote>) + is the new version of the well known IP protocol (also known as + <acronym>IPv4</acronym>). Like the other current *BSD systems, + FreeBSD includes the KAME IPv6 reference implementation. So + your FreeBSD system comes with all you will need to experiment + with IPv6. This section focuses on getting IPv6 configured and + running.</para> + + <para>In the early 1990s, people became aware of the rapidly + diminishing address space of IPv4. Given the expansion rate of + the Internet there were two major concerns:</para> + + <itemizedlist> + <listitem> + <para>Running out of addresses. Today this is not so much of + a concern 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> + </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> </entry> + </row> + + <row> + <entry><hostid role="ip6addr">ff::</hostid></entry> + <entry>8 bits</entry> + <entry>multicast</entry> + <entry> </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<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255 + inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1 + ether 00:00:21:03:08:e1 + media: Ethernet autoselect (100baseTX ) + status: active</programlisting> + + <para><hostid + role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid> + is an auto configured link-local address. It is generated + from the MAC address as part of the auto configuration.</para> + + <para>For further information on the structure of IPv6 addresses + see <ulink + url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</para> + </sect2> + + <sect2> + <title>Getting Connected</title> + + <para>Currently there are four ways to connect to other IPv6 + hosts and networks:</para> + + <itemizedlist> + <listitem> + <para>Contact your Internet Service Provider to see if they + offer IPv6 yet.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.sixxs.net">SixXS</ulink> offers + tunnels with end-points all around the globe.</para> + </listitem> + + <listitem> + <para>Tunnel via 6-to-4 (<ulink + url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para> + </listitem> + + <listitem> + <para>Use the + <filename role="package">net/freenet6</filename> port if + you are on a dial-up connection.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>DNS in the IPv6 World</title> + + <para>There used to be two types of DNS records for IPv6. The + IETF has declared A6 records obsolete. AAAA records are the + standard now.</para> + + <para>Using AAAA records is straightforward. Assign your + hostname to the new IPv6 address you just received by + adding:</para> + + <programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting> + + <para>To your primary zone DNS file. In case you do not serve + your own <acronym>DNS</acronym> zones ask your + <acronym>DNS</acronym> provider. Current versions of + <application>bind</application> (version 8.3 and 9) and + <filename role="package">dns/djbdns</filename> (with the IPv6 + patch) support AAAA records.</para> + </sect2> + + <sect2> + <title>Applying the Needed Changes to + <filename>/etc/rc.conf</filename></title> + + <sect3> + <title>IPv6 Client Settings</title> + + <para>These settings will help you configure a machine that + will be on your LAN and act as a client, not a router. To + have &man.rtsol.8; autoconfigure your interface on boot on + &os; 9.<replaceable>x</replaceable> and later, + add:</para> + + <programlisting>ipv6_prefer="YES"</programlisting> + + <para>to <filename>rc.conf</filename>.</para> + + <para>For &os; 8.<replaceable>x</replaceable> and + earlier, add:</para> + + <programlisting>ipv6_enable="YES"</programlisting> + + <para>To statically assign an IP address such as <hostid + role="ip6addr">2001:471:1f11:251:290:27ff:fee0:2093</hostid>, + to your <devicename>fxp0</devicename> interface, add the + following for &os; 9.<replaceable>x</replaceable>:</para> + + <programlisting>ifconfig_fxp0_ipv6="inet6 2001:471:1f11:251:290:27ff:fee0:2093 prefixlen <replaceable>64</replaceable>"</programlisting> + + <note> + <para>Be sure to change <replaceable>prefixlen + 64</replaceable> to the appropriate value for the subnet + within which the computer is networked.</para> + </note> + + <para>For &os; 8<replaceable>x</replaceable> and earlier, + add:</para> + + <programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting> + + <para>To assign a default router of + <hostid role="ip6addr">2001:471:1f11:251::1</hostid> add the + following to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting> + </sect3> + + <sect3> + <title>IPv6 Router/Gateway Settings</title> + + <para>This will help you take the directions that your tunnel + provider has given you and convert it into settings that + will persist through reboots. To restore your tunnel on + startup use something like the following in + <filename>/etc/rc.conf</filename>:</para> + + <para>List the Generic Tunneling interfaces that will be + configured, for example + <devicename>gif0</devicename>:</para> + + <programlisting>gif_interfaces="gif0"</programlisting> + + <para>To configure the interface with a local endpoint of + <replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint + of <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para> + + <programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting> + + <para>To apply the IPv6 address you have been assigned for use + as your IPv6 tunnel endpoint, add the following for + &os; 9.<replaceable>x</replaceable> and later:</para> + + <programlisting>ifconfig_gif0_ipv6="inet6 <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + + <para>For &os; 8.<replaceable>x</replaceable> and + earlier, add:</para> + + <programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + <para>Then all you have to do is set the default route for + IPv6. This is the other side of the IPv6 tunnel:</para> + + <programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + </sect3> + + <sect3> + <title>IPv6 Tunnel Settings</title> + + <para>If the server is to route IPv6 between the rest of your + network and the world, the following + <filename>/etc/rc.conf</filename> setting will also be + needed:</para> + + <programlisting>ipv6_gateway_enable="YES"</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Router Advertisement and Host Auto Configuration</title> + + <para>This section will help you setup &man.rtadvd.8; to + advertise the IPv6 default route.</para> + + <para>To enable &man.rtadvd.8; you will need the following in + your <filename>/etc/rc.conf</filename>:</para> + + <programlisting>rtadvd_enable="YES"</programlisting> + + <para>It is important that you specify the interface on which to + do IPv6 router solicitation. For example to tell + &man.rtadvd.8; to use <devicename>fxp0</devicename>:</para> + + <programlisting>rtadvd_interfaces="fxp0"</programlisting> + + <para>Now we must create the configuration file, + <filename>/etc/rtadvd.conf</filename>. Here is an + example:</para> + + <programlisting>fxp0:\ + :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting> + + <para>Replace <devicename>fxp0</devicename> with the interface + you are going to be using.</para> + + <para>Next, replace + <hostid role="ip6addr">2001:471:1f11:246::</hostid> with the + prefix of your allocation.</para> + + <para>If you are dedicated a <hostid role="netmask">/64</hostid> + subnet you will not need to change anything else. Otherwise, + you will need to change the <literal>prefixlen#</literal> to + the correct value.</para> + </sect2> + </sect1> + + <sect1 id="network-atm"> + <sect1info> + <authorgroup> + <author> + <firstname>Harti</firstname> + <surname>Brandt</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Asynchronous Transfer Mode (ATM)</title> + + <sect2> + <title>Configuring Classical IP over ATM (PVCs)</title> + + <para>Classical IP over ATM (<acronym>CLIP</acronym>) is the + simplest method to use Asynchronous Transfer Mode (ATM) + with IP. It can be used with + switched connections (SVCs) and with permanent connections + (PVCs). This section describes how to set up a network based + on PVCs.</para> + + <sect3> + <title>Fully Meshed Configurations</title> + + <para>The first method to set up a <acronym>CLIP</acronym> + with PVCs is to connect each machine to each other machine + in the network via a dedicated PVC. While this is simple to + configure it tends to become impractical for a larger number + of machines. The example supposes that we have four + machines in the network, each connected to the + <acronym role="Asynchronous Transfer Mode">ATM</acronym> + network with an + <acronym role="Asynchronous Transfer Mode">ATM</acronym> + adapter card. The first step is the planning of the IP + addresses and the + <acronym role="Asynchronous Transfer Mode">ATM</acronym> + connections between the machines. We use the + following:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Host</entry> + <entry>IP Address</entry> + </row> + </thead> + + <tbody> + <row> + <entry><hostid>hostA</hostid></entry> + <entry><hostid + role="ipaddr">192.168.173.1</hostid></entry> + </row> + + <row> + <entry><hostid>hostB</hostid></entry> + <entry><hostid + role="ipaddr">192.168.173.2</hostid></entry> + </row> + + <row> + <entry><hostid>hostC</hostid></entry> + <entry><hostid + role="ipaddr">192.168.173.3</hostid></entry> + </row> + + <row> + <entry><hostid>hostD</hostid></entry> + <entry><hostid + role="ipaddr">192.168.173.4</hostid></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>To build a fully meshed net we need one ATM connection + between each pair of machines:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Machines</entry> + <entry>VPI.VCI couple</entry> + </row> + </thead> + + <tbody> + <row> + <entry><hostid>hostA</hostid> - + <hostid>hostB</hostid></entry> + <entry>0.100</entry> + </row> + + <row> + <entry><hostid>hostA</hostid> - + <hostid>hostC</hostid></entry> + <entry>0.101</entry> + </row> + + <row> + <entry><hostid>hostA</hostid> - + <hostid>hostD</hostid></entry> + <entry>0.102</entry> + </row> + + <row> + <entry><hostid>hostB</hostid> - + <hostid>hostC</hostid></entry> + <entry>0.103</entry> + </row> + + <row> + <entry><hostid>hostB</hostid> - + <hostid>hostD</hostid></entry> + <entry>0.104</entry> + </row> + + <row> + <entry><hostid>hostC</hostid> - + <hostid>hostD</hostid></entry> + <entry>0.105</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>The VPI and VCI values at each end of the connection may + of course differ, but for simplicity we assume that they are + the same. Next we need to configure the ATM interfaces on + each host:</para> + + <screen>hostA&prompt.root; <userinput>ifconfig hatm0 192.168.173.1 up</userinput> +hostB&prompt.root; <userinput>ifconfig hatm0 192.168.173.2 up</userinput> +hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput> +hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen> + + <para>assuming that the ATM interface is + <devicename>hatm0</devicename> on all hosts. Now the PVCs + need to be configured on <hostid>hostA</hostid> (we assume + that they are already configured on the ATM switches, you + need to consult the manual for the switch on how to do + this).</para> + + <screen>hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr</userinput> +hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr</userinput> +hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr</userinput> + +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr</userinput> +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr</userinput> +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr</userinput> + +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr</userinput> +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr</userinput> +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr</userinput> + +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr</userinput> +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr</userinput> +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</userinput></screen> + + <para>Of course other traffic contracts than UBR can be used + given the ATM adapter supports those. In this case the name + of the traffic contract is followed by the parameters of the + traffic. Help for the &man.atmconfig.8; tool can be + obtained with:</para> + + <screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen> + + <para>or in the &man.atmconfig.8; manual page.</para> + + <para>The same configuration can also be done via + <filename>/etc/rc.conf</filename>. For + <hostid>hostA</hostid> this would look like:</para> + + <programlisting>network_interfaces="lo0 hatm0" +ifconfig_hatm0="inet 192.168.173.1 up" +natm_static_routes="hostB hostC hostD" +route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr" +route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr" +route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting> + + <para>The current state of all <acronym>CLIP</acronym> routes + can be obtained with:</para> + + <screen>hostA&prompt.root; <userinput>atmconfig natm show</userinput></screen> + </sect3> + </sect2> + </sect1> + + <sect1 id="carp"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Common Address Redundancy Protocol (CARP)</title> + + <indexterm> + <primary>CARP</primary> + </indexterm> + <indexterm> + <primary>Common Address Redundancy Protocol</primary> + </indexterm> + + <para>The Common Address Redundancy Protocol, or + <acronym>CARP</acronym> allows multiple hosts to share the same + <acronym>IP</acronym> address. In some configurations, this may + be used for availability or load balancing. Hosts may use + separate <acronym>IP</acronym> addresses as well, as in the + example provided here.</para> + + <para>To enable support for <acronym>CARP</acronym>, the &os; + kernel must be rebuilt as described in + <xref linkend="kernelconfig"/> with the following option:</para> + + <programlisting>device carp</programlisting> + + <para>Alternatively, the <filename>if_carp.ko</filename> module + can be loaded at boot time. Add the following line to the + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>if_carp_load="YES"</programlisting> + + <para><acronym>CARP</acronym> functionality should now be + available and may be tuned via several <command>sysctl</command> + <acronym>OID</acronym>s:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>OID</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>net.inet.carp.allow</varname></entry> + <entry>Accept incoming <acronym>CARP</acronym> packets. + Enabled by default.</entry> + </row> + + <row> + <entry><varname>net.inet.carp.preempt</varname></entry> + <entry>This option downs all of the + <acronym>CARP</acronym> interfaces on the host when one + of them goes down. Disabled by default</entry> + </row> + + <row> + <entry><varname>net.inet.carp.log</varname></entry> + <entry>A value of <literal>0</literal> disables any + logging. A Value of <literal>1</literal> enables + logging of bad <acronym>CARP</acronym> packets. Values + greater than <literal>1</literal> enables logging of + state changes for the <acronym>CARP</acronym> + interfaces. The default value is + <literal>1</literal>.</entry> + </row> + + <row> + <entry><varname>net.inet.carp.arpbalance</varname></entry> + <entry>Balance local network traffic using + <acronym>ARP</acronym>. Disabled by default.</entry> + </row> + + <row> + <entry><varname>net.inet.carp.suppress_preempt</varname></entry> + <entry>A read only <acronym>OID</acronym> showing the + status of preemption suppression. Preemption can be + suppressed if link on an interface is down. A value of + <literal>0</literal>, means that preemption is not + suppressed. Every problem increments this + <acronym>OID</acronym>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>The <acronym>CARP</acronym> devices themselves may be + created via the <command>ifconfig</command> command:</para> + + <screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen> + + <para>In a real environment, these interfaces will need unique + identification numbers known as a <acronym>VHID</acronym>. This + <acronym>VHID</acronym> or Virtual Host Identification will be + used to distinguish the host on the network.</para> + + <sect2> + <title>Using CARP for Server Availability (CARP)</title> + + <para>One use of <acronym>CARP</acronym>, as noted above, is for + server availability. This example will provide failover + support for three hosts, all with unique <acronym>IP</acronym> + addresses and providing the same web content. These machines + will act in conjunction with a Round Robin + <acronym>DNS</acronym> configuration. The failover machine + will have two additional <acronym>CARP</acronym> interfaces, + one for each of the content server's <acronym>IP</acronym>s. + When a failure occurs, the failover server should pick up the + failed machine's <acronym>IP</acronym> address. This means + the failure should go completely unnoticed to the user. The + failover server requires identical content and services as the + other content servers it is expected to pick up load + for.</para> + + <para>The two machines should be configured identically other + than their issued hostnames and <acronym>VHID</acronym>s. + This example calls these machines + <hostid>hosta.example.org</hostid> and + <hostid>hostb.example.org</hostid> respectively. First, the + required lines for a <acronym>CARP</acronym> configuration + have to be added to <filename>rc.conf</filename>. For + <hostid>hosta.example.org</hostid>, the + <filename>rc.conf</filename> file should contain the following + lines:</para> + + <programlisting>hostname="hosta.example.org" +ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0" +cloned_interfaces="carp0" +ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24"</programlisting> + + <para>On <hostid>hostb.example.org</hostid> the following lines + should be in <filename>rc.conf</filename>:</para> + + <programlisting>hostname="hostb.example.org" +ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0" +cloned_interfaces="carp0" +ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting> + + <note> + <para>It is very important that the passwords, specified by + the <option>pass</option> option to + <command>ifconfig</command>, are identical. The + <devicename>carp</devicename> devices will only listen to + and accept advertisements from machines with the correct + password. The <acronym>VHID</acronym> must also be + different for each machine.</para> + </note> + + <para>The third machine, <hostid>provider.example.org</hostid>, + should be prepared so that it may handle failover from either + host. This machine will require two + <devicename>carp</devicename> devices, one to handle each + host. The appropriate <filename>rc.conf</filename> + configuration lines will be similar to the following:</para> + + <programlisting>hostname="provider.example.org" +ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0" +cloned_interfaces="carp0 carp1" +ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24" +ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlisting> + + <para>Having the two <devicename>carp</devicename> devices will + allow <hostid>provider.example.org</hostid> to notice and pick + up the <acronym>IP</acronym> address of either machine should + it stop responding.</para> + + <note> + <para>The default &os; kernel <emphasis>may</emphasis> have + preemption enabled. If so, + <hostid>provider.example.org</hostid> may not relinquish the + <acronym>IP</acronym> address back to the original content + server. In this case, an administrator may have to manually + force the IP back to the master. The following command + should be issued on + <hostid>provider.example.org</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen> + + <para>This should be done on the <devicename>carp</devicename> + interface which corresponds to the correct host.</para> + </note> + + <para>At this point, <acronym>CARP</acronym> should be + completely enabled and available for testing. For testing, + either networking has to be restarted or the machines need to + be rebooted.</para> + + <para>More information is always available in the &man.carp.4; + manual page.</para> + </sect2> + </sect1> +</chapter> |