<!--

     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.234 2003/07/21 13:35:50 blackend Exp $

-->

<chapter id="advanced-networking">

  <title>Advanced Networking</title>

  <sect1 id="advanced-networking-synopsis">

    <title>Synopsis</title>

    <para>This chapter will cover some of the more frequently used network

      services on Unix systems.  We will cover how to define, setup, test and

      maintain all of the network services that FreeBSD utilizes.  In addition,

      there have been example configuration files included throughout this

      chapter for you to benefit from.</para>

    <para>After reading this chapter, you will know:</para>

    <itemizedlist>

      <listitem>

	<para>The basics of gateways and routes.</para>

      </listitem>

      <listitem>

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

      </listitem>

      <listitem>

	<para>How to setup a network filesystem.</para>

      </listitem>

      <listitem>

	<para>How to setup network booting on a diskless machine.</para>

      </listitem>

      <listitem>

	<para>How to setup a network information server for sharing user

	  accounts.</para>

      </listitem>

      <listitem>

	<para>How to setup automatic network settings using DHCP.</para>

      </listitem>

      <listitem>

	<para>How to setup a domain name server.</para>

      </listitem>

      <listitem>

	<para>How to synchronize the time and date, and setup a

	  time server, with the NTP protocol.</para>

      </listitem>

      <listitem>

	<para>How to setup network address translation.</para>

      </listitem>

      <listitem>

	<para>How to manage the <command>inetd</command> daemon.</para>

      </listitem>

      <listitem>

	<para>How to connect two computers via PLIP.</para>

      </listitem>

      <listitem>

	<para>How to setup IPv6 on a FreeBSD machine.</para>

      </listitem>

    </itemizedlist>

    <para>Before reading this chapter, you should:</para>

    <itemizedlist>

      <listitem>

	<para>Understand the basics of the <filename>/etc/rc</filename> scripts.</para>

      </listitem>

      <listitem>

	<para>Be familiar with basic network terminology.</para>

      </listitem>

    </itemizedlist>

  </sect1>

  <sect1 id="network-routing">

    <sect1info>

      <authorgroup>

        <author>

          <firstname>Coranth</firstname>

      	  <surname>Gryphon</surname>

	  <contrib>Contributed by </contrib>

        </author>

      </authorgroup>

    </sect1info>

    <title>Gateways and Routes</title>

    <indexterm><primary>routing</primary></indexterm>

    <indexterm><primary>gateway</primary></indexterm>

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

    <para>For one machine to be able to find another over a network,

      there must be a mechanism in place to describe how to get from

      one to the other.  This is called

      <firstterm>routing</firstterm>.  A <quote>route</quote> is a

      defined pair of addresses: a <quote>destination</quote> and a

      <quote>gateway</quote>.  The pair indicates that if you are

      trying to get to this <emphasis>destination</emphasis>,

      communicate through this <emphasis>gateway</emphasis>.  There

      are three types of destinations: individual hosts, subnets, and

      <quote>default</quote>.  The <quote>default route</quote> is

      used if none of the other routes apply.  We will talk a little

      bit more about default routes later on.  There are also three

      types of gateways: individual hosts, interfaces (also called

      <quote>links</quote>), and Ethernet hardware addresses (MAC

      addresses).

    </para>

    <sect2>

      <title>An Example</title>

      <para>To illustrate different aspects of routing, we will use the

	following example from <command>netstat</command>:</para>

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

Routing tables

Destination      Gateway            Flags     Refs     Use     Netif Expire

default          outside-gw         UGSc       37      418      ppp0

localhost        localhost          UH          0      181       lo0

test0            0:e0:b5:36:cf:4f   UHLW        5    63288       ed0     77

10.20.30.255     link#1             UHLW        1     2421

example.com      link#1             UC          0        0

host1            0:e0:a8:37:8:1e    UHLW        3     4601       lo0

host2            0:e0:a8:37:8:1e    UHLW        0        5       lo0 =>

host2.example.com link#1             UC          0        0

224              link#1             UC          0        0</screen>

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

      <para>The first two lines specify the default route (which we

	will cover in the <link linkend="network-routing-default">next

	  section</link>) and the <hostid>localhost</hostid> route.</para>

      <indexterm><primary>loopback device</primary></indexterm>

      <para>The interface (<literal>Netif</literal> column) that this

	routing table specifies to use for

	<literal>localhost</literal> is <devicename>lo0</devicename>,

	also known as the loopback device.  This says to keep all

	traffic for this destination internal, rather than sending it

	out over the LAN, since it will only end up back where it

	started.</para>

      <indexterm>

        <primary>Ethernet</primary>

        <secondary>MAC address</secondary>

      </indexterm>

      <para>The next thing that stands out are the addresses beginning

	with <hostid role="mac">0:e0:</hostid>.  These are Ethernet

	hardware addresses, which are also known as MAC addresses.

	FreeBSD will automatically identify any hosts

	(<hostid>test0</hostid> in the example) on the local Ethernet

	and add a route for that host, directly to it over the

	Ethernet interface, <devicename>ed0</devicename>.  There is

	also a timeout (<literal>Expire</literal> column) associated

	with this type of route, which is used if we fail to hear from

	the host in a specific amount of time.  When this happens, the

	route to this host will be automatically deleted.  These hosts

	are identified using a mechanism known as RIP (Routing

	Information Protocol), which figures out routes to local hosts

	based upon a shortest path determination.</para>

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

      <para>FreeBSD will also add subnet routes for the local subnet (<hostid

	  role="ipaddr">10.20.30.255</hostid> is the broadcast address for the

	subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid

	  role="domainname">example.com</hostid> is the domain name associated

	with that subnet).  The designation <literal>link#1</literal> refers

	to the first Ethernet card in the machine.  You will notice no

	additional interface is specified for those.</para>

      <para>Both of these groups (local network hosts and local subnets) have

	their routes automatically configured by a daemon called

	<application>routed</application>.  If this is not run, then only

	routes which are statically defined (i.e. entered explicitly) will

	exist.</para>

      <para>The <literal>host1</literal> line refers to our host, which it

	knows by Ethernet address.  Since we are the sending host, FreeBSD

	knows to use the loopback interface (<devicename>lo0</devicename>)

	rather than sending it out over the Ethernet interface.</para>

      <para>The two <literal>host2</literal> lines are an example of

	what happens when we use an &man.ifconfig.8; alias (see the

	section on Ethernet for reasons why we would do this).  The

	<literal>=&gt;</literal> symbol after the

	<devicename>lo0</devicename> interface says that not only are

	we using the loopback (since this address also refers to the

	local host), but specifically it is an alias.  Such routes

	only show up on the host that supports the alias; all other

	hosts on the local network will simply have a

	<literal>link#1</literal> line for such routes.</para>

      <para>The final line (destination subnet <literal>224</literal>) 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">

	<tgroup cols="2">

	  <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>

      <literallayout>

[Local2]  <--ether-->  [Local1]  <--PPP--> [ISP-Serv]  <--ether-->  [T1-GW]

      </literallayout>

      <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">

	<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>As a final note, 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">

	<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>

    </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.</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 gated 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>

      <para>Even when FreeBSD is configured in this way, it does not

	completely comply with the Internet standard requirements for

	routers.  It comes close enough for ordinary use,

	however.</para>

    </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</primary>

	<secondary>options 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 DVMRP via

	<filename>/etc/mrouted.conf</filename>.  More details on

	multicast configuration may be found in the man pages for

	mrouted.</para>

    </sect2>

  </sect1>

  <sect1 id="network-wireless">

    <sect1info>

      <authorgroup>

        <author>

          <firstname>Eric</firstname>

          <surname>Anderson</surname>

          <contrib>Written by </contrib>

        </author>

      </authorgroup>

    </sect1info>

    <title>Wireless Networking</title>

   <indexterm><primary>wireless networking</primary></indexterm>

   <indexterm>

     <primary>802.11</primary>

     <see>wireless networking</see>

   </indexterm>

   <sect2>

      <title>Introduction</title>

      <para>It can be very useful to be able to use a computer without the

      annoyance of having a network cable attached at all times.  FreeBSD can

      be used as a wireless client, and even as a wireless <quote>access

      point</quote>.</para>

   </sect2>

   <sect2>

     <title>Wireless Modes of Operation</title>

     <para>There are two different ways to configure 802.11 wireless devices:

      BSS and IBSS.</para>

     <sect3>

       <title>BSS Mode</title>

       <para>BSS mode is the mode that typically is used.  BSS mode is

        also called infrastructure mode.  In this mode, a number of

        wireless access points are connected to a wired network.  Each

        wireless network has its own name.  This name is called the

        SSID of the network.</para>

       <para>Wireless clients connect to these wireless access

        points. The IEEE 802.11 standard defines the protocol that

        wireless networks use to connect.  A wireless client can be

        tied to a specific network, when a SSID is set.  A wireless

        client can also attach to any network by not explicitly

        setting a SSID.</para>

     </sect3>

     <sect3>

       <title>IBSS Mode</title>

       <para>IBSS mode, also called ad-hoc mode, is designed for point

         to point connections.  There are actually two types of ad-hoc

         mode.  One is IBSS mode, also called ad-hoc or IEEE ad-hoc

         mode.  This mode is defined by the IEEE 802.11 standards.

         The second is called demo ad-hoc mode or Lucent ad-hoc mode

         (and sometimes, confusingly, ad-hoc mode).  This is the old,

         pre-802.11 ad-hoc mode and should only be used for legacy

	 installations.  We will not cover either of the ad-hoc modes

         further.</para>

     </sect3>

   </sect2>

   <sect2>

     <title>Infrastructure Mode</title>

     <sect3>

       <title>Access Points</title>

       <para>Access points are wireless networking devices that allow

        one or more wireless clients to use the device as a central

        hub.  When using an access point, all clients communicate

        through the access point.  Multiple access points are often

        used to cover a complete area such as a house, business, or

        park with a wireless network.</para>

       <para>Access points typically have multiple network

       connections: the wireless card, and one or more wired Ethernet

       adapters for connection to the rest of the network.

       </para>

       <para>Access points can either be purchased prebuilt, or you

        can build your own with FreeBSD and a supported wireless card.

        Several vendors make wireless access points and wireless cards

        with various features.</para>

     </sect3>

     <sect3>

       <title>Building a FreeBSD Access Point</title>

       <indexterm><primary>wireless networking</primary>

         <secondary>access point</secondary>

       </indexterm>

       <sect4><title>Requirements</title>

         <para>In order to set up a wireless access point with

          FreeBSD, you need to have a compatible wireless card.

          Currently, only cards with the Prism chipset are

          supported. You will also need a wired network card that is

          supported by FreeBSD (this should not be difficult to find,

          FreeBSD supports a lot of different devices).  For this

          guide, we will assume you want to &man.bridge.4; all traffic

          between the wireless device and the network attached to the

          wired network card.</para>

	 <para>The hostap functionality that FreeBSD uses to implement

           the access point works best with certain versions of

           firmware.  Prism 2 cards should use firmware version 1.3.4

           or newer.  Prism 2.5 and Prism 3 cards should use firmware

           1.4.9.  Older versions of the firmware way or may not

           function correctly.  At this time, the only way to update

           cards is with windows firmware update utilities available

           from your card's manufacturer.</para>

       </sect4>

       <sect4>

         <title>Setting It Up</title>

         <para>First, make sure your system can see the wireless card:</para>

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

wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500

        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7

        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255

        ether 00:09:2d:2d:c9:50

        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)

        status: no carrier

        ssid ""

        stationname "FreeBSD Wireless node"

        channel 10 authmode OPEN powersavemode OFF powersavesleep 100

        wepmode OFF weptxkey 1</screen>

         <para>Do not worry about the details now, just make sure it shows you

          something to indicate you have a wireless card installed.

	  If you have trouble seeing the wireless interface, and you

	  are using a PC Card, you may want to check out

	  &man.pccardc.8; and &man.pccardd.8; manual pages for more

	  information.</para>

         <para>Next, you will need to load a module in order to get

          the bridging part of FreeBSD ready for the access point.  In

          order to load the &man.bridge.4; module, simply run the

          following command:</para>

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

         <para>It should not have produced any errors when loading the

          module.  If it did, you may need to compile the

          &man.bridge.4; code into your kernel.  The <link

          linkend="network-bridging">Bridging</link> section of the handbook

          should be able to help you accomplish that task.</para>

         <para>Now that you have the bridging stuff done, we need to

          tell the FreeBSD kernel which interfaces to bridge together.

          We do that by using &man.sysctl.8;:</para>

         <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput>

&prompt.root; <userinput>sysctl net.link.ether.bridge_cfg="wi0 xl0"</userinput>

&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>

         <para>Now it is time for the wireless card setup.</para>

         <para>The following command will set the card into an access point:</para>

         <screen>

&prompt.root; <userinput>ifconfig wi0 ssid my_net channel 11 media DS/11Mbps mediaopt hostap up stationname "FreeBSD AP"</userinput>

         </screen>

         <para>The &man.ifconfig.8; line brings the

	  <devicename>wi0</devicename> interface up, sets its SSID to

	  <literal>my_net</literal>, and sets the station name to

	  <literal>FreeBSD AP</literal>.  The <option>media

	  DS/11Mbps</option> sets the card into 11Mbps mode and is

	  needed for any <option>mediaopt</option> to take effect.

	  The <option>mediaopt hostap</option> option places the

	  interface into access point mode.  The <option>channel

	  11</option> option sets the 802.11b channel to use.  The

	  &man.wicontrol.8; man page has valid channel options for

	  your regulatory domain.

         </para>

         <para>Now you should have a complete functioning access point

          up and running.  You are encouraged to read

          &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for

          further information.

         </para>

         <para>It is also suggested that you read the section on encryption that follows.</para>

       </sect4>

       <sect4>

         <title>Status Information</title>

	 <para>Once the access point is configured and operational,

	   operators will want to see the clients that are associated

	   with the access point.  At any time, the operator may type:</para>

         <screen>&prompt.root; <userinput>wicontrol -l</userinput>

1 station:

00:09:b7:7b:9d:16  asid=04c0, flags=3<ASSOC,AUTH>, caps=1<ESS>, rates=f<1M,2M,5.5M,11M>, sig=38/15

</screen>

         <para>This shows that there's one station associated, along

           with its parameters.  The signal indicated should be used

           as a relative indication of strength only.  Its

           translation to dBm or other units varies between different

           firmware revisions.</para>

       </sect4>

     </sect3>

     <sect3>

       <title>Clients</title>

       <para>A wireless client is a system that accesses an access

       point or another client directly. </para>

       <para>Typically, wireless clients only have one network device,

       the wireless networking card.<para>

       <para>There are a few different ways to configure a wireless

        client.  These are based on the different wireless modes,

        generally BSS (infrastructure mode, which requires an access

        point), and IBSS (ad-hoc, or peer-to-peer mode).  In our

        example, we will use the most popular of the two, BSS mode, to

        talk to an access point.</para>

       <sect4>

       <title>Requirements</title>

       <para>There is only one real requirement for setting up FreeBSD as a wireless client.

        You will need a wireless card that is supported by FreeBSD.</para>

       </sect4>

       <sect4>

       <title>Setting Up a Wireless FreeBSD Client</title>

       <para>You will need to know a few things about the wireless

        network you are joining before you start.  In this example, we

        are joining a network that has a name of

        <literal>my_net</literal>, and encryption turned off.</para>

       <para>Note: In this example, we are not using encryption, which

        is a dangerous situation.  In the next section, you will learn

        how to turn on encryption, and why it is important to do so,

        and why some encryption technologies still do not completely

        protect you.</para>

       <para>Make sure your card is recognized by FreeBSD:</para>

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

wi0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500

        inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7

        inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255

        ether 00:09:2d:2d:c9:50

        media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)

        status: no carrier

        ssid ""

        stationname "FreeBSD Wireless node"

        channel 10 authmode OPEN powersavemode OFF powersavesleep 100

        wepmode OFF weptxkey 1</screen>

       <para>Now, we will set the card to the correct settings for our

       network:</para>

       <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net</userinput></screen>

       <para>Replace <hostid role="IPAddr">192.168.0.20</hostid> and

        <hostid role="Netmask">255.255.255.0</hostid> with a valid IP

        address and netmask on your wired network.  Remember, our

        access point is bridging the data between the wireless

        network, and the wired network, so it will appear to the other

        devices on your network that you are on the wired network just

        as they are.</para>

       <para>Once you have done that, you should be able to ping hosts

        on the wired network just as if you were connected using a

        standard wired connection.</para>

       <para>If you are experiencing problems with your wireless

        connection, check to make sure that your are associated

        (connected) to the access point:</para>

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

       <para>should return some information, and you should see:</para>

       <screen>status: associated</screen>

       <para>If it does not show associated, then you may be out of

       range of the access point, do not have encryption on, or

       possibly have a configuration problem.</para>

       </sect4>

     </sect3>

     <sect3>

      <title>Encryption</title>

      <indexterm>

        <primary>wireless networking</primary>

        <secondary>encryption</secondary>

      </indexterm>

      <para>Encryption on a wireless network is important because you

       no longer have the ability to keep the network contained in a

       well protected area.  Your wireless data will be broadcast

       across your entire neighborhood, so anyone who cares to read it

       can.  This is where encryption comes in.  By encrypting the

       data that is sent over the airwaves, you make it much more

       difficult for any interested party to grab your data right out

       of the air. </para>

     <para>The two most common ways to encrypt the data between your

      client and the access point, are WEP, and &man.ipsec.4;.</para>

     <sect4>

     <title>WEP</title>

      <indexterm><primary>WEP</primary></indexterm>

      <para>WEP is an abbreviation for Wired Equivalency Protocol.

       WEP is an attempt to make wireless networks as safe and secure

       as a wired network.  Unfortunately, it has been cracked, and is

       fairly trivial to break.  This also means it is not something

       to rely on when it comes to encrypting sensitive data.  </para>

      <para>It is better than nothing, so use the following to turn on

       WEP on your new FreeBSD access point:</para>

      <screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap</userinput></screen>

      <para>And you can turn on WEP on a client with this command:</para>

      <screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890</userinput></screen>

      <para>Note that you should replace the <literal>0x1234567890</literal> with a more unique key.</para>

     </sect4>

     <sect4>

     <title>IPsec</title>

     <para>&man.ipsec.4; is a much more robust and powerful tool for

       encrypting data across a network.  This is definitely the

       preferred way to encrypt wireless data over a network.  You can

       read more about &man.ipsec.4; security and how to implement it

       in the <link linkend="ipsec">IPsec</link> section of the

       handbook.</para>

     </sect4>

    </sect3>

    <sect3>

    <title>Tools</title>

    <para>There are a small number of tools available for use in

      debugging and setting up your wireless network, and here we will

      attempt to describe some of them and what they do.</para>

    <sect4>

    <title>The <application>bsd-airtools</application> Package</title>

    <para>The <application>bsd-airtools</application> package is a

      complete toolset that includes wireless auditing tools for WEP

      key cracking, access point detection, etc.</para>

    <para>The <application>bsd-airtools</application> utilities can be

      installed from the <filename

      role="package">net/bsd-airtools</filename> port.  Information on

      installing ports can be found in <xref linkend="ports"> of the

      handbook.</para>

    <para>The program <command>dstumbler</command> is the packaged

      tool that allows for access point discovery and signal to noise

      ratio graphing.  If you are having a hard time getting your

      access point up and running, <command>dstumbler</command> may

      help you get started.</para>

    <para>To test your wireless network security, you may choose to

      use <quote>dweputils</quote> (<command>dwepcrack</command>,

      <command>dwepdump</command> and <command>dwepkeygen</command>)

      to help you determine if WEP is the right solution to your

      wireless security needs.</para>

    </sect4>

    <sect4>

    <title>The <application>wicontrol</application>, <application>ancontrol</application> and <application>raycontrol</application> Utilities</title>

    <para>These are the tools you use to control how your wireless

      card behaves on the wireless network.  In the examples above, we

      have chosen to use &man.wicontrol.8;, since our wireless card is

      a <devicename>wi0</devicename> interface.  If you had a Cisco

      wireless device, it would come up as

      <devicename>an0</devicename>, and therefore you would use

      &man.ancontrol.8;.<para>

    </sect4>

    <sect4>

    <title>The <application>ifconfig</application> Command</title>

    <indexterm><primary>ifconfig</primary></indexterm>

    <para>&man.ifconfig.8; can be used to do many of the same options

      as &man.wicontrol.8;, however it does lack a few options.  Check

      &man.ifconfig.8; for command line parameters and options.</para>

    </sect4>

    </sect3>

    <sect3>

    <title>Supported Cards</title>

    <sect4>

    <title>Access Points</title>

    <para>The only cards that are currently supported for BSS (as an

      access point) mode are devices based on the Prism 2, 2.5, or 3

      chipsets. For a complete list, look at &man.wi.4;.</para>

    </sect4>

    <sect4>

    <title>Clients</title>

    <para>Almost all 802.11b wireless cards are currently supported

      under FreeBSD.  Most cards based on Prism, Spectrum24, Hermes,

      Aironet, and Raylink will work as a wireless network card in

      IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>

    </sect4>

    </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 A for file service, and the Production users

	  are on server B.  An Ethernet 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>IP Masquerading</primary></indexterm>

	<para>The second common situation is where firewall functionality is

	  needed without IP Masquerading (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 as of FreeBSD 4.0

	  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>options 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 <varname>IPFIREWALL</varname> option as

	  well.  Read <xref linkend="firewalls"> for general

	  information on configuring the bridge as a firewall.</para>

	<para>If you need to allow non-IP packets (such as ARP) to flow

	  through the bridge, there is an undocumented firewall option that

	  must be set.  This option is

	  <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>.  Note that this

	  changes the default rule for the firewall to accept any packet.

	  Make sure you know how this changes the meaning of your ruleset

	  before you set it.</para>

      </sect3>

      <sect3>

	<title>Traffic Shaping Support</title>

	<para>If you want to use the bridge as a traffic shaper, you will need

	  to add the <literal>DUMMYNET</literal> option to your kernel

	  configuration.  Read &man.dummynet.4; for further

	  information.</para>

      </sect3>

    </sect2>

    <sect2>

      <title>Enabling the Bridge</title>

      <para>Add the line:</para>

      <programlisting>net.link.ether.bridge=1</programlisting>

      <para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at

	runtime, and the line:</para>

      <programlisting>net.link.ether.bridge_cfg=<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>

    </sect2>

    <sect2>

      <title>Other Information</title>

      <para>If you want to be able to telnet into the bridge from the network,

	it is OK 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 ping times, especially for

        traffic from one segment to another.

    </sect2>

  </sect1>

  <sect1 id="network-nfs">

    <sect1info>

      <authorgroup>

        <author>

          <firstname>Tom</firstname>

          <surname>Rhodes</surname>

          <contrib>Reorganized and enhanced by </contrib>

        </author>

      </authorgroup>

      <authorgroup>

        <author>

          <firstname>Bill</firstname>

      	  <surname>Swingle</surname>

	  <contrib>Written by </contrib>

        </author>

      </authorgroup>

    </sect1info>

    <title>NFS</title>

    <indexterm><primary>NFS</primary></indexterm>

    <para>Among the many different filesystems that FreeBSD supports is

      the Network File System, also known as <acronym>NFS</acronym>.

      <acronym>NFS</acronym> allows a system to share directories and files

      with others over a network.  By using <acronym>NFS</acronym>, users and

      programs can access files on remote systems almost as if they were local

      files.</para>

    <para>Some of the most notable benefits that

      <acronym>NFS</acronym> can provide are:</para>

    <itemizedlist>

      <listitem>

	<para>Local workstations use less disk space because

	  commonly used data can be stored on a single machine and still

	  remain accessible to others over the network.</para>

      </listitem>

      <listitem>

	<para>There is no need for users to have separate home directories

	  on every network machine.  Home directories could be setup on the

	  <acronym>NFS</acronym> server and made available throughout

	  the network.</para>

      </listitem>

      <listitem>

	<para>Storage devices such as floppy disks, CDROM drives, and

	  ZIP drives can be used by other machines on the network.

	  This may reduce the number of removable media drives

	  throughout the network.</para>

      </listitem>

    </itemizedlist>

    <sect2>

      <title>How <acronym>NFS</acronym> Works</title>

      <para><acronym>NFS</acronym> consists of at least two main parts:

        a server and one or more clients.  The client remotely accesses

        the data that is stored

        on the server machine.  In order for this to function properly a few

        processes have to be configured and running:</para>

      <note><para>In &os; 5.X, the <application>portmap</application> utility

	has been replaced with the <command>rpcbind</command> utility.  Thus,

	in &os; 5.X the user is required to replace every instance of

	<application>portmap</application> with <command>rpcbind</command>

	in the forthcoming examples.</para></note>

      <para>The server has to be running the following daemons:</para>

      <indexterm>

        <primary>NFS</primary>

        <secondary>server</secondary>

      </indexterm>

      <indexterm>

        <primary><application>portmap</application></primary>

      </indexterm>

      <indexterm>

        <primary><application>mountd</application></primary>

      </indexterm>

      <indexterm>

        <primary><application>nfsd</application></primary>

      </indexterm>

      <informaltable frame="none">

	<tgroup cols="2">

	  <thead>

	    <row>

	      <entry>Daemon</entry>

	      <entry>Description</entry>

	    </row>

	  </thead>

	  <tbody>

	    <row>

	      <entry>nfsd</entry>

	      <entry>The <acronym>NFS</acronym> daemon which services requests from

              the <acronym>NFS</acronym> clients.</entry>

	    </row>

	    <row>

	      <entry>mountd</entry>

	      <entry>The <acronym>NFS</acronym> mount daemon which carries out

		the requests that &man.nfsd.8; passes on to it.</entry>

	    </row>

	    <row>

	      <entry>portmap</entry>

	      <entry> The portmapper daemon

                allows <acronym>NFS</acronym> clients to discover which port the <acronym>NFS</acronym> server

                is using.</entry>

	    </row>

	  </tbody>

	</tgroup>

      </informaltable>

      <para>The client can also run a daemon, known as

        <application>nfsiod</application>.  The

        <application>nfsiod</application> daemon services the requests

        from the <acronym>NFS</acronym> server.  This is optional, and

        improves performance, but is not required for normal and

        correct operation.  See the &man.nfsiod.8; manual page for

        more information.

      </para>

    </sect2>

    <sect2 id="network-configuring-nfs">

      <title>Configuring <acronym>NFS</acronym></title>

      <indexterm>

        <primary>NFS</primary>

        <secondary>configuration</secondary>

      </indexterm>

      <para><acronym>NFS</acronym> configuration is a relatively

        straightforward process.  The processes that need to be

        running can all start at boot time with a few modifications to

        your <filename>/etc/rc.conf</filename> file.</para>

      <para>On the <acronym>NFS</acronym> server, make sure that the

        following options are configured in the

        <filename>/etc/rc.conf</filename> file:</para>

      <programlisting>portmap_enable="YES"

nfs_server_enable="YES"

mountd_flags="-r"</programlisting>

      <para><command>mountd</command> runs automatically whenever the

        <acronym>NFS</acronym> server is enabled.</para>

      <para>On the client, make sure this option is present in

        <filename>/etc/rc.conf</filename>:</para>

      <programlisting>nfs_client_enable="YES"</programlisting>

      <para>The <filename>/etc/exports</filename> file specifies which

        filesystems <acronym>NFS</acronym> should export (sometimes

        referred to as <quote>share</quote>).  Each line in

        <filename>/etc/exports</filename> specifies a filesystem to be

        exported and which machines have access to that filesystem.

        Along with what machines have access to that filesystem,

        access options may also be specified.  There are many such

        options that can be used in this file but only a few will be

        mentioned here.  You can easily discover other options by

        reading over the &man.exports.5; manual page.</para>

      <para>Here are a few example <filename>/etc/exports</filename>

	entries:</para>

      <indexterm>

        <primary>NFS</primary>

        <secondary>export examples</secondary>

      </indexterm>

      <para>The following examples give an idea of how to export filesystems,

        although the settings may be different depending on

        your environment and network configuration.

        For instance, to export the <filename>/cdrom</filename> directory to

	three example machines that have the same domain name as the server

	(hence the lack of a domain name for each) or have entries in your

	<filename>/etc/hosts</filename> file.  The <option>-ro</option>

	flag makes the exported filesystem read-only.  With this flag, the

	remote system will not be able to write any changes to the

	exported filesystem.</para>

      <programlisting>/cdrom -ro host1 host2 host3</programlisting>

      <para>The following line exports <filename>/home</filename> to

	three hosts by IP address.  This is a useful setup if you have

	a private network without a <acronym>DNS</acronym> server

	configured.  Optionally the <filename>/etc/hosts</filename>

	file could be configured for internal hostnames; please review

	&man.hosts.5; for more information.  The

	<option>-alldirs</option> flag allows the subdirectories to be

	mount points.  In other words, it will not mount the

	subdirectories but permit the client to mount only the

	directories that are required or needed.</para>

      <programlisting>/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>

      <para>The following line exports <filename>/a</filename> so that

	two clients from different domains may access the filesystem.

	The <option>-maproot=root</option> flag allows the

	<username>root</username> user on the remote system to write

	data on the exported filesystem as <username>root</username>.

	If the <literal>-maproot=root</literal> flag is not specified,

	then even if a user has <username>root</username> access on

	the remote system, they will not be able to modify files on

	the exported filesystem.</para>

      <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>

      <para>In order for a client to access an exported filesystem,

	the client must have permission to do so.  Make sure the

	client is listed in your <filename>/etc/exports</filename>

	file.</para>

      <para>In <filename>/etc/exports</filename>, each line represents

	the export information for one filesystem to one host.  A

	remote host can only be specified once per filesystem, and may

	only have one default entry.  For example, assume that

	<filename>/usr</filename> is a single filesystem.  The

	following <filename>/etc/exports</filename> would be

	invalid:</para>

      <programlisting>/usr/src   client

/usr/ports client</programlisting>

      <para>One filesystem, <filename>/usr</filename>, has two lines

	specifying exports to the same host, <hostid>client</hostid>.

        The correct format for this situation is:</para>

      <programlisting>/usr/src /usr/ports  client</programlisting>

      <para>The properties of one filesystem exported to a given host

	must all occur on one line.  Lines without a client specified

	are treated as a single host.  This limits how you can export

	filesystems, but for most people this is not an issue.</para>

      <para>The following is an example of a valid export list, where

	<filename>/usr</filename> and <filename>/exports</filename>

	are local filesystems:</para>

      <programlisting># Export src and ports to client01 and client02, but only

# client01 has root privileges on it

/usr/src /usr/ports -maproot=root    client01

/usr/src /usr/ports               client02

# The client machines have root and can mount anywhere

# on /exports. Anyone in the world can mount /exports/obj read-only

/exports -alldirs -maproot=root      client01 client02

/exports/obj -ro</programlisting>

      <para>You must restart

        <command>mountd</command> whenever you modify

        <filename>/etc/exports</filename> so the changes can take effect.

        This can be accomplished by sending the HUP signal

        to the <command>mountd</command> process:</para>

      <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>

      <para>Alternatively, a reboot will make FreeBSD set everything

        up properly.  A reboot is not necessary though.

        Executing the following commands as <username>root</username>

        should start everything up.</para>

      <para>On the <acronym>NFS</acronym> server:</para>

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

&prompt.root; <userinput>nfsd -u -t -n 4</userinput>

&prompt.root; <userinput>mountd -r</userinput></screen>

      <para>On the <acronym>NFS</acronym> client:</para>

      <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>

      <para>Now everything should be ready to actually mount a remote file

	system.  In these examples the

	server's name will be <literal>server</literal> and the client's

	name will be <literal>client</literal>.  If you only want to

	temporarily mount a remote filesystem or would rather test the

	configuration, just execute a command like this as <username>root</username> on the

        client:</para>

      <indexterm>

        <primary>NFS</primary>

        <secondary>mounting</secondary>

      </indexterm>

      <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>

      <para>This will mount the <filename>/home</filename> directory

	on the server at <filename>/mnt</filename> on the client.  If

	everything is set up correctly you should be able to enter

	<filename>/mnt</filename> on the client and see all the files

        that are on the server.</para>

      <para>If you want to automatically mount a remote filesystem

	each time the computer boots, add the filesystem to the

	<filename>/etc/fstab</filename> file.  Here is an example:</para>

      <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>

      <para>The &man.fstab.5; manual page lists all the available options.</para>

    </sect2>

    <sect2>

      <title>Practical Uses</title>

      <para><acronym>NFS</acronym> has many practical uses.  Some of the more common

        ones are listed below:</para>

      <indexterm>

        <primary>NFS</primary>

        <secondary>uses</secondary>

      </indexterm>

      <itemizedlist>

        <listitem>

	  <para>Set several machines to share a CDROM or other media

	    among them.  This is cheaper and often a more convenient

	    method to install software on multiple machines.</para>

	</listitem>

	<listitem>

	  <para>On large networks, it might be more convenient to

	    configure a central <acronym>NFS</acronym> server in which

	    to store all the user home directories.  These home

	    directories can then be exported to the network so that

	    users would always have the same home directory,

	    regardless of which workstation they log in to.</para>

	</listitem>

	<listitem>

	  <para>Several machines could have a common

            <filename>/usr/ports/distfiles</filename> directory.  That

            way, when you need to install a port on several machines,

            you can quickly access the source without downloading it

            on each machine.</para>

	</listitem>

      </itemizedlist>

    </sect2>

    <sect2 id="network-amd">

      <sect2info>

	<authorgroup>

	  <author>

	    <firstname>Wylie</firstname>

	    <surname>Stilwell</surname>

	    <contrib>Contributed by </contrib>

	  </author>

	</authorgroup>

	<authorgroup>

	  <author>

	    <firstname>Chern</firstname>

	    <surname>Lee</surname>

	    <contrib>Rewritten by </contrib>

	  </author>

	</authorgroup>

      </sect2info>

      <title>Automatic Mounts with <application>amd</application></title>

      <indexterm><primary>amd</primary></indexterm>

      <indexterm><primary>automatic mounter daemon</primary></indexterm>

      <para>&man.amd.8; (the automatic mounter daemon)

	automatically mounts a

	remote filesystem whenever a file or directory within that

	filesystem is accessed.  Filesystems that are inactive for a

	period of time will also be automatically unmounted by

	<application>amd</application>.  Using

	<application>amd</application> provides a simple alternative

	to permanent mounts, as permanent mounts are usually listed in

        <filename>/etc/fstab</filename>.</para>

      <para><application>amd</application> operates by attaching

	itself as an NFS server to the <filename>/host</filename> and

	<filename>/net</filename> directories.  When a file is accessed

	within one of these directories, <application>amd</application>

	looks up the corresponding remote mount and automatically mounts

	it.  <filename>/net</filename> is used to mount an exported

	filesystem from an IP address, while <filename>/host</filename>

	is used to mount an export from a remote hostname.</para>

      <para>An access to a file within

	<filename>/host/foobar/usr</filename> would tell

	<application>amd</application> to attempt to mount the

	<filename>/usr</filename> export on the host

	<hostid>foobar</hostid>.</para>

      <example>

	<title>Mounting an Export with <application>amd</application></title>

	<para>You can view the available mounts of a remote host with

	  the <command>showmount</command> command.  For example, to

	  view the mounts of a host named <hostid>foobar</hostid>, you

	  can use:</para>

	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>

Exports list on foobar:

/usr                               10.10.10.0

/a                                 10.10.10.0

&prompt.user; <userinput>cd /host/foobar/usr</userinput></screen>

      </example>

      <para>As seen in the example, the <command>showmount</command> shows

	<filename>/usr</filename> as an export.  When changing directories to

	<filename>/host/foobar/usr</filename>, <application>amd</application>

	attempts to resolve the hostname <hostid>foobar</hostid> and

	automatically mount the desired export.</para>

      <para><application>amd</application> can be started by the

	startup scripts by placing the following lines in

	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>amd_enable="YES"</programlisting>

      <para>Additionally, custom flags can be passed to

      <application>amd</application> from the

      <varname>amd_flags</varname> option.  By default,

      <varname>amd_flags</varname> is set to:</para>

      <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>

      <para>The <filename>/etc/amd.map</filename> file defines the

	default options that exports are mounted with.  The

	<filename>/etc/amd.conf</filename> file defines some of the more

	advanced features of <application>amd</application>.</para>

      <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more

	information.</para>

    </sect2>

    <sect2 id="network-nfs-integration">

      <sect2info>

        <authorgroup>

          <author>

            <firstname>John</firstname>

            <surname>Lind</surname>

            <contrib>Contributed by </contrib>

          </author>

        </authorgroup>

      </sect2info>

      <title>Problems Integrating with Other Systems</title>

      <para>Certain Ethernet adapters for ISA PC systems have limitations

	which can lead to serious network problems, particularly with NFS.

	This difficulty is not specific to FreeBSD, but FreeBSD systems

	are affected by it.</para>

      <para>The problem nearly always occurs when (FreeBSD) PC systems are

	networked with high-performance workstations, such as those made

	by Silicon Graphics, Inc., and Sun Microsystems, Inc.  The NFS

	mount will work fine, and some operations may succeed, but

	suddenly the server will seem to become unresponsive to the

	client, even though requests to and from other systems continue to

	be processed.  This happens to the client system, whether the

	client is the FreeBSD system or the workstation.  On many systems,

	there is no way to shut down the client gracefully once this

	problem has manifested itself.  The only solution is often to

	reset the client, because the NFS situation cannot be

	resolved.</para>

      <para>Though the <quote>correct</quote> solution is to get a higher

	performance and capacity Ethernet adapter for the FreeBSD system,

	there is a simple workaround that will allow satisfactory

	operation.  If the FreeBSD system is the

	<emphasis>server</emphasis>, include the option

	<option>-w=1024</option> on the mount from the client.  If the

	FreeBSD system is the <emphasis>client</emphasis>, then mount the

	NFS filesystem with the option <option>-r=1024</option>.  These

	options may be specified using the fourth field of the

	<filename>fstab</filename> entry on the client for automatic

	mounts, or by using the <option>-o</option> parameter of the mount

	command for manual mounts.</para>

      <para>It should be noted that there is a different problem,

	sometimes mistaken for this one, when the NFS servers and clients

	are on different networks.  If that is the case, make

	<emphasis>certain</emphasis> that your routers are routing the

	necessary UDP information, or you will not get anywhere, no matter

	what else you are doing.</para>

      <para>In the following examples, <hostid>fastws</hostid> is the host

	(interface) name of a high-performance workstation, and

	<hostid>freebox</hostid> is the host (interface) name of a FreeBSD

	system with a lower-performance Ethernet adapter.  Also,

	<filename>/sharedfs</filename> will be the exported NFS

	filesystem (see &man.exports.5;), and

	<filename>/project</filename> will be the mount point on the

	client for the exported filesystem.  In all cases, note that

	additional options, such as <option>hard</option> or

	<option>soft</option> and <option>bg</option> may be desirable in

	your application.</para>

      <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as

	the client in <filename>/etc/fstab</filename> on freebox:</para>

      <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>

      <para>As a manual mount command on <hostid>freebox</hostid>:</para>

      <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>

      <para>Examples for the FreeBSD system as the server in

	<filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para>

      <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>

      <para>As a manual mount command on <hostid>fastws</hostid>:</para>

      <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>

      <para>Nearly any 16-bit Ethernet adapter will allow operation

	without the above restrictions on the read or write size.</para>

      <para>For anyone who cares, here is what happens when the failure

	occurs, which also explains why it is unrecoverable.  NFS

	typically works with a <quote>block</quote> size of 8&nbsp;k (though it

	may do fragments of smaller sizes).  Since the maximum Ethernet

	packet is around 1500&nbsp;bytes, the NFS <quote>block</quote> gets

	split into multiple Ethernet packets, even though it is still a

	single unit to the upper-level code, and must be received,

	assembled, and <emphasis>acknowledged</emphasis> as a unit.  The

	high-performance workstations can pump out the packets which

	comprise the NFS unit one right after the other, just as close

	together as the standard allows.  On the smaller, lower capacity

	cards, the later packets overrun the earlier packets of the same

	unit before they can be transferred to the host and the unit as a

	whole cannot be reconstructed or acknowledged.  As a result, the

	workstation will time out and try again, but it will try again

	with the entire 8 K unit, and the process will be repeated, ad

	infinitum.</para>

      <para>By keeping the unit size below the Ethernet packet size

	limitation, we ensure that any complete Ethernet packet received

	can be acknowledged individually, avoiding the deadlock

	situation.</para>

      <para>Overruns may still occur when a high-performance workstations

	is slamming data out to a PC system, but with the better cards,

	such overruns are not guaranteed on NFS <quote>units</quote>.  When

	an overrun occurs, the units affected will be retransmitted, and

	there will be a fair chance that they will be received, assembled,

	and acknowledged.</para>

    </sect2>

  </sect1>

  <sect1 id="network-diskless">

    <sect1info>

      <authorgroup>

        <author>

          <firstname>Jean-Fran&ccedil;ois</firstname>

          <surname>Dock&egrave;s</surname>

          <contrib>Updated by </contrib>

        </author>

      </authorgroup>

    </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 filesystems mounted from an NFS server.  No system

      modification is necessary, beyond standard configuration files.

      Such a system is 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><emphasis>PXE</emphasis>: Intel's 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><emphasis>The <application>etherboot</application>

	      port</emphasis> (<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 filesystem

	  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 NFS 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 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>root</filename> filesystem, and a shared

	  read-only <filename>/usr</filename>.</para>

	<para>The <filename>root</filename> filesystem 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 <filename>root</filename> which have to be

	  writable are overlaid with &man.mfs.8; filesystems.  Any changes

	  will be lost when the system reboots.</para>

      </listitem>

      <listitem>

	<para>The kernel is loaded by <application>etherboot

	  </application>, using DHCP (or BOOTP) and TFTP.</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>

    <sect2>

      <title>Setup Instructions</title>

      <sect3>

	<title>Configuring DHCP/BOOTP</title>

	<indexterm>

	  <primary>diskless operation</primary>

	  <secondary>booting</secondary>

	</indexterm>

	<para>There are two protocols that are commonly used to boot a

	  workstation that retrieves its configuration over the network: BOOTP

	  and DHCP.  They are used at several points in the workstation

	  bootstrap:</para>

	<itemizedlist>

	  <listitem><para><application>etherboot</application> uses

	      DHCP (by default) or BOOTP (needs a configuration option) to

	      find the kernel.  (PXE uses DHCP).</para>

	  </listitem>

	  <listitem><para>The kernel uses BOOTP to locate the NFS

	      root.</para>

	  </listitem>

	</itemizedlist>

	<para>It is possible to configure a system to use only BOOTP.

	  The &man.bootpd.8; server program is included in the

	  base FreeBSD system.</para>

	<para>However, DHCP has a number of advantages over BOOTP (nicer

	  configuration files, possibility of using PXE, plus many others

	  not directly related to diskless operation), and we shall describe

	  both a pure BOOTP, and a BOOTP+DHCP configuration, with an

	  emphasis on the latter, which will use the ISC DHCP software

	  package.</para>

	<sect4>

	  <title>Configuration Using ISC DHCP</title>

	  <indexterm>

	    <primary>DHCP</primary>

	    <secondary>diskless operation</secondary>

	  </indexterm>

	  <para>The <application>isc-dhcp</application> server can answer

	    both BOOTP and DHCP requests.</para>

	  <para>As of release 4.4, <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</filename> port or the

	    corresponding package.  Please refer to <xref linkend="ports">

	    for general information about ports and packages.</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:</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 "/tftpboot/kernel.diskless";<co id="co-dhcp-filename">

              option root-path "192.168.4.4:/data/misc/diskless";<co id="co-dhcp-root-path">

            }

          }

          </programlisting>

	  <calloutlist>

	    <callout arearefs="co-dhcp-host-name"><para>This option tells

		<command>dhcpd</command> 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

		host declarations.</para>

	    </callout>

	    <callout arearefs="co-dhcp-next-server"><para>The

		<literal>next-server</literal> directive designates

		the TFTP server (the default is to use the same host as the

		DHCP server).</para>

	    </callout>

	    <callout arearefs="co-dhcp-filename"><para>The

		<literal>filename</literal> directive defines the file that

		<application>etherboot</application> will load as a

		kernel.

		<note><para>PXE appears to prefer a relative file

		    name, and it loads <command>pxeboot</command>, not the

		    kernel (<literal>option filename

		      "pxeboot"</literal>).</para>

		</note>

	      </para>

	    </callout>

	    <callout arearefs="co-dhcp-root-path"><para>The

		<literal>root-path</literal> option defines the path to

		the root filesystem, in usual NFS notation.</para>

	    </callout>

	  </calloutlist>

	</sect4>

	<sect4>

	  <title>Configuration Using BOOTP</title>

	  <indexterm>

	    <primary>BOOTP</primary>

	    <secondary>diskless operation</secondary>

	  </indexterm>

	  <para>Here follows an equivalent <command>bootpd</command>

	    configuration.  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 PXE <emphasis>needs</emphasis> DHCP.  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>

	</sect4>

      </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.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.

	  The <application>etherboot</application> port can normally

	  be found in <filename>/usr/ports/net/etherboot</filename>.

	  If the ports tree is installed on your system, just typing

	  <literal>make</literal> in this directory should take care

	  of everything.  Else refer to <xref linkend="ports"> for

	  information about ports and packages.</para>

	<para>For our setup, we shall use a boot floppy.  For other methods

	  (PROM, or 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>Configuring the TFTP and NFS Servers</title>

	<indexterm>

	  <primary>TFTP</primary>

	  <secondary>diskless operation</secondary>

	</indexterm>

	<indexterm>

	  <primary>NFS</primary>

	  <secondary>diskless operation</secondary>

	</indexterm>

	<para>You need to enable <command>tftpd</command> on the TFTP

	  server:</para>

        <procedure>

          <step>

            <para>Create a directory from which <command>tftpd</command>

            will serve the files, i.e.: <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 -s /tftpboot</programlisting>

	    <note><para>It appears that at least some PXE versions want

		the TCP version of TFTP.  In this case, add a second line,

		replacing <literal>dgram udp</literal> with <literal>stream

		tcp</literal>.</para>

	    </note>

          </step>

	  <step>

	    <para>Tell <command>inetd</command> to reread its configuration