diff options
| author | Giorgos Keramidas <keramida@FreeBSD.org> | 2007-11-02 16:14:25 +0000 |
|---|---|---|
| committer | Giorgos Keramidas <keramida@FreeBSD.org> | 2007-11-02 16:14:25 +0000 |
| commit | eb2c85db964d96b3169001545c017417108df9d9 (patch) | |
| tree | a1befcd68d2af62c0d3017b4c8950d0e9449c086 /el_GR.ISO8859-7/books/handbook/advanced-networking | |
| parent | 1ab7e7b80651cabc8d989a9ea71cd39f309b70ca (diff) | |
| download | doc-eb2c85db964d96b3169001545c017417108df9d9.tar.gz doc-eb2c85db964d96b3169001545c017417108df9d9.zip | |
Update of the doc/el_GR.ISO8859-7 documentation, to catch up with
the latest developments in the Greek translation team. This one
brings in many resync/MFen changes for articles, and a new book:
The Greek Handbook
We still have a lot of work to do in the Handbook tree, but the
work of the following people has been instrumental in getting us
so far already:
Giorgos Iordanou
Manolis Kiagias
Nikos Kokkalis
Leonidas Tsampros
Baggelis Typaldos
Notes
Notes:
svn path=/head/; revision=30998
Diffstat (limited to 'el_GR.ISO8859-7/books/handbook/advanced-networking')
| -rw-r--r-- | el_GR.ISO8859-7/books/handbook/advanced-networking/chapter.sgml | 4804 |
1 files changed, 4804 insertions, 0 deletions
diff --git a/el_GR.ISO8859-7/books/handbook/advanced-networking/chapter.sgml b/el_GR.ISO8859-7/books/handbook/advanced-networking/chapter.sgml new file mode 100644 index 0000000000..cd60fc622a --- /dev/null +++ b/el_GR.ISO8859-7/books/handbook/advanced-networking/chapter.sgml @@ -0,0 +1,4804 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="advanced-networking"> + <title>Προχωρημένα Θέματα Δικτύωσης</title> + + <sect1 id="advanced-networking-synopsis"> + <title>Σύνοψη</title> + + <para>Το κεφάλαιο αυτό καλύπτει προχωρημένα θέματα δικτύωσης.</para> + + <para>Αφού διαβάσετε αυτό το κεφάλαιο, θα ξέρετε:</para> + + <itemizedlist> + <listitem> + <para>Τα βασικά των πυλών (gateways) και των δρομολογήσεων + (routes).</para> + </listitem> + + <listitem> + <para>Πως να ρυθμίσετε συσκευές IEEE 802.11 και &bluetooth;.</para> + </listitem> + + <listitem> + <para>Πως να κάνετε το &os; να δρα ως γέφυρα (bridge).</para> + </listitem> + + <listitem> + <para>Πως να ρυθμίσετε εκκίνηση από το δίκτυο σε ένα μηχάνημα + χωρίς σκληρό δίσκο.</para> + </listitem> + + <listitem> + <para>Πως να ρυθμίσετε μετάφραση δικτυακών διευθύνσεων (NAT).</para> + </listitem> + + <listitem> + <para>Πως να συνδέσετε δύο υπολογιστές μέσω PLIP.</para> + </listitem> + + <listitem> + <para>Πως να ρυθμίσετε το IPv6 σε ένα μηχάνημα &os;.</para> + </listitem> + + <listitem> + <para>Πως να ρυθμίσετε το ATM.</para> + </listitem> + + <listitem> + <para>Πως να ρυθμίσετε και να χρησιμοποιήσετε τις δυνατότητες του + CARP (Common Access Redundancy Protocol) στο &os;.</para> + </listitem> + </itemizedlist> + + <para>Πριν διαβάσετε αυτό το κεφάλαιο, θα πρέπει:</para> + + <itemizedlist> + <listitem> + <para>Να κατανοείτε τις βασικές έννοιες των αρχείων script + <filename>/etc/rc</filename>.</para> + </listitem> + + <listitem> + <para>Να είστε εξοικειωμένος με τη βασική ορολογία των δικτύων.</para> + </listitem> + + <listitem> + <para>Να γνωρίζετε πως να ρυθμίσετε και να εγκαταστήσετε ένα νέο + πυρήνα στο &os; (<xref linkend="kernelconfig">).</para> + </listitem> + + <listitem> + <para>Να γνωρίζετε πως να εγκαταστήσετε πρόσθετο λογισμικό τρίτου + κατασκευαστή (<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> + <title>Dual Homed Hosts</title> + <indexterm><primary>dual homed hosts</primary></indexterm> + <para>There is one other type of configuration that we should cover, and + that is a host that sits on two different networks. Technically, any + machine functioning as a gateway (in the example above, using a PPP + connection) counts as a dual-homed host. But the term is really only + used to refer to a machine that sits on two local-area + networks.</para> + + <para>In one case, the machine has two Ethernet cards, each + having an address on the separate subnets. Alternately, the + machine may only have one Ethernet card, and be using + &man.ifconfig.8; aliasing. The former is used if two + physically separate Ethernet networks are in use, the latter + if there is one physical network segment, but two logically + separate subnets.</para> + + <para>Either way, routing tables are set up so that each subnet knows + that this machine is the defined gateway (inbound route) to the other + subnet. This configuration, with the machine acting as a router + between the two subnets, is often used when we need to implement + packet filtering or firewall security in either or both + directions.</para> + + <para>If you want this machine to actually forward packets + between the two interfaces, you need to tell FreeBSD to enable + this ability. See the next section for more details on how + to do this.</para> + </sect2> + + <sect2 id="network-dedicated-router"> + <title>Building a Router</title> + + <indexterm><primary>router</primary></indexterm> + + <para>A network router is simply a system that forwards packets + from one interface to another. Internet standards and good + engineering practice prevent the FreeBSD Project from enabling + this by default in FreeBSD. You can enable this feature by + changing the following variable to <literal>YES</literal> in + &man.rc.conf.5;:</para> + + <programlisting>gateway_enable=YES # Set to YES if this host will be a gateway</programlisting> + + <para>This option will set the &man.sysctl.8; variable + <varname>net.inet.ip.forwarding</varname> to + <literal>1</literal>. If you should need to stop routing + temporarily, you can reset this to <literal>0</literal> temporarily.</para> + + <para>Your new router will need routes to know where to send the + traffic. If your network is simple enough you can use static + routes. FreeBSD also comes with the standard BSD routing + daemon &man.routed.8;, which speaks RIP (both version 1 and + version 2) and IRDP. Support for BGP v4, OSPF v2, and other + sophisticated routing protocols is available with the + <filename role="package">net/zebra</filename> package. + Commercial products such as <application>&gated;</application> are also available for more + complex network routing solutions.</para> + +<indexterm><primary>BGP</primary></indexterm> +<indexterm><primary>RIP</primary></indexterm> +<indexterm><primary>OSPF</primary></indexterm> + </sect2> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Al</firstname> + <surname>Hoang</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <!-- 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/24 link#1 UC 0 0 xl0 +192.168.1/24 link#2 UC 0 0 xl1</screen> + + <para>With the current routing table <hostid>RouterA</hostid> + will not be able to reach our Internal Net 2. It does not + have a route for <hostid + role="ipaddr">192.168.2.0/24</hostid>. One way to alleviate + this is to manually add the route. The following command + would add the Internal Net 2 network to + <hostid>RouterA</hostid>'s routing table using <hostid + role="ipaddr">192.168.1.2</hostid> as the next hop:</para> + + <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen> + + <para>Now <hostid>RouterA</hostid> can reach any hosts on the + <hostid role="ipaddr">192.168.2.0/24</hostid> + network.</para> + </sect3> + + <sect3> + <title>Persistent Configuration</title> + + <para>The above example is perfect for configuring a static + route on a running system. However, one problem is that the + routing information will not persist if you reboot your &os; + machine. The way to handle the addition of a static route + is to put it in your <filename>/etc/rc.conf</filename> + file:</para> + + <programlisting># Add Internal Net 2 as a static route +static_routes="internalnet2" +route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting> + + <para>The <literal>static_routes</literal> configuration + variable is a list of strings separated by a space. Each + string references to a route name. In our above example we + only have one string in <literal>static_routes</literal>. + This string is <replaceable>internalnet2</replaceable>. We + then add a configuration variable called + <literal>route_<replaceable>internalnet2</replaceable></literal> + where we put all of the configuration parameters we would + give to the &man.route.8; command. For our example above we + would have used the command:</para> + + <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen> + + <para>so we need <literal>"-net 192.168.2.0/24 192.168.1.2"</literal>.</para> + + <para>As said above, we can have more than one string in + <literal>static_routes</literal>. This allows us to + create multiple static routes. The following lines shows + an example of adding static routes for the <hostid + role="ipaddr">192.168.0.0/24</hostid> and <hostid + role="ipaddr">192.168.1.0/24</hostid> networks on an imaginary + router:</para> + + <programlisting>static_routes="net1 net2" +route_net1="-net 192.168.0.0/24 192.168.0.1" +route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Routing Propagation</title> + <indexterm><primary>routing propagation</primary></indexterm> + <para>We have already talked about how we define our routes to the + outside world, but not about how the outside world finds us.</para> + + <para>We already know that routing tables can be set up so that all + traffic for a particular address space (in our examples, a class-C + subnet) can be sent to a particular host on that network, which will + forward the packets inbound.</para> + + <para>When you get an address space assigned to your site, your service + provider will set up their routing tables so that all traffic for your + subnet will be sent down your PPP link to your site. But how do sites + across the country know to send to your ISP?</para> + + <para>There is a system (much like the distributed DNS information) that + keeps track of all assigned address-spaces, and defines their point of + connection to the Internet Backbone. The <quote>Backbone</quote> are + the main trunk lines that carry Internet traffic across the country, + and around the world. Each backbone machine has a copy of a master + set of tables, which direct traffic for a particular network to a + specific backbone carrier, and from there down the chain of service + providers until it reaches your network.</para> + + <para>It is the task of your service provider to advertise to the + backbone sites that they are the point of connection (and thus the + path inward) for your site. This is known as route + propagation.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + <indexterm> + <primary><command>traceroute</command></primary> + </indexterm> + <para>Sometimes, there is a problem with routing propagation, and some + sites are unable to connect to you. Perhaps the most useful command + for trying to figure out where routing is breaking down is the + &man.traceroute.8; command. It is equally useful if you cannot seem + to make a connection to a remote machine (i.e. &man.ping.8; + fails).</para> + + <para>The &man.traceroute.8; command is run with the name of the remote + host you are trying to connect to. It will show the gateway hosts + along the path of the attempt, eventually either reaching the target + host, or terminating because of a lack of connection.</para> + + <para>For more information, see the manual page for + &man.traceroute.8;.</para> + </sect2> + + <sect2> + <title>Multicast Routing</title> + <indexterm> + <primary>multicast routing</primary> + </indexterm> + <indexterm> + <primary>kernel options</primary> + <secondary>MROUTING</secondary> + </indexterm> + <para>FreeBSD supports both multicast applications and multicast + routing natively. Multicast applications do not require any + special configuration of FreeBSD; applications will generally + run out of the box. Multicast routing + requires that support be compiled into the kernel:</para> + + <programlisting>options MROUTING</programlisting> + + <para>In addition, the multicast routing daemon, &man.mrouted.8; + must be configured to set up tunnels and <acronym>DVMRP</acronym> via + <filename>/etc/mrouted.conf</filename>. More details on + multicast configuration may be found in the manual page for + &man.mrouted.8;.</para> + </sect2> + </sect1> + + <sect1 id="network-wireless"> + <sect1info> + <authorgroup> + <author> + <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>Since the 6.0 version, &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 driver proper (&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 you load this support as + 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 can be found at the beginning + of the &man.wlan.4; manual page. If a native &os; driver + for your wireless device does not exist, it may be + possible to directly use the &windows; driver with the + help of the <link + linkend="config-network-ndis">NDIS</link> driver + wrapper.</para> + </note> + + <para>With a device driver configured you need to also bring + in the 802.11 networking support required by the driver. + For the &man.ath.4; driver this is at least the &man.wlan.4; + module; this module is automatically loaded with the + wireless device driver. 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 is to run totally open (i.e., with no encryption) + then you do not even need the &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 just 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 ath # Atheros IEEE 802.11 wireless network driver +device ath_hal # Atheros Hardware Access Layer +device ath_rate_sample # John Bicket's SampleRate control algorithm. +device wlan # 802.11 support (Required) +device wlan_wep # WEP crypto support for 802.11 devices +device wlan_ccmp # AES-CCMP crypto support for 802.11 devices +device wlan_tkip # TKIP and Michael crypto support for 802.11 devices</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 0xff9f0000-0xff9fffff irq 17 at device 2.0 on pci2 +ath0: Ethernet address: 00:11:95:d5:43:62 +ath0: mac 7.9 phy 4.5 radio 5.6</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>ath0</replaceable> up scan</userinput> +SSID BSSID CHAN RATE S:N INT CAPS +dlinkap 00:13:46:49:41:76 6 54M 29:0 100 EPS WPA WME +freebsdap 00:11:95:c3:0d:ac 1 54M 22:0 100 EPS WPA</screen> + + <note> + <para>You must mark the interface <option>up</option> + before you can scan. Subsequent scan requests do not + require you to mark the interface up again.</para> + </note> + + <para>The output of a scan request lists each BSS/IBSS + network found. Beside the name of the network, + <literal>SSID</literal>, we find the + <literal>BSSID</literal> which is the MAC address of the + access point. The <literal>CAPS</literal> field + identifies the type of each network and the capabilities + of the stations operating there:</para> + + <variablelist> + <varlistentry> + <term><literal>E</literal></term> + + <listitem> + <para>Extended Service Set (ESS). Indicates that the + station is part of an infrastructure network (in + contrast to an IBSS/ad-hoc network).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>I</literal></term> + + <listitem> + <para>IBSS/ad-hoc network. Indicates that the station + is part of an ad-hoc network (in contrast to an ESS + network).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>P</literal></term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>S</literal></term> + + <listitem> + <para>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).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>s</literal></term> + + <listitem> + <para>Short slot time. Indicates that the 802.11g + network is using a short slot time because there are + no legacy (802.11b) stations present.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>One can also display the current list of known + networks with:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</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>ifconfig_ath0="DHCP"</programlisting> + + <para>If there are multiple access points and you want to + select a specific one, you can select it by its + SSID:</para> + + <programlisting>ifconfig_ath0="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>ifconfig_ath0="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>ifconfig_ath0="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>ifconfig_ath0="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, + simply 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>ifconfig_ath0="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>ath0</replaceable></userinput> +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps) + status: associated + ssid dlinkap channel 6 bssid 00:13:46:49:41:76 + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</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</literal> line informs you that the + communication is not encrypted + (<literal>OPEN</literal>).</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>ifconfig_ath0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting> + </sect5> + + <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) which 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 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>ifconfig_ath0="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 ath0 to 255.255.255.255 port 67 interval 5 +DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 6 +DHCPOFFER from 192.168.0.1 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100</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>ath0</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=TKIP GTK=TKIP]</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>ath0</replaceable></userinput> +DHCPREQUEST on ath0 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>ath0</replaceable></userinput> +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/48Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100</screen> + + <note> + <para>If the <filename>/etc/rc.conf</filename> is set up + with the line <literal>ifconfig_ath0="DHCP"</literal> + then it is no need to run the + <command>dhclient</command> command manually, + <command>dhclient</command> will be launched after + <command>wpa_supplicant</command> plumbs the + keys.</para> + </note> + + <para>In the case where the use of DHCP is not possible, + you can set a static IP address after + <command>wpa_supplicant</command> has authenticated the + station:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput> +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100</screen> + + <para>When DHCP is not used, you also have to manually set + up 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 make difference with the less secure + WPA-Personal with its pre-shared key. The + authentication in WPA-Enterprise is based on EAP + (Extensible Authentication Protocol).</para> + + <para>EAP does not come with an encryption method, it was + decided to embed EAP inside an encrypted tunnel. Many + types of EAP authentication methods have been designed, + the most common methods are EAP-TLS, EAP-TTLS and + EAP-PEAP.</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 certificat.</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 line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_ath0="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 ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100</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 certificat.</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 line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_ath0="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 ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen> + </sect5> + + <sect5 id="network-wireless-wpa-eap-peap"> + <title>WPA with EAP-PEAP</title> + + <para>PEAP (Protected EAP) has been designed as an + alternative to EAP-TTLS. There are two types of PEAP + methods, the most common one is PEAPv0/EAP-MSCHAPv2. In + the rest of this document, we will use the PEAP term to + refer to that EAP method. PEAP 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 term of + security the difference between EAP-TTLS and PEAP is + that PEAP authentication broadcasts the username in + clear, only the password is 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 certificat.</para> + </callout> + + <callout arearefs="co-peap-pha1"> + <para>This field contains the parameters for the + first phase of the authentication (the TLS + tunnel). According to the authentication server + used, you will have to specify a specific label + for the authentication. Most of 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>ifconfig_ath0="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 ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100</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 to be + cracked.</para> + + <para>WEP can be set up with + <command>ifconfig</command>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid my_net \ + wepmode on weptxkey 3 wepkey 3:0x3456789012</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.</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> + + <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 &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>ath0</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 adresses + and a SSID.</para> + + <para>On the box <hostid>A</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mediaopt adhoc</userinput> +&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + 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 <adhoc> (autoselect <adhoc>) + status: associated + ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</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>ath0</replaceable> up scan</userinput> + SSID BSSID CHAN RATE S:N INT CAPS + freebsdap 02:11:95:c3:0d:ac 2 54M 19:0 100 IS</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>ath0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mediaopt adhoc</userinput> +&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable></userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>) + status: associated + ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen> + + <para>Both <hostid>A</hostid> and <hostid>B</hostid> are now + ready to exchange informations.</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 these informations. 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> + + <note> + <para>The Bluetooth stack has to be started manually on &os; 6.0, and + on &os; 5.X before 5.5. It is done automatically from &man.devd.8; + on &os; 5.5, 6.1 and newer.</para> + + <para>Copy + <filename>/usr/share/examples/netgraph/bluetooth/rc.bluetooth</filename> + into some convenient place, like <filename>/etc/rc.bluetooth</filename>. + This script is used to start and stop the Bluetooth stack. It is a good + idea to stop the stack before unplugging the device, but it is not + (usually) fatal. When starting the stack, you will receive output similar + to the following:</para> + + <screen>&prompt.root; <userinput>/etc/rc.bluetooth start ubt0</userinput> +BD_ADDR: 00:02:72:00:d4:1a +Features: 0xff 0xff 0xf 00 00 00 00 00 +<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> + </note> + + </sect2> + + <indexterm><primary>HCI</primary></indexterm> + <sect2> + <title>Host Controller Interface (HCI)</title> + + <para>Host Controller Interface (HCI) provides a command interface to the + baseband controller and link manager, and access to hardware status and + control registers. This interface provides a uniform method of accessing + the Bluetooth baseband capabilities. HCI layer on the Host exchanges + data and commands with the HCI firmware on the Bluetooth hardware. + The Host Controller Transport Layer (i.e. physical bus) driver provides + both HCI layers with the ability to exchange information with each + other.</para> + + <para>A single Netgraph node of type <emphasis>hci</emphasis> is + created for a single Bluetooth device. The HCI node is normally + connected to the Bluetooth device driver node (downstream) and + the L2CAP node (upstream). All HCI operations must be performed + on the HCI node and not on the device driver node. Default name + for the HCI node is <quote>devicehci</quote>. + For more details refer to the &man.ng.hci.4; manual page.</para> + + <para>One of the most common tasks is discovery of Bluetooth devices in + RF proximity. This operation is called <emphasis>inquiry</emphasis>. + Inquiry and other HCI related operations are done with the + &man.hccontrol.8; utility. The example below shows how to find out + which Bluetooth devices are in range. You should receive the list of + devices in a few seconds. Note that a remote device will only answer + the inquiry if it put into <emphasis>discoverable</emphasis> + mode.</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput> +Inquiry result, num_responses=1 +Inquiry result #0 + BD_ADDR: 00:80:37:29:19:a4 + Page Scan Rep. Mode: 0x1 + Page Scan Period Mode: 00 + Page Scan Mode: 00 + Class: 52:02:04 + Clock offset: 0x78ef +Inquiry complete. Status: No error [00]</screen> + + <para><literal>BD_ADDR</literal> is unique address of a Bluetooth + device, similar to MAC addresses of a network card. This address + is needed for further communication with a device. It is possible + to assign human readable name to a BD_ADDR. + The <filename>/etc/bluetooth/hosts</filename> file contains information + regarding the known Bluetooth hosts. The following example shows how + to obtain human readable name that was assigned to the remote + device:</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput> +BD_ADDR: 00:80:37:29:19:a4 +Name: Pav's T39</screen> + + <para>If you perform an inquiry on a remote Bluetooth device, it will + find your computer as <quote>your.host.name (ubt0)</quote>. The name + assigned to the local device can be changed at any time.</para> + + <para>The Bluetooth system provides a point-to-point connection (only two + Bluetooth units involved), or a point-to-multipoint connection. In the + point-to-multipoint connection the connection is shared among several + Bluetooth devices. The following example shows how to obtain the list + of active baseband connections for the local device:</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput> +Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State +00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN</screen> + + <para>A <emphasis>connection handle</emphasis> is useful when termination + of the baseband connection is required. Note, that it is normally not + required to do it by hand. The stack will automatically terminate + inactive baseband connections.</para> + + <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput> +Connection handle: 41 +Reason: Connection terminated by local host [0x16]</screen> + + <para>Refer to <command>hccontrol help</command> for a complete listing + of available HCI commands. Most of the HCI commands do not require + superuser privileges.</para> + + </sect2> + + <indexterm><primary>L2CAP</primary></indexterm> + <sect2> + <title>Logical Link Control and Adaptation Protocol (L2CAP)</title> + + <para>Logical Link Control and Adaptation Protocol (L2CAP) provides + connection-oriented and connectionless data services to upper layer + protocols with protocol multiplexing capability and segmentation and + reassembly operation. L2CAP permits higher level protocols and + applications to transmit and receive L2CAP data packets up to 64 + kilobytes in length.</para> + + <para>L2CAP is based around the concept of <emphasis>channels</emphasis>. + Channel is a logical connection on top of baseband connection. Each + channel is bound to a single protocol in a many-to-one fashion. Multiple + channels can be bound to the same protocol, but a channel cannot be + bound to multiple protocols. Each L2CAP packet received on a channel is + directed to the appropriate higher level protocol. Multiple channels + can share the same baseband connection.</para> + + <para>A single Netgraph node of type <emphasis>l2cap</emphasis> is + created for a single Bluetooth device. The L2CAP node is normally + connected to the Bluetooth HCI node (downstream) and Bluetooth sockets + nodes (upstream). Default name for the L2CAP node is + <quote>devicel2cap</quote>. For more details refer to the + &man.ng.l2cap.4; manual page.</para> + + <para>A useful command is &man.l2ping.8;, which can be used to ping + other devices. Some Bluetooth implementations might not return all of + the data sent to them, so <literal>0 bytes</literal> in the following + example is normal.</para> + + <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput> +0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen> + + <para>The &man.l2control.8; utility is used to perform various operations + on L2CAP nodes. This example shows how to obtain the list of logical + connections (channels) and the list of baseband connections for the + local device:</para> + + <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput> +L2CAP channels: +Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State +00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN +&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput> +L2CAP connections: +Remote BD_ADDR Handle Flags Pending State +00:07:e0:00:0b:ca 41 O 0 OPEN</screen> + + <para>Another diagnostic tool is &man.btsockstat.1;. It does a job + similar to as &man.netstat.1; does, but for Bluetooth network-related + data structures. The example below shows the same logical connection as + &man.l2control.8; above.</para> + + <screen>&prompt.user; <userinput>btsockstat</userinput> +Active L2CAP sockets +PCB Recv-Q Send-Q Local address/PSM Foreign address CID State +c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN +Active RFCOMM sessions +L2PCB PCB Flag MTU Out-Q DLCs State +c2afe900 c2b53380 1 127 0 Yes OPEN +Active RFCOMM sockets +PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State +c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</screen> + + </sect2> + + <indexterm><primary>RFCOMM</primary></indexterm> + <sect2> + <title>RFCOMM Protocol</title> + + <para>The RFCOMM protocol provides emulation of serial ports over the + L2CAP protocol. The protocol is based on the ETSI standard TS 07.10. + RFCOMM is a simple transport protocol, with additional provisions for + emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The + RFCOMM protocol supports up to 60 simultaneous connections (RFCOMM + channels) between two Bluetooth devices.</para> + + <para>For the purposes of RFCOMM, a complete communication path involves + two applications running on different devices (the communication + endpoints) with a communication segment between them. RFCOMM is intended + to cover applications that make use of the serial ports of the devices + in which they reside. The communication segment is a Bluetooth link from + one device to another (direct connect).</para> + + <para>RFCOMM is only concerned with the connection between the devices in + the direct connect case, or between the device and a modem in the + network case. RFCOMM can support other configurations, such as modules + that communicate via Bluetooth wireless technology on one side and + provide a wired interface on the other side.</para> + + <para>In &os; the RFCOMM protocol is implemented at the Bluetooth sockets + layer.</para> + </sect2> + + <indexterm><primary>pairing</primary></indexterm> + <sect2> + <title>Pairing of Devices</title> + + <para>By default, Bluetooth communication is not authenticated, and any + device can talk to any other device. A Bluetooth device (for example, + cellular phone) may choose to require authentication to provide a + particular service (for example, Dial-Up service). Bluetooth + authentication is normally done with <emphasis>PIN codes</emphasis>. + A PIN code is an ASCII string up to 16 characters in length. User is + required to enter the same PIN code on both devices. Once user has + entered the PIN code, both devices will generate a + <emphasis>link key</emphasis>. After that the link key can be stored + either in the devices themselves or in a persistent storage. Next time + both devices will use previously generated link key. The described + above procedure is called <emphasis>pairing</emphasis>. Note that if + the link key is lost by any device then pairing must be repeated.</para> + + <para>The &man.hcsecd.8; daemon is responsible for handling of all + Bluetooth authentication requests. The default configuration file is + <filename>/etc/bluetooth/hcsecd.conf</filename>. An example section for + a cellular phone with the PIN code arbitrarily set to + <quote>1234</quote> is shown below:</para> + + <programlisting>device { + bdaddr 00:80:37:29:19:a4; + name "Pav's T39"; + key nokey; + pin "1234"; + }</programlisting> + + <para>There is no limitation on PIN codes (except length). Some devices + (for example Bluetooth headsets) may have a fixed PIN code built in. + The <option>-d</option> switch forces the &man.hcsecd.8; daemon to stay + in the foreground, so it is easy to see what is happening. Set the + remote device to receive pairing and initiate the Bluetooth connection + to the remote device. The remote device should say that pairing was + accepted, and request the PIN code. Enter the same PIN code as you + have in <filename>hcsecd.conf</filename>. Now your PC and the remote + device are paired. Alternatively, you can initiate pairing on the remote + device.</para> + + <para>On &os; 5.5, 6.1 and newer, the following line can be added to the + <filename>/etc/rc.conf</filename> file to have + <application>hcsecd</application> started automatically on system + start:</para> + + <programlisting>hcsecd_enable="YES"</programlisting> + + <para>The following is a sample of the + <application>hcsecd</application> daemon output:</para> + +<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist +hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists +hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting> + + </sect2> + + <indexterm><primary>SDP</primary></indexterm> + <sect2> + <title>Service Discovery Protocol (SDP)</title> + <para>The Service Discovery Protocol (SDP) provides the means for client + applications to discover the existence of services provided by server + applications as well as the attributes of those services. The attributes + of a service include the type or class of service offered and the + mechanism or protocol information needed to utilize the service.</para> + + <para>SDP involves communication between a SDP server and a SDP client. + The server maintains a list of service records that describe the + characteristics of services associated with the server. Each service + record contains information about a single service. A client may + retrieve information from a service record maintained by the SDP server + by issuing a SDP request. If the client, or an application associated + with the client, decides to use a service, it must open a separate + connection to the service provider in order to utilize the service. + SDP provides a mechanism for discovering services and their attributes, + but it does not provide a mechanism for utilizing those services.</para> + + <para>Normally, a SDP client searches for services based on some desired + characteristics of the services. However, there are times when it is + desirable to discover which types of services are described by an SDP + server's service records without any a priori information about the + services. This process of looking for any offered services is called + <emphasis>browsing</emphasis>.</para> + + <para>The Bluetooth SDP server &man.sdpd.8; and command line client + &man.sdpcontrol.8; are included in the standard &os; installation. + The following example shows how to perform a SDP browse query.</para> + + <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput> +Record Handle: 00000000 +Service Class ID List: + Service Discovery Server (0x1000) +Protocol Descriptor List: + L2CAP (0x0100) + Protocol specific parameter #1: u/int/uuid16 1 + Protocol specific parameter #2: u/int/uuid16 1 + +Record Handle: 0x00000001 +Service Class ID List: + Browse Group Descriptor (0x1001) + +Record Handle: 0x00000002 +Service Class ID List: + LAN Access Using PPP (0x1102) +Protocol Descriptor List: + L2CAP (0x0100) + RFCOMM (0x0003) + Protocol specific parameter #1: u/int8/bool 1 +Bluetooth Profile Descriptor List: + LAN Access Using PPP (0x1102) ver. 1.0 +</screen> + + <para>... and so on. Note that each service has a list of attributes + (RFCOMM channel for example). Depending on the service you might need to + make a note of some of the attributes. Some Bluetooth implementations do + not support service browsing and may return an empty list. In this case + it is possible to search for the specific service. The example below + shows how to search for the OBEX Object Push (OPUSH) service:</para> + + <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen> + + <para>Offering services on &os; to Bluetooth clients is done with the + &man.sdpd.8; server. On &os; 5.5, 6.1 and newer, the following line can + be added to the <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>sdpd_enable="YES"</programlisting> + + <para>Then the <application>sdpd</application> daemon can be started with:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sdpd start</userinput></screen> + + <para>On &os; 6.0, and on &os; 5.X before 5.5, + <application>sdpd</application> is not integrated into the system + startup scripts. It has to be started manually with:</para> + + <screen>&prompt.root; <userinput>sdpd</userinput></screen> + + <para>The local server application that wants to provide Bluetooth + service to the remote clients will register service with the local + SDP daemon. The example of such application is &man.rfcomm.pppd.8;. + Once started it will register Bluetooth LAN service with the local + SDP daemon.</para> + + <para>The list of services registered with the local SDP server can be + obtained by issuing SDP browse query via local control channel:</para> + + <screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen> + + </sect2> + + <sect2> + <title>Dial-Up Networking (DUN) and Network Access with PPP (LAN) + Profiles</title> + + <para>The Dial-Up Networking (DUN) profile is mostly used with modems + and cellular phones. The scenarios covered by this profile are the + following:</para> + + <itemizedlist> + <listitem><para>use of a cellular phone or modem by a computer as + a wireless modem for connecting to a dial-up Internet access server, + or using other dial-up services;</para></listitem> + + <listitem><para>use of a cellular phone or modem by a computer to + receive data calls.</para></listitem> + </itemizedlist> + + <para>Network Access with PPP (LAN) profile can be used in the following + situations:</para> + + <itemizedlist> + <listitem><para>LAN access for a single Bluetooth device; + </para></listitem> + + <listitem><para>LAN access for multiple Bluetooth devices; + </para></listitem> + + <listitem><para>PC to PC (using PPP networking over serial cable + emulation).</para></listitem> + </itemizedlist> + + <para>In &os; both profiles are implemented with &man.ppp.8; and + &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth + connection into something PPP can operate with. Before any profile + can be used, a new PPP label in the <filename>/etc/ppp/ppp.conf</filename> + must be created. Consult &man.rfcomm.pppd.8; manual page for examples. + </para> + + <para>In the following example &man.rfcomm.pppd.8; will be used to open + RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on + DUN RFCOMM channel. The actual RFCOMM channel number will be obtained + from the remote device via SDP. It is possible to specify RFCOMM channel + by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP + query. Use &man.sdpcontrol.8; to find out RFCOMM + channel on the remote device.</para> + + <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen> + + <para>In order to provide Network Access with PPP (LAN) service the + &man.sdpd.8; server must be running. A new entry for LAN clients must + be created in the <filename>/etc/ppp/ppp.conf</filename> file. Consult + &man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP + server on valid RFCOMM channel number. The RFCOMM PPP server will + automatically register Bluetooth LAN service with the local SDP daemon. + The example below shows how to start RFCOMM PPP server.</para> + + <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen> + + </sect2> + + <indexterm><primary>OBEX</primary></indexterm> + <sect2> + <title>OBEX Object Push (OPUSH) Profile</title> + <para>OBEX is a widely used protocol for simple file transfers between + mobile devices. Its main use is in infrared communication, where it is + used for generic file transfers between notebooks or PDAs, + and for sending business cards or calendar entries between cellular + phones and other devices with PIM applications.</para> + + <para>The OBEX server and client are implemented as a third-party package + <application>obexapp</application>, which is available as + <filename role="package">comms/obexapp</filename> port.</para> + + <para>OBEX client is used to push and/or pull objects from the OBEX server. + An object can, for example, be a business card or an appointment. + The OBEX client can obtain RFCOMM channel number from the remote device + via SDP. This can be done by specifying service name instead of RFCOMM + channel number. Supported service names are: IrMC, FTRN and OPUSH. + It is possible to specify RFCOMM channel as a number. Below is an + example of an OBEX session, where device information object is pulled + from the cellular phone, and a new object (business card) is pushed + into the phone's directory.</para> + + <screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput> +obex> 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>Steve</firstname> + <surname>Peterson</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Bridging</title> + + <sect2> + <title>Introduction</title> + <indexterm><primary>IP subnet</primary></indexterm> + <indexterm><primary>bridge</primary></indexterm> + <para>It is sometimes useful to divide one physical network + (such as an Ethernet segment) into two separate network + segments without having to create IP subnets and use a router + to connect the segments together. A device that connects two + networks together in this fashion is called a + <quote>bridge</quote>. A FreeBSD system with two network + interface cards can act as a bridge.</para> + + <para>The bridge works by learning the MAC layer addresses + (Ethernet addresses) of the devices on each of its network interfaces. + It forwards traffic between two networks only when its source and + destination are on different networks.</para> + + <para>In many respects, a bridge is like an Ethernet switch with very + few ports.</para> + </sect2> + + <sect2> + <title>Situations Where Bridging Is Appropriate</title> + + <para>There are two common situations in which a bridge is used + today.</para> + + <sect3> + <title>High Traffic on a Segment</title> + + <para>Situation one is where your physical network segment is + overloaded with traffic, but you do not want for whatever reason to + subnet the network and interconnect the subnets with a + router.</para> + + <para>Let us consider an example of a newspaper where the Editorial and + Production departments are on the same subnetwork. The Editorial + users all use server <hostid>A</hostid> for file service, and the Production users + are on server <hostid>B</hostid>. An Ethernet network is used to connect all users together, + and high loads on the network are slowing things down.</para> + + <para>If the Editorial users could be segregated on one + network segment and the Production users on another, the two + network segments could be connected with a bridge. Only the + network traffic destined for interfaces on the + <quote>other</quote> side of the bridge would be sent to the + other network, reducing congestion on each network + segment.</para> + </sect3> + + <sect3> + <title>Filtering/Traffic Shaping Firewall</title> + <indexterm><primary>firewall</primary></indexterm> + <indexterm><primary>NAT</primary></indexterm> + + <para>The second common situation is where firewall functionality is + needed without network address translation (NAT).</para> + + <para>An example is a small company that is connected via DSL + or ISDN to their ISP. They have a 13 globally-accessible IP + addresses from their ISP and have 10 PCs on their network. + In this situation, using a router-based firewall is + difficult because of subnetting issues.</para> + + <indexterm><primary>router</primary></indexterm> + <indexterm><primary>DSL</primary></indexterm> + <indexterm><primary>ISDN</primary></indexterm> + <para>A bridge-based firewall can be configured and dropped into the + path just downstream of their DSL/ISDN router without any IP + numbering issues.</para> + </sect3> + </sect2> + + <sect2> + <title>Configuring a Bridge</title> + + <sect3> + <title>Network Interface Card Selection</title> + + <para>A bridge requires at least two network cards to function. + Unfortunately, not all network interface cards + support bridging. Read &man.bridge.4; for details on the cards that + are supported.</para> + + <para>Install and test the two network cards before continuing.</para> + </sect3> + + <sect3> + <title>Kernel Configuration Changes</title> + <indexterm> + <primary>kernel options</primary> + <secondary>BRIDGE</secondary> + </indexterm> + + <para>To enable kernel support for bridging, add the:</para> + + <programlisting>options BRIDGE</programlisting> + + <para>statement to your kernel configuration file, and rebuild your + kernel.</para> + </sect3> + + <sect3> + <title>Firewall Support</title> + <indexterm><primary>firewall</primary></indexterm> + <para>If you are planning to use the bridge as a firewall, you + will need to add the <literal>IPFIREWALL</literal> option as + well. Read <xref linkend="firewalls"> for general + information on configuring the bridge as a firewall.</para> + + <para>If you need to allow non-IP packets (such as ARP) to flow + through the bridge, there are three options available. + The first is to add the following option to the kernel and + rebuild:<para> + + <programlisting>option IPFIREWALL_DEFAULT_TO_ACCEPT</programlisting> + + <para>The second is to set the firewall type to <quote><literal>open</literal></quote> in the + <filename>rc.conf</filename> file:</para> + + <programlisting>firewall_type="open"</programlisting> + + <para>Note that these options will make the firewall seem completely + transparent; any packet or connection will be permitted by default. + This may require significant changes to the firewall ruleset.</para> + + <para>The third option is to apply the following &man.ipfw.8; + rule:</para> + + <screen>&prompt.root; <userinput>ipfw add allow mac-type arp layer2</userinput></screen> + + <para>Or add it to the current firewall ruleset. This rule effectively + allows &man.arp.8; packets through, so it must be be applied near the + beginning of the ruleset for early evaluation.</para> + </sect3> + + <sect3> + <title>Traffic Shaping Support</title> + + <para>If you want to use the bridge as a traffic shaper, you will need + to add the <literal>DUMMYNET</literal> option to your kernel + configuration. Read &man.dummynet.4; for further + information.</para> + </sect3> + </sect2> + + <sect2> + <title>Enabling the Bridge</title> + + <para>Add the line:</para> + + <programlisting>net.link.ether.bridge.enable=1</programlisting> + + <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at + runtime, and the line:</para> + + <programlisting>net.link.ether.bridge.config=<replaceable>if1</replaceable>,<replaceable>if2</replaceable></programlisting> + + <para>to enable bridging on the specified interfaces (replace + <replaceable>if1</replaceable> and + <replaceable>if2</replaceable> with the names of your two + network interfaces). If you want the bridged packets to be + filtered by &man.ipfw.8;, you should add:</para> + + <programlisting>net.link.ether.bridge.ipfw=1</programlisting> + + <para>as well.</para> + + <para>For versions prior to &os; 5.2-RELEASE, use instead the following + lines:</para> + + <programlisting>net.link.ether.bridge=1 +net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable> +net.link.ether.bridge_ipfw=1</programlisting> + + </sect2> + + <sect2> + <title>Other Information</title> + + <para>If you want to be able to &man.ssh.1; into the bridge from the network, + it is correct to assign one of the network cards an IP address. The + consensus is that assigning both cards an address is a bad + idea.</para> + + <para>If you have multiple bridges on your network, there cannot be more + than one path between any two workstations. Technically, this means + that there is no support for spanning tree link management.</para> + + <para>A bridge can add latency to your &man.ping.8; times, especially for + traffic from one segment to another.</para> + + </sect2> + </sect1> + + <sect1 id="network-diskless"> + <sect1info> + <authorgroup> + <author> + <firstname>Jean-Franç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 + 3.0</application> is not part of the base + system. You will first need to install the + <filename role="package">net/isc-dhcp3-server</filename> port or the + corresponding package.</para> + + <para>Once <application>ISC DHCP</application> is installed, it + needs a configuration file to run (normally named + <filename>/usr/local/etc/dhcpd.conf</filename>). Here follows + a commented example, where host <hostid>margaux</hostid> + uses <application>Etherboot</application> and host + <hostid>corbieres</hostid> uses <acronym>PXE</acronym>:</para> + + <programlisting> +default-lease-time 600; +max-lease-time 7200; +authoritative; + +option domain-name "example.com"; +option domain-name-servers 192.168.4.1; +option routers 192.168.4.1; + +subnet 192.168.4.0 netmask 255.255.255.0 { + use-host-decl-names on; <co id="co-dhcp-host-name"> + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.4.255; + + host margaux { + hardware ethernet 01:23:45:67:89:ab; + fixed-address margaux.example.com; + next-server 192.168.4.4; <co id="co-dhcp-next-server"> + filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename"> + option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path"> + } + host corbieres { + hardware ethernet 00:02:b3:27:62:df; + fixed-address corbieres.example.com; + next-server 192.168.4.4; + filename "pxeboot"; + option root-path "192.168.4.4:/data/misc/diskless"; + } +} + </programlisting> + + <calloutlist> + <callout arearefs="co-dhcp-host-name"><para>This option tells + <application>dhcpd</application> to send the value in the + <literal>host</literal> declarations as the hostname for the + diskless host. An alternate way would be to add an + <literal>option host-name + <replaceable>margaux</replaceable></literal> inside the + <literal>host</literal> declarations.</para> + </callout> + + <callout arearefs="co-dhcp-next-server"><para>The + <literal>next-server</literal> directive designates + the <acronym>TFTP</acronym> or <acronym>NFS</acronym> server to + use for loading loader or kernel file (the default is to use + the same host as the + <acronym>DHCP</acronym> server).</para> + </callout> + + <callout arearefs="co-dhcp-filename"><para>The + <literal>filename</literal> directive defines the file that + <application>Etherboot</application> or <acronym>PXE</acronym> + will load for the next execution step. It must be specified + according to the transfer method used. + <application>Etherboot</application> can be compiled to use + <acronym>NFS</acronym> or <acronym>TFTP</acronym>. The &os; + port configures <acronym>NFS</acronym> by default. + <acronym>PXE</acronym> uses <acronym>TFTP</acronym>, which is + why a relative filename is used here (this may depend on the + <acronym>TFTP</acronym> server configuration, but would be + fairly typical). Also, <acronym>PXE</acronym> loads + <filename>pxeboot</filename>, not the kernel. There are other + interesting possibilities, like loading + <filename>pxeboot</filename> from a &os; CD-ROM + <filename role="directory">/boot</filename> directory (as + &man.pxeboot.8; can load a <filename>GENERIC</filename> kernel, + this makes it possible to use <acronym>PXE</acronym> to boot + from a remote CD-ROM).</para> + </callout> + + <callout arearefs="co-dhcp-root-path"><para>The + <literal>root-path</literal> option defines the path to + the root file system, in usual <acronym>NFS</acronym> notation. + When using <acronym>PXE</acronym>, it is possible to leave off + the host's IP as long as you do not enable the kernel option + BOOTP. The <acronym>NFS</acronym> server will then be + the same as the <acronym>TFTP</acronym> one.</para> + </callout> + </calloutlist> + + </sect3> + <sect3> + <title>Configuration Using BOOTP</title> + <indexterm> + <primary>BOOTP</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>Here follows an equivalent <application>bootpd</application> + configuration (reduced to one client). This would be found in + <filename>/etc/bootptab</filename>.</para> + + <para>Please note that <application>Etherboot</application> + must be compiled with the non-default option + <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, + and that <acronym>PXE</acronym> <emphasis>needs</emphasis> <acronym>DHCP</acronym>. The only + obvious advantage of <application>bootpd</application> is + that it exists in the base system.</para> + + <programlisting> +.def100:\ + :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\ + :sm=255.255.255.0:\ + :ds=192.168.4.1:\ + :gw=192.168.4.1:\ + :hd="/tftpboot":\ + :bf="/kernel.diskless":\ + :rp="192.168.4.4:/data/misc/diskless": + +margaux:ha=0123456789ab:tc=.def100 + </programlisting> + </sect3> + + <sect3> + <title>Preparing a Boot Program with + <application>Etherboot</application></title> + + <indexterm> + <primary>Etherboot</primary> + </indexterm> + + <para><ulink url="http://etherboot.sourceforge.net">Etherboot's Web + site</ulink> contains + <ulink url="http://etherboot.sourceforge.net/doc/html/userman/t1.html"> + extensive documentation</ulink> mainly intended for Linux + systems, but nonetheless containing useful information. The + following will just outline how you would use + <application>Etherboot</application> on a FreeBSD + system.</para> + + <para>You must first install the <filename + role="package">net/etherboot</filename> package or port.</para> + + <para>You can change the <application>Etherboot</application> + configuration (i.e. to use <acronym>TFTP</acronym> instead of + <acronym>NFS</acronym>) by editing the <filename>Config</filename> + file in the <application>Etherboot</application> source + directory.</para> + + <para>For our setup, we shall use a boot floppy. For other methods + (PROM, or &ms-dos; program), please refer to the + <application>Etherboot</application> documentation.</para> + + <para>To make a boot floppy, insert a floppy in the drive on the + machine where you installed <application>Etherboot</application>, + then change your current directory to the <filename>src</filename> + directory in the <application>Etherboot</application> tree and + type:</para> + + <screen> +&prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput> + </screen> + + <para><replaceable>devicetype</replaceable> depends on the type of + the Ethernet card in the diskless workstation. Refer to the + <filename>NIC</filename> file in the same directory to determine the + right <replaceable>devicetype</replaceable>.</para> + + </sect3> + + <sect3> + <title>Booting with <acronym>PXE</acronym></title> + + <para>By default, the &man.pxeboot.8; loader loads the kernel via + <acronym>NFS</acronym>. It can be compiled to use + <acronym>TFTP</acronym> instead by specifying the + <literal>LOADER_TFTP_SUPPORT</literal> option in + <filename>/etc/make.conf</filename>. See the comments in + <filename>/usr/share/examples/etc/make.conf</filename> + for instructions.</para> + + <para>There are two other <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 +cd /usr/src/etc; make distribution</programlisting> + + <para>Once done, you may need to customize your + <filename>/etc/rc.conf</filename> and + <filename>/etc/fstab</filename> placed into + <envar>DESTDIR</envar> according to your needs.</para> + </sect4> + </sect3> + + <sect3> + <title>Configuring Swap</title> + + <para>If needed, a swap file located on the server can be + accessed via <acronym>NFS</acronym>.</para> + + <sect4> + <title><acronym>NFS</acronym> Swap</title> + + <para>The kernel does not support enabling <acronym>NFS</acronym> + swap at boot time. Swap must be enabled by the startup scripts, + by mounting a writable file system and creating and enabling a + swap file. To create a swap file of appropriate size, you can do + like this:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen> + + <para>To enable it you have to add the following line to your + <filename>rc.conf</filename>:</para> + + <programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting> + </sect4> + </sect3> + + <sect3> + <title>Miscellaneous Issues</title> + + + <sect4> + <title>Running with a Read-only <filename>/usr</filename></title> + + <indexterm> + <primary>diskless operation</primary> + <secondary>/usr read-only</secondary> + </indexterm> + + <para>If the diskless workstation is configured to run X, you + will have to adjust the <application>XDM</application> configuration file, which puts + the error log on <filename>/usr</filename> by default.</para> + </sect4> + <sect4> + <title>Using a Non-FreeBSD Server</title> + + <para>When the server for the root file system is not running FreeBSD, + you will have to create the root file system on a + FreeBSD machine, then copy it to its destination, using + <command>tar</command> or <command>cpio</command>.</para> + <para>In this situation, there are sometimes + problems with the special files in <filename>/dev</filename>, + due to differing major/minor integer sizes. A solution to this + problem is to export a directory from the non-FreeBSD server, + mount this directory onto a FreeBSD machine, and + use &man.devfs.5; to allocate device nodes transparently for + the user.</para> + + </sect4> + + </sect3> + + </sect2> + </sect1> + + <sect1 id="network-isdn"> + <title>ISDN</title> + + <indexterm> + <primary>ISDN</primary> + </indexterm> + + <para>A good resource for information on ISDN technology and hardware is + <ulink url="http://www.alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN + Page</ulink>.</para> + + <para>A quick simple road map to ISDN follows:</para> + + <itemizedlist> + <listitem> + <para>If you live in Europe you might want to investigate the ISDN card + section.</para> + </listitem> + + <listitem> + <para>If you are planning to use ISDN primarily to connect to the + Internet with an Internet Provider on a dial-up non-dedicated basis, + you might look into Terminal Adapters. This will give you the + most flexibility, with the fewest problems, if you change + providers.</para> + </listitem> + + <listitem> + <para>If you are connecting two LANs together, or connecting to the + Internet with a dedicated ISDN connection, you might consider + the stand alone router/bridge option.</para> + </listitem> + </itemizedlist> + + <para>Cost is a significant factor in determining what solution you will + choose. The following options are listed from least expensive to most + expensive.</para> + + <sect2 id="network-isdn-cards"> + <sect2info> + <authorgroup> + <author> + <firstname>Hellmuth</firstname> + <surname>Michaelis</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>ISDN Cards</title> + + <indexterm> + <primary>ISDN</primary> + <secondary>cards</secondary> + </indexterm> + + <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931 + (or Euro-ISDN) standard using passive cards. Some active cards + are supported where the firmware + also supports other signaling protocols; this also includes the + first supported Primary Rate (PRI) ISDN card.</para> + + <para>The <application>isdn4bsd</application> software allows you to connect + to other ISDN routers using either IP over raw HDLC or by using + synchronous PPP: either by using kernel PPP with <literal>isppp</literal>, a + modified &man.sppp.4; driver, or by using userland &man.ppp.8;. By using + userland &man.ppp.8;, channel bonding of two or more ISDN + B-channels is possible. A telephone answering machine + application is also available as well as many utilities such as + a software 300 Baud modem.</para> + + <para>Some growing number of PC ISDN cards are supported under + FreeBSD and the reports show that it is successfully used all + over Europe and in many other parts of the world.</para> + + <para>The passive ISDN cards supported are mostly the ones with + the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, + but also ISDN cards with chips from Cologne Chip (ISA bus only), + PCI cards with Winbond W6692 chips, some cards with the + Tiger300/320/ISAC chipset combinations and some vendor specific + chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the + AVM Fritz!Card PnP.</para> + + <para>Currently the active supported ISDN cards are the AVM B1 + (ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para> + + <para>For documentation on <application>isdn4bsd</application>, + have a look at <filename>/usr/share/examples/isdn/</filename> + directory on your FreeBSD system or at the <ulink + url="http://www.freebsd-support.de/i4b/">homepage of + isdn4bsd</ulink> which also has pointers to hints, erratas and + much more documentation such as the <ulink + url="http://people.FreeBSD.org/~hm/">isdn4bsd + handbook</ulink>.</para> + + <para>In case you are interested in adding support for a + different ISDN protocol, a currently unsupported ISDN PC card or + otherwise enhancing <application>isdn4bsd</application>, please + get in touch with &a.hm;.</para> + + <para>For questions regarding the installation, configuration + and troubleshooting <application>isdn4bsd</application>, a + &a.isdn.name; mailing list is available.</para> + </sect2> + + <sect2> + <title>ISDN Terminal Adapters</title> + + <para>Terminal adapters (TA), are to ISDN what modems are to regular + phone lines.</para> + <indexterm><primary>modem</primary></indexterm> + <para>Most TA's use the standard Hayes modem AT command set, and can be + used as a drop in replacement for a modem.</para> + + <para>A TA will operate basically the same as a modem except connection + and throughput speeds will be much faster than your old modem. You + will need to configure <link linkend="ppp">PPP</link> exactly the same + as for a modem setup. Make sure you set your serial speed as high as + possible.</para> + <indexterm><primary>PPP</primary></indexterm> + <para>The main advantage of using a TA to connect to an Internet + Provider is that you can do Dynamic PPP. As IP address space becomes + more and more scarce, most providers are not willing to provide you + with a static IP anymore. Most stand-alone routers are not able to + accommodate dynamic IP allocation.</para> + + <para>TA's completely rely on the PPP daemon that you are running for + their features and stability of connection. This allows you to + upgrade easily from using a modem to ISDN on a FreeBSD machine, if you + already have PPP set up. However, at the same time any problems you + experienced with the PPP program and are going to persist.</para> + + <para>If you want maximum stability, use the kernel <link + linkend="ppp">PPP</link> option, not the <link + linkend="userppp">userland PPP</link>.</para> + + <para>The following TA's are known to work with FreeBSD:</para> + + <itemizedlist> + <listitem> + <para>Motorola BitSurfer and Bitsurfer Pro</para> + </listitem> + + <listitem> + <para>Adtran</para> + </listitem> + </itemizedlist> + + <para>Most other TA's will probably work as well, TA vendors try to make + sure their product can accept most of the standard modem AT command + set.</para> + + <para>The real problem with external TA's is that, like modems, + you need a good serial card in your computer.</para> + + <para>You should read the <ulink + url="&url.articles.serial-uart;/index.html">FreeBSD Serial + Hardware</ulink> tutorial for a detailed understanding of + serial devices, and the differences between asynchronous and + synchronous serial ports.</para> + + <para>A TA running off a standard PC serial port (asynchronous) limits + you to 115.2 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-natdkernconfiguration"> + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> + <title>Configuration</title> + <para>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> + + <para>The following must be in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"> +firewall_enable="YES" <co id="co-natd-firewall-enable"> +firewall_type="OPEN" <co id="co-natd-firewall-type"> +natd_enable="YES" +natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface"> +natd_flags="" <co id="co-natd-natd-flags"></programlisting> + + <calloutlist> + <callout arearefs="co-natd-gateway-enable"> + <para>Sets up the machine to act as a gateway. Running + <command>sysctl net.inet.ip.forwarding=1</command> would + have the same effect.</para> + </callout> + + <callout arearefs="co-natd-firewall-enable"> + <para>Enables the firewall rules in + <filename>/etc/rc.firewall</filename> at boot.</para> + </callout> + + <callout arearefs="co-natd-firewall-type"> + <para>This specifies a predefined firewall ruleset that + allows anything in. See + <filename>/etc/rc.firewall</filename> for additional + types.</para> + </callout> + + <callout arearefs="co-natd-natd-interface"> + <para>Indicates which interface to forward packets through + (the interface connected to the Internet).</para> + </callout> + + <callout arearefs="co-natd-natd-flags"> + <para>Any additional configuration options passed to + &man.natd.8; on boot.</para> + </callout> + </calloutlist> + + <para>Having the previous options defined in + <filename>/etc/rc.conf</filename> would run + <command>natd -interface fxp0</command> at boot. This can also + be run manually.</para> + + <note> + <para>It is also possible to use a configuration file for + &man.natd.8; when there are too many options to pass. In this + case, the configuration file must be defined by adding the + following line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>natd_flags="-f /etc/natd.conf"</programlisting> + + <para>The <filename>/etc/natd.conf</filename> file will + contain a list of configuration options, one per line. For + example the next section case would use the following + file:</para> + + <programlisting>redirect_port tcp 192.168.0.2:6667 6667 +redirect_port tcp 192.168.0.3:80 80</programlisting> + + <para>For more information about the configuration file, + consult the &man.natd.8; manual page about the + <option>-f</option> option.</para> + </note> + + <para>Each machine and interface behind the LAN should be + assigned IP address numbers in the private network space as + defined by <ulink + url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink> + and have a default gateway of the <application>natd</application> machine's internal IP + address.</para> + + <para>For example, client <hostid>A</hostid> and + <hostid>B</hostid> behind the LAN have IP addresses of <hostid + role="ipaddr">192.168.0.2</hostid> and <hostid + role="ipaddr">192.168.0.3</hostid>, while the natd machine's + LAN interface has an IP address of <hostid + role="ipaddr">192.168.0.1</hostid>. Client <hostid>A</hostid> + and <hostid>B</hostid>'s default gateway must be set to that + of the <application>natd</application> machine, <hostid + role="ipaddr">192.168.0.1</hostid>. The <application>natd</application> machine's + external, or Internet interface does not require any special + modification for &man.natd.8; to work.</para> + </sect2> + + <sect2 id="network-natdport-redirection"> + <title>Port Redirection</title> + + <para>The drawback with &man.natd.8; is that the LAN clients are not accessible + from the Internet. Clients on the LAN can make outgoing connections to + the world but cannot receive incoming ones. This presents a problem + if trying to run Internet services on one of the LAN client machines. + A simple way around this is to redirect selected Internet ports on the + <application>natd</application> machine to a LAN client. + </para> + + <para>For example, an IRC server runs on client <hostid>A</hostid>, and a web server runs + on client <hostid>B</hostid>. For this to work properly, connections received on ports + 6667 (IRC) and 80 (web) must be redirected to the respective machines. + </para> + + <para>The <option>-redirect_port</option> must be passed to + &man.natd.8; with the proper options. The syntax is as follows:</para> + <programlisting> -redirect_port proto targetIP:targetPORT[-targetPORT] + [aliasIP:]aliasPORT[-aliasPORT] + [remoteIP[:remotePORT[-remotePORT]]]</programlisting> + + <para>In the above example, the argument should be:</para> + + <programlisting> -redirect_port tcp 192.168.0.2:6667 6667 + -redirect_port tcp 192.168.0.3:80 80</programlisting> + + <para> + This will redirect the proper <emphasis>tcp</emphasis> ports to the + LAN client machines. + </para> + + <para>The <option>-redirect_port</option> argument can be used to indicate port + ranges over individual ports. For example, <replaceable>tcp + 192.168.0.2:2000-3000 2000-3000</replaceable> would redirect + all connections received on ports 2000 to 3000 to ports 2000 + to 3000 on client <hostid>A</hostid>.</para> + + <para>These options can be used when directly running + &man.natd.8;, placed within the + <literal>natd_flags=""</literal> option in + <filename>/etc/rc.conf</filename>, + or passed via a configuration file.</para> + + <para>For further configuration options, consult &man.natd.8;</para> + </sect2> + + <sect2 id="network-natdaddress-redirection"> + <title>Address Redirection</title> + <indexterm><primary>address redirection</primary></indexterm> + <para>Address redirection is useful if several IP addresses are + available, yet they must be on one machine. With this, + &man.natd.8; can assign each LAN client its own external IP address. + &man.natd.8; then rewrites outgoing packets from the LAN clients + with the proper external IP address and redirects + all traffic incoming on that particular IP address back to + the specific LAN client. This is also known as static NAT. + For example, the IP addresses <hostid role="ipaddr">128.1.1.1</hostid>, + <hostid role="ipaddr">128.1.1.2</hostid>, and + <hostid role="ipaddr">128.1.1.3</hostid> belong to the <application>natd</application> gateway + machine. <hostid role="ipaddr">128.1.1.1</hostid> can be used + as the <application>natd</application> gateway machine's external IP address, while + <hostid role="ipaddr">128.1.1.2</hostid> and + <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to LAN + clients <hostid>A</hostid> and <hostid>B</hostid>.</para> + + <para>The <option>-redirect_address</option> syntax is as follows:</para> + + <programlisting>-redirect_address localIP publicIP</programlisting> + + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <tbody> + <row> + <entry>localIP</entry> + <entry>The internal IP address of the LAN client.</entry> + </row> + <row> + <entry>publicIP</entry> + <entry>The external IP address corresponding to the LAN client.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>In the example, this argument would read:</para> + + <programlisting>-redirect_address 192.168.0.2 128.1.1.2 +-redirect_address 192.168.0.3 128.1.1.3</programlisting> + + <para>Like <option>-redirect_port</option>, these arguments are also placed within + the <literal>natd_flags=""</literal> option of <filename>/etc/rc.conf</filename>, or passed via a configuration file. With address + redirection, there is no need for port redirection since all data + received on a particular IP address is redirected.</para> + + <para>The external IP addresses on the <application>natd</application> machine must be active and aliased + to the external interface. Look at &man.rc.conf.5; to do so.</para> + + </sect2> + </sect1> + + <sect1 id="network-plip"> + <title>Parallel Line IP (PLIP)</title> + + <indexterm><primary>PLIP</primary></indexterm> + <indexterm> + <primary>Parallel Line IP</primary> + <see>PLIP</see> + </indexterm> + + <para>PLIP lets us run TCP/IP between parallel ports. It is + useful on machines without network cards, or to install on + laptops. In this section, we will discuss:</para> + + <itemizedlist> + <listitem> + <para>Creating a parallel (laplink) cable.</para> + </listitem> + + <listitem> + <para>Connecting two computers with PLIP.</para> + </listitem> + </itemizedlist> + + <sect2 id="network-create-parallel-cable"> + <title>Creating a Parallel Cable</title> + + <para>You can purchase a parallel cable at most computer supply + stores. If you cannot do that, or you just want to know how + it is done, the following table shows how to make one out of a normal parallel + printer cable.</para> + + <table frame="none"> + <title>Wiring a Parallel Cable for Networking</title> + + <tgroup cols="5"> + <thead> + <row> + <entry>A-name</entry> + + <entry>A-End</entry> + + <entry>B-End</entry> + + <entry>Descr.</entry> + + <entry>Post/Bit</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literallayout>DATA0 +-ERROR</literallayout></entry> + + <entry><literallayout>2 +15</literallayout></entry> + + <entry><literallayout>15 +2</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x01 +1/0x08</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA1 ++SLCT</literallayout></entry> + + <entry><literallayout>3 +13</literallayout></entry> + + <entry><literallayout>13 +3</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x02 +1/0x10</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA2 ++PE</literallayout></entry> + + <entry><literallayout>4 +12</literallayout></entry> + + <entry><literallayout>12 +4</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x04 +1/0x20</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA3 +-ACK</literallayout></entry> + + <entry><literallayout>5 +10</literallayout></entry> + + <entry><literallayout>10 +5</literallayout></entry> + + <entry>Strobe</entry> + + <entry><literallayout>0/0x08 +1/0x40</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA4 +BUSY</literallayout></entry> + + <entry><literallayout>6 +11</literallayout></entry> + + <entry><literallayout>11 +6</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x10 +1/0x80</literallayout></entry> + </row> + + <row> + <entry>GND</entry> + + <entry>18-25</entry> + + <entry>18-25</entry> + + <entry>GND</entry> + + <entry>-</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 id="network-plip-setup"> + <title>Setting Up PLIP</title> + + <para>First, you have to get a laplink cable. + Then, confirm that both computers have a kernel with &man.lpt.4; driver + support:</para> + + <screen>&prompt.root; <userinput>grep lp /var/run/dmesg.boot</userinput> +lpt0: <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</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>Getting an IPv6 network from your upstream provider. Talk to your + Internet provider for instructions.</para> + </listitem> + + <listitem> + <para>Tunnel via 6-to-4 (<ulink + url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para> + </listitem> + + <listitem> + <para>Use the <filename role="package">net/freenet6</filename> port if you are on a dial-up connection.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>DNS in the IPv6 World</title> + + <para>There used to be two types of DNS records for IPv6. The IETF + has declared A6 records obsolete. AAAA records are the standard + now.</para> + + <para>Using AAAA records is straightforward. Assign your hostname to the new + IPv6 address you just received by adding:</para> + + <programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting> + + <para>To your primary zone DNS file. In case you do not serve your own + <acronym>DNS</acronym> zones ask your <acronym>DNS</acronym> provider. + Current versions of <application>bind</application> (version 8.3 and 9) + and <filename role="package">dns/djbdns</filename> (with the IPv6 patch) + support AAAA records.</para> + </sect2> + + <sect2> + <title>Applying the needed changes to <filename>/etc/rc.conf</filename></title> + + <sect3> + <title>IPv6 Client Settings</title> + + <para>These settings will help you configure a machine that will be on + your LAN and act as a client, not a router. To have &man.rtsol.8; + autoconfigure your interface on boot all you need to add is:</para> + + <programlisting>ipv6_enable="YES"</programlisting> + + <para>To statically assign an IP address such as <hostid role="ip6addr"> + 2001:471:1f11:251:290:27ff:fee0:2093</hostid>, to your + <devicename>fxp0</devicename> interface, add:</para> + + <programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting> + + <para>To assign a default router of + <hostid role="ip6addr">2001:471:1f11:251::1</hostid> + add the following to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting> + + </sect3> + + <sect3> + <title>IPv6 Router/Gateway Settings</title> + + <para>This will help you take the directions that your tunnel provider has + given you and convert it into settings that will persist through reboots. + To restore your tunnel on startup use something like the following in + <filename>/etc/rc.conf</filename>:</para> + + <para>List the Generic Tunneling interfaces that will be configured, for + example <devicename>gif0</devicename>:</para> + + <programlisting>gif_interfaces="gif0"</programlisting> + + <para>To configure the interface with a local endpoint of + <replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint of + <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para> + + <programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting> + + <para>To apply the IPv6 address you have been assigned for use as your + IPv6 tunnel endpoint, add:</para> + + <programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + + <para>Then all you have to do is set the default route for IPv6. This is + the other side of the IPv6 tunnel:</para> + + <programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + + </sect3> + + <sect3> + <title>IPv6 Tunnel Settings</title> + + <para>If the server is to route IPv6 between the rest of your network + and the world, the following <filename>/etc/rc.conf</filename> + setting will also be needed:</para> + + <programlisting>ipv6_gateway_enable="YES"</programlisting> + + </sect3> + </sect2> + + <sect2> + <title>Router Advertisement and Host Auto Configuration</title> + + <para>This section will help you setup &man.rtadvd.8; to advertise the + IPv6 default route.</para> + + <para>To enable &man.rtadvd.8; you will need the following in your + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>rtadvd_enable="YES"</programlisting> + + <para>It is important that you specify the interface on which to do + IPv6 router solicitation. For example to tell &man.rtadvd.8; to use + <devicename>fxp0</devicename>:</para> + + <programlisting>rtadvd_interfaces="fxp0"</programlisting> + + <para>Now we must create the configuration file, + <filename>/etc/rtadvd.conf</filename>. Here is an example:</para> + + <programlisting>fxp0:\ + :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting> + + <para>Replace <devicename>fxp0</devicename> with the interface you + are going to be using.</para> + + <para>Next, replace <hostid role="ip6addr">2001:471:1f11:246::</hostid> + with the prefix of your allocation.</para> + + <para>If you are dedicated a <hostid role="netmask">/64</hostid> subnet + you will not need to change anything else. Otherwise, you will need to + change the <literal>prefixlen#</literal> to the correct value.</para> + + </sect2> + </sect1> + + <sect1 id="network-atm"> + <sect1info> + <authorgroup> + <author> + <firstname>Harti</firstname> + <surname>Brandt</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Asynchronous Transfer Mode (ATM)</title> + + <sect2> + <title>Configuring classical IP over ATM (PVCs)</title> + + <para>Classical IP over ATM (<acronym>CLIP</acronym>) is the + simplest method to use Asynchronous Transfer Mode (ATM) + with IP. It can be used with + switched connections (SVCs) and with permanent connections + (PVCs). This section describes how to set up a network based + on PVCs.</para> + + <sect3> + <title>Fully meshed configurations</title> + + <para>The first method to set up a <acronym>CLIP</acronym> with + PVCs is to connect each machine to each other machine in the + network via a dedicated PVC. While this is simple to + configure it tends to become impractical for a larger number + of machines. The example supposes that we have four + machines in the network, each connected to the <acronym role="Asynchronous Transfer Mode">ATM</acronym> network + with an <acronym role="Asynchronous Transfer Mode">ATM</acronym> adapter card. The first step is the planning of + the IP addresses and the <acronym role="Asynchronous + Transfer Mode">ATM</acronym> connections between the + machines. We use the following:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="1*"> + <thead> + <row> + <entry>Host</entry> + <entry>IP Address</entry> + </row> + </thead> + + <tbody> + <row> + <entry><hostid>hostA</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.1</hostid></entry> + </row> + + <row> + <entry><hostid>hostB</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.2</hostid></entry> + </row> + + <row> + <entry><hostid>hostC</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.3</hostid></entry> + </row> + + <row> + <entry><hostid>hostD</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.4</hostid></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>To build a fully meshed net we need one ATM connection + between each pair of machines:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="1*"> + <thead> + <row> + <entry>Machines</entry> + <entry>VPI.VCI couple</entry> + </row> + </thead> + + <tbody> + <row> + <entry><hostid>hostA</hostid> - <hostid>hostB</hostid></entry> + <entry>0.100</entry> + </row> + + <row> + <entry><hostid>hostA</hostid> - <hostid>hostC</hostid></entry> + <entry>0.101</entry> + </row> + + <row> + <entry><hostid>hostA</hostid> - <hostid>hostD</hostid></entry> + <entry>0.102</entry> + </row> + + <row> + <entry><hostid>hostB</hostid> - <hostid>hostC</hostid></entry> + <entry>0.103</entry> + </row> + + <row> + <entry><hostid>hostB</hostid> - <hostid>hostD</hostid></entry> + <entry>0.104</entry> + </row> + + <row> + <entry><hostid>hostC</hostid> - <hostid>hostD</hostid></entry> + <entry>0.105</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>The VPI and VCI values at each end of the connection may + of course differ, but for simplicity we assume that they are + the same. Next we need to configure the ATM interfaces on + each host:</para> + + <screen>hostA&prompt.root; <userinput>ifconfig hatm0 192.168.173.1 up</userinput> +hostB&prompt.root; <userinput>ifconfig hatm0 192.168.173.2 up</userinput> +hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput> +hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen> + + <para>assuming that the ATM interface is + <devicename>hatm0</devicename> on all hosts. Now the PVCs + need to be configured on <hostid>hostA</hostid> (we assume that + they are already configured on the ATM switches, you need to + consult the manual for the switch on how to do this).</para> + + <screen>hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr</userinput> +hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr</userinput> +hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr</userinput> + +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr</userinput> +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr</userinput> +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr</userinput> + +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr</userinput> +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr</userinput> +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr</userinput> + +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr</userinput> +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr</userinput> +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</userinput></screen> + + <para>Of course other traffic contracts than UBR can be used + given the ATM adapter supports those. In this case the name + of the traffic contract is followed by the parameters of the + traffic. Help for the &man.atmconfig.8; tool can be + obtained with:</para> + + <screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen> + + <para>or in the &man.atmconfig.8; manual page.</para> + + <para>The same configuration can also be done via + <filename>/etc/rc.conf</filename>. + For <hostid>hostA</hostid> this would look like:</para> + +<programlisting>network_interfaces="lo0 hatm0" +ifconfig_hatm0="inet 192.168.173.1 up" +natm_static_routes="hostB hostC hostD" +route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr" +route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr" +route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting> + + <para>The current state of all <acronym>CLIP</acronym> routes + can be obtained with:</para> + + <screen>hostA&prompt.root; <userinput>atmconfig natm show</userinput></screen> + </sect3> + </sect2> + </sect1> + + <sect1 id="carp"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Common Access Redundancy Protocol (CARP)</title> + + <indexterm><primary>CARP</primary></indexterm> + <indexterm><primary>Common Access Redundancy Protocol</primary></indexterm> + + <para>The Common Access 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 with the following option:</para> + + <programlisting>device carp</programlisting> + + <para><acronym>CARP</acronym> functionality should now be available + and may be tuned via several <command>sysctl</command> + <acronym>OID</acronym>s. Devices themselves may be loaded 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 testpast 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 + <quote>nudge</quote> the interface. 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> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> +<!-- LocalWords: config mnt www --> |