path: root/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml

<!--
     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.24 2000/05/02 22:40:41 unfurl Exp $
-->

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

  <sect1>
    <title>Synopsis</title>

    <para>The following chapter will cover some of the more frequently
      used network services on UNIX systems.  This, of course, will
      pertain to configuring said services on your FreeBSD system.</para>
  </sect1>

  <sect1 id="routing">
    <title>Gateways and Routes</title>
    
    <para><emphasis>Contributed by &a.gryphon;. 6 October
	1995.</emphasis></para>

    <para>For one machine to be able to find another, there must be a
      mechanism in place to describe how to get from one to the other. This is
      called Routing.  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>, send along 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.</para>

    <sect2>
      <title>An example</title>
      
      <para>To illustrate different aspects of routing, we will use the
	following example which is the output of the command <command>netstat
	  -r</command>:</para>
	  
      <screen>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 
foobar.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.foobar.com link#1             UC          0        0
224              link#1             UC          0        0</screen>
	  
      <para>The first two lines specify the default route (which we will cover
	in the next section) and the <hostid>localhost</hostid> route.</para>
	  
      <para>The interface (<literal>Netif</literal> column) that it 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 anyway.</para>
      
      <para>The next thing that stands out are the <hostid
	  role="mac">0:e0:...</hostid> addresses.  These are ethernet hardware
	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.  In this case the route 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>
	  
      <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">foobar.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
	<command>routed</command>.  If this is not run, then only routes which
	are statically defined (ie. 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 ifconfig alias (see the section of 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 is 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.</para>
	  
      <para>The final line (destination subnet <literal>224</literal>) deals
	with MultiCasting, which will be covered in a another section.</para>
	  
      <para>The other column that we should talk about are the
	<literal>Flags</literal>.  Each route has different attributes that
	are described in the 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>
      <title>Default routes</title>
      
      <para>When the local system needs to make a connection to 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, or your
	hardware device attached to a dedicated data line).</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]  &lt;--ether--&gt;  [Local1]  &lt;--PPP--&gt; [ISP-Serv]  &lt;--ether--&gt;  [T1-GW]
      </literallayout>
	  
      <para>The hosts <hostid>Local1</hostid> and <hostid>Local2</hostid> are
	at your site, with the formed being your PPP connection to your ISP's
	Terminal Server.  Your ISP has a local network at their site, which
	has, among other things, the server where you connect and a hardware
	device (T1-GW) attached to the ISP's 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 T1-GW to
	be the default gateway for Local1, 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 T1-GW 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">...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>
	  
      <literallayout>
Local2 (10.20.30.2)             --&gt;  Local1 (10.20.30.1)
Local1 (10.20.30.1, 10.9.9.30)  --&gt;  T1-GW (10.9.9.1)
      </literallayout>
    </sect2>
    
    <sect2>
      <title>Dual homed hosts</title>
      
      <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 as two ethernet cards, each having an
	address on the separate subnets.  Alternately, the machine may only
	have one ethernet card, and be using ifconfig 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 Bridge
	between the two subnets, is often used when we need to implement
	packet filtering or firewall security in either or both
	directions.</para>
    </sect2>
    
    <sect2>
      <title>Routing propagation</title>
      
      <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>
      
      <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 a 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>
  </sect1>
  
  <sect1 id="nfs">
    <title>NFS</title>

    <para><emphasis>Written by &a.unfurl;, 4 March 2000.</emphasis></para>

    <para>Among the many different file systems that FreeBSD supports is
      a very unique type, the Network File System or NFS.  NFS allows you
      to share directories and files on one machine with one or more other
      machines via the network they are attached to.  Using NFS, users and
      programs can access files on remote systems as if they were local
      files.</para>

    <para>NFS has several benefits:</para>

    <itemizedlist>
      <listitem>
	<para>Local workstations dont need as much disk space because
	  commonly used data can be stored on a single machine and still
	  remain accessible to everyone on the network.</para>
      </listitem>

      <listitem>
	<para>There is no need for users to have unique home directories
	  on every machine on your network.  Once they have an established
	  directory that is available via NFS it can be accessed from
	  anywhere.</para>
      </listitem>

      <listitem>
	<para>Storage devices such as floppies and CD-ROM drives can be
	  used by other machines on the network eliminating the need for
	  extra hardware.</para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>How It Works</title>

      <para> NFS is composed of two sides &ndash; a client side and a
	server side.  Think of it as a want/have relationship.  The client
	<emphasis>wants</emphasis> the data that the server side
	<emphasis>has</emphasis>.  The server shares its data with the
	client.  In order for this system to function properly a few
	processes have to be configured and running properly.</para>

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

      <itemizedlist>
        <listitem>
	  <para><command>nfsd</command> - The NFS Daemon which services
	    requests from NFS clients.</para>
	</listitem>

        <listitem>
	  <para><command>mountd</command> - The NFS Mount Daemon which
	    actually carries  out requests that nfsd passes on to
	    it.</para>
	</listitem>
      </itemizedlist>

      <para>The client side only needs to run a single daemon:</para>

      <itemizedlist>
        <listitem>
	  <para><command>nfsiod</command> - The NFS async I/O Daemon which
	    services requests from its NFS server.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Configuring NFS</title>

      <para>Luckily for us, on a FreeBSD system this setup is a snap.  The
	processes that need to be running can all be run at boot time with
	a few modificationss to your <filename>/etc/rc.conf</filename>
	file.</para>

      <para>On the NFS server make sure you have:</para>

      <programlisting>
nfs_server_enable="YES"
nfs_server_flags="-u -t -n 4"
mountd_flags="-r"</programlisting>

      <para><command>mountd</command> is automatically run whenever the
	NFS server is enabled.  The <option>-u</option> and
	<option>-t</option> flags to <command>nfsd</command> tell it to
	serve UDP and TCP clients.  The <option>-n 4</option> flag tells
	<command>nfsd</command> to start 4 copies of itself.</para>

      <para>On the client, make sure you have:</para>

      <programlisting>
nfs_client_enable="YES"
nfs_client_flags="-n 4"</programlisting>

      <para>Like <command>nfsd</command>, the <option>-n 4</option> tells
	<command>nfsiod</command> to start 4 copies of itself.</para>

      <para>The last configuration step requires that you create a file
	called <filename>/etc/exports</filename>.  The exports file
	specifies which file systems on your server will be shared
	(a.k.a., <quote>exported</quote>) and with what clients they will
	be shared.  Each line in the file specifies a file system to be
	shared.  There are a handful of options that can be used in this
	file but I will only touch on a few of them.  You can find out
	about the rest in the &man.exports.5; man page.</para>

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

      <para>The following line exports <filename>/cdrom</filename> to
	three silly 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 shared file system read-only.  With this flag, the
	remote system will not be able to make any changes to the the
	shared file system.</para>

      <programlisting>/cdrom -ro moe larry curly</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 but do not have DNS running.  The
	<option>-alldirs</option> flag allows all the directories below
	the specified file system to be exported as well.</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> to two
	machines that have different domain names than the server.  The
	<option>-maproot=0</option> flag allows
        the root user on the remote system to write to the shared
        file system as root.  Without the -maproot=0 flag even if
        someone has root access on the remote system they won't
        be able to modify files on the shared file system.</para>

      <programlisting>/a  -maproot=0  host.domain.com box.example.com</programlisting>

      <para>In order for a client to share an exported file system it must
	have permission to do so.  Make sure your client is listed in your
	<filename>/etc/exports</filename> file.</para>

      <para>Now that you have made all these changes you can just reboot
	and let FreeBSD start everything for you at boot time or you can
	run the following commands as root:</para>

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

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

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

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

      <para>Now you should be ready to actually mount a remote file
	system.  This can be done one of two ways.  In these examples the
	server's name will be <literal>server</literal> and the client's
	name will be <literal>client</literal>.  If you just want to
	temporarily mount a remote file system or just want to test out
	your config you can run a command like this as root on the
	client:</para>

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

      <para>This will mount <filename>/home</filename> on the server on
	<filename>/mnt</filename> on the client.  If everything is setup
	correctly you should be able to go into /mnt on the client and see
	all the files that are on the server.</para>

      <para>If you want to permanently (each time you reboot) mount a
	remote file system you need to add it to your
	<filename>/etc/fstab</filename> file.  Here is an example
	line:</para>

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

      <para>Read the &man.fstab.5; man page for more options.</para>
    </sect2>

    <sect2>
      <title>Practical Uses</title>

      <para>There are many very cool uses for NFS.  I use it quite a bit
	on the LAN I admin.  Here are a few ways I have found it to be
	useful.</para>

      <para>I have several machines on my network but only one of them has
	a CD-ROM drive.  Why?  Because I have that one CD-ROM drive shared
	with all the others via NFS.  The same can be done with floppy
	drives.</para>

      <para>With so many machines on the network it gets old having your
	personal files strewn all over the place.  I have a central NFS
	server that houses all user home directories and shares them with
	the rest of the machines on the LAN, so no matter where I login I
	have the same home directory.</para>

      <para>When you get to reinstalling FreeBSD on one of your machines,
	NFS is the way to go.  Just pop your distribution CD into your
	file server and away you go.</para>

      <para>I have a common <filename>/usr/ports/distfiles</filename>
	directory that all my machines share.  That way when I go to
	install a port that I already installed on a different machine I
	do not have to download the source all over again.</para>
    </sect2>

    <sect2>
      <title>Problems integrating with other systems</title>

      <para><emphasis>Contributed by &a.jlind;.</emphasis></para>

      <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 file system 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 <command>man exports</command>), and
	<filename>/project</filename> will be the mount point on the
	client for the exported file system.  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 8k (though it
	may do fragments of smaller sizes).  Since the maximum Ethernet
	packet is around 1500 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 8K 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="diskless">
    <title>Diskless Operation</title>
    
    <para><emphasis>Contributed by &a.martin;.</emphasis></para>
    
    <para><filename>netboot.com</filename>/<filename>netboot.rom</filename>
      allow you to boot your FreeBSD machine over the network and run FreeBSD
      without having a disk on your client.  Under 2.0 it is now possible to
      have local swap.  Swapping over NFS is also still supported.</para>

    <para>Supported Ethernet cards include: Western Digital/SMC 8003, 8013,
      8216 and compatibles; NE1000/NE2000 and compatibles (requires
      recompile)</para>
    
    <sect2>
      <title>Setup Instructions</title>
      
      <procedure>
	<step>
	  <para>Find a machine that will be your server.  This machine will
	    require enough disk space to hold the FreeBSD 2.0 binaries and
	    have bootp, tftp and NFS services available. Tested
	    machines:</para>
	      
	  <itemizedlist>
	    <listitem>
	      <para>HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
		work)</para>
	    </listitem>
	    
	    <listitem>
	      <para>Sun/Solaris 2.3.  (you may need to get bootp)</para>
	    </listitem>
	  </itemizedlist>
	</step>

	<step>
	  <para>Set up a bootp server to provide the client with IP, gateway,
	    netmask.</para>
	  
	  <programlisting>
diskless:\
        :ht=ether:\
        :ha=0000c01f848a:\
        :sm=255.255.255.0:\
        :hn:\
        :ds=192.1.2.3:\
        :ip=192.1.2.4:\
        :gw=192.1.2.5:\
        :vm=rfc1048:</programlisting>
	</step>

	<step>
	  <para>Set up a TFTP server (on same machine as bootp server) to
	    provide booting information to client.  The name of this file is
	    <filename>cfg.<replaceable>X.X.X.X</replaceable></filename> (or
	    <filename>/tftpboot/cfg.<replaceable>X.X.X.X</replaceable></filename>,
	    it will try both) where <replaceable>X.X.X.X</replaceable> is the
	    IP address of the client.  The contents of this file can be any
	    valid netboot commands.  Under 2.0, netboot has the following
	    commands:</para>

	  <informaltable frame="none">
	    <tgroup cols="2">
	      <tbody>
		<row>
		  <entry>help</entry>
		  <entry>print help list</entry>
		</row>
		
		<row>
		  <entry>ip
		    <option><replaceable>X.X.X.X</replaceable></option></entry>
		  <entry>print/set client's IP address</entry>
		</row>
		
		<row>
		  <entry>server
		    <option><replaceable>X.X.X.X</replaceable></option></entry>
		  <entry>print/set bootp/tftp server address</entry>
		</row>
		
		<row>
		  <entry>netmask
		    <option><replaceable>X.X.X.X</replaceable></option></entry>
		  <entry>print/set netmask</entry>
		</row>

		<row>
		  <entry>hostname <replaceable>name</replaceable></entry>
		  <entry>print/set hostname</entry>
		    </row>
		
		<row>
		  <entry>kernel
		    <option><replaceable>name</replaceable></option></entry>
		  <entry>print/set kernel name</entry>
		</row>
		
		<row>
		  <entry>rootfs
		    <option><replaceable>ip:/fs</replaceable></option></entry>
		  <entry>print/set root filesystem</entry>
		</row>
		
		<row>
		  <entry>swapfs
		    <option><replaceable>ip:/fs</replaceable></option></entry>
		  <entry>print/set swap filesystem</entry>
		</row>
		
		<row>
		  <entry>swapsize
		    <option><replaceable>size</replaceable></option></entry>
		  <entry>set diskless swapsize in Kbytes</entry>
		</row>
		
		<row>
		  <entry>diskboot</entry>
		  <entry>boot from disk</entry>
		</row>
		
		<row>
		  <entry>autoboot</entry>
		  <entry>continue boot process</entry>
		</row>
		
		<row>
		  <entry>trans
		    <option>on</option>|<option>off</option></entry>
		  <entry>turn transceiver on|off</entry>
		</row>
		
		<row>
		  <entry>flags
		    <option>b</option><option>c</option><option>d</option><option>h</option><option>s</option><option>v</option></entry>
		  <entry>set boot flags</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </informaltable>
	  
	  <para>A typical completely diskless cfg file might contain:</para>

	  <programlisting>
rootfs 192.1.2.3:/rootfs/myclient
swapfs 192.1.2.3:/swapfs
swapsize 20000
hostname myclient.mydomain</programlisting>

	  <para>A cfg file for a machine with local swap might contain:</para>

	  <programlisting>
rootfs 192.1.2.3:/rootfs/myclient
hostname myclient.mydomain</programlisting>
	</step>

	<step>
	  <para>Ensure that your NFS server has exported the root (and swap if
	    applicable) filesystems to your client, and that the client has
	    root access to these filesystems A typical
	    <filename>/etc/exports</filename> file on FreeBSD might look
	    like:</para>
	  
	  <programlisting>
/rootfs/myclient -maproot=0:0 myclient.mydomain
/swapfs -maproot=0:0 myclient.mydomain</programlisting>

	  <para>And on HP-UX:</para>

	  <programlisting>
/rootfs/myclient -root=myclient.mydomain
/swapfs -root=myclient.mydomain</programlisting>
	</step>
	      
	<step>
	  <para>If you are swapping over NFS (completely diskless
	    configuration) create a swap file for your client using
	    <command>dd</command>.  If your <command>swapfs</command> command
	    has the arguments <filename>/swapfs</filename> and the size 20000
	    as in the example above, the swapfile for myclient will be called
	    <filename>/swapfs/swap.<replaceable>X.X.X.X</replaceable></filename>
	    where <replaceable>X.X.X.X</replaceable> is the client's IP addr,
	    eg:</para>
		  
	  <screen>&prompt.root; <userinput>dd if=/dev/zero of=/swapfs/swap.192.1.2.4 bs=1k count=20000</userinput></screen>
		  
	  <para>Also, the client's swap space might contain sensitive
	    information once swapping starts, so make sure to restrict read
	    and write access to this file to prevent unauthorized
	    access:</para>
		  
	  <screen>&prompt.root; <userinput>chmod 0600 /swapfs/swap.192.1.2.4</userinput></screen>
	</step>

	<step>
	  <para>Unpack the root filesystem in the directory the client will
	    use for its root filesystem (<filename>/rootfs/myclient</filename>
	    in the example above).</para>
	  
	  <itemizedlist>
	    <listitem>
	      <para>On HP-UX systems: The server should be running HP-UX 9.04
		or later for HP9000/800 series machines. Prior versions do not
		allow the creation of device files over NFS.</para>
	    </listitem>
	    
	    <listitem>
	      <para>When extracting <filename>/dev</filename> in
		<filename>/rootfs/myclient</filename>, beware that some
		systems (HPUX) will not create device files that FreeBSD is
		happy with.  You may have to go to single user mode on the
		first bootup (press control-c during the bootup phase), cd
		<filename>/dev</filename> and do a <command>sh ./MAKEDEV
		  all</command> from the client to fix this.</para>
	    </listitem>
	  </itemizedlist>
	</step>

	<step>
	  <para>Run <command>netboot.com</command> on the client or make an
	    EPROM from the <filename>netboot.rom</filename> file</para>
	</step>
      </procedure>
    </sect2>
    
    <sect2>
      <title>Using Shared <filename>/</filename> and <filename>/usr</filename>
	filesystems</title>
	  
      <para>At present there isn't an officially sanctioned way of doing this,
	although I have been using a shared <filename>/usr</filename>
	filesystem and individual <filename>/</filename> filesystems for each
	client.  If anyone has any suggestions on how to do this cleanly,
	please let me and/or the &a.core; know.</para>
    </sect2>
    
    <sect2>
      <title>Compiling netboot for specific setups</title>
      
      <para>Netboot can be compiled to support NE1000/2000 cards by changing
	the configuration in
	<filename>/sys/i386/boot/netboot/Makefile</filename>.  See the
	comments at the top of this file.</para>
    </sect2>
  </sect1>
  
  <sect1 id="isdn">
    <title>ISDN</title>
    
    <para><emphasis>Last modified by &a.wlloyd;</emphasis>.</para>
    
    <para>A good resource for information on ISDN technology and hardware is
      <ulink url="http://alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN
	Page</ulink>.</para>

    <para>A quick simple roadmap to ISDN follows:</para>
    
    <itemizedlist>
      <listitem>
	<para>If you live in Europe I suggest you 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 dialup non-dedicated basis,
	  I suggest you 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, I suggest you 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>
      <title>ISDN Cards</title>
      
      <para><emphasis>Contributed by &a.hm;.</emphasis></para>
      
      <para>This section is really only relevant to ISDN users in countries
	where the DSS1/Q.931 ISDN standard is supported.</para>
  
      <para>Some growing number of PC ISDN cards are supported under FreeBSD
	2.2.x and up by the isdn4bsd driver package.  It is still under
	development but the reports show that it is successfully used all over
	Europe.</para>

      <para>The latest isdn4bsd version is available from  <ulink
	  url="ftp://isdn4bsd@ftp.consol.de/pub/">ftp://isdn4bsd@ftp.consol.de/pub/</ulink>,
	the main isdn4bsd ftp site (you have to log in as user
	<username>isdn4bsd</username> , give your mail address as the password
	and change to the <filename>pub</filename> directory.  Anonymous ftp
	as user <username>ftp</username> or <username>anonymous</username>
	will <emphasis>not</emphasis> give the desired result).</para>

      <para>Isdn4bsd allows you to connect to other ISDN routers using either
	IP over raw HDLC or by using synchronous PPP.  A telephone answering
	machine application is also available.</para>

      <para>Many ISDN PC cards are supported, mostly the ones with a Siemens
	ISDN chipset (ISAC/HSCX), support for other chipsets (from Motorola,
	Cologne Chip Designs) is currently under development.  For an
	up-to-date list of supported cards, please have a look at the <ulink
	  url="ftp://isdn4bsd@ftp.consol.de/pub/README">README</ulink>
	file.</para>

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

      <para>A majordomo maintained mailing list is available.  To join the
	list, send mail to &a.majordomo; and
	specify:</para>
      
      <programlisting>
subscribe freebsd-isdn</programlisting>

      <para>in the body of your message.</para>
    </sect2>
    
    <sect2>
      <title>ISDN Terminal Adapters</title>
      
      <para>Terminal adapters(TA), are to ISDN what modems are to regular
	phone lines.</para>
      
      <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>
	  
      <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 standalone 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 setup.  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 user-land <link
	  linkend="userppp">iijPPP</link>.</para>
	  
      <para>The following TA's are know 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 like modems you need a good
	serial card in your computer.</para>
	  
      <para>You should read the <link linkend="uart">serial ports</link>
	section in the handbook 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.2Kbs, even though you have a 128Kbs connection. To fully
	utilize the 128Kbs 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 standalone
	router, and with a simple 386 FreeBSD box driving it, probably more
	flexible.</para>
	  
      <para>The choice of sync/TA vs standalone router is largely a religious
	issue.  There has been some discussion of this in the mailing lists.
	I suggest you search the <ulink
	  url="http://www.FreeBSD.org/search.html">archives</ulink> for the
	complete discussion.</para>
    </sect2>
    
    <sect2>
      <title>Standalone ISDN Bridges/Routers</title>
      
      <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 page, I will use router and bridge
	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(or
	card), and manages its own connection to the other bridge/router.  It
	has all the software to do PPP and other protocols built in.</para>
	  
      <para>A router will allow you much faster throughput that 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, I recommend that you
	discuss your needs with them.</para>
	  
      <para>If you are planning to connect two lan segments together, ie: 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>

	<para>Network is 10 Base T Ethernet.  Connect router to network cable
	  with AUI/10BT transceiver, if necessary.</para>

	<!-- This should be a graphic -->
	<programlisting>
---Sun workstation     
|
---FreeBSD box
|
---Windows 95 (Do not admit to owning it)
|
Standalone router
   |
ISDN BRI line</programlisting>

	<para>If your home/branch office is only one computer you can use a
	  twisted pair crossover cable to connect to the standalone router
	  directly.</para>
      </example>
      
      <example>
	<title>Head office or other lan</title>

	<para>Network is Twisted Pair Ethernet.</para>

	<!-- This should be a graphic -->
	<programlisting>
    -------Novell Server
    | H |
    |   ---Sun      
    |   |
    | U ---FreeBSD
    |   |
    |   ---Windows 95
    | B |
    |___---Standalone router
                |
        ISDN BRI line</programlisting>
      </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(expensive) models that
	have two serial ports. Do not confuse this with channel bonding, MPP
	etc.</para>
	  
      <para>This can be very useful feature, for example if you have an
	dedicated internet ISDN connection at your office and would like to
	tap into it, but don't want to get another ISDN line at work. A router
	at the office location can manage a dedicated B channel connection
	(64Kbs) to the internet, as well as a use the other B channel for a
	separate data connection.  The second B channel can be used for
	dialin, dialout or dynamically bond(MPP etc.) with the first B channel
	for more bandwidth.</para>
	  
      <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="nis">
    <title>NIS/YP</title>

    <para><emphasis>Written by &a.unfurl;, 21 January 2000.</emphasis></para>

    <sect2>
      <title>What is it?</title>
  
      <para> NIS is an RPC-based client/server system that allows a group
	of machines within an NIS domain to share a common set of
	configuration files.  This permits a system administrator to set
	up NIS client systems with only minimal configuration data and
	add, remove or modify configuration data from a single
	location.</para>
    </sect2>
  
    <sect2>
      <title>How does it work?</title>
        
      <para>There are 3 types of hosts in an NIS enviornment; master
	servers, slave servers, and clients.  Servers act as a central
	repository for host configuration information.  Master servers
	hold the authoritatve copy of this information, while slave
	servers mirror this information for redundancy.  Clients rely on
	the servers to provide this information to them.</para>

      <para>Information in many files can be shared in this manner.  The
	<filename>master.passwd</filename>, <filename>group</filename>,
	and <filename>hosts</filename> files are commonly shared via NIS.
	Whenever a process on a client needs information that would
	normally be found in these files locally, it makes a query to the
	server it is bound to, to get this information.</para>
    </sect2>
    
    <sect2>
      <title>Using NIS/YP</title>
  
      <sect3>
        <title>Planning</title>
  
        <para>If you are setting up a NIS scheme for the first time, it
	  is a good idea to think through how you want to go about it.  No
	  matter what the size of your network, there are a few decisions
	  that need to be made.</para>
  
        <sect4>
          <title>Choosing a NIS Domain Name</title>
  
          <para>This might not be the <quote>domainname</quote> that you
	    are used to.  It is more accurately called the
	    <quote>NIS domainname</quote>.  When a client broadcasts its
	    requests for info, it includes the name of the NIS domain
	    that it is part of.  This is how multiple servers on one
	    network can tell which server should answer which request.
	    Think of the NIS domainname as the name for a group of hosts
	    that are related in someway way.</para>
  
	  <para>Some organizations choose to use their Internet domainname
	    for their NIS domainname. This is not recommended as it can
	    cause confusion when trying to debug network problems.  The
	    NIS domainname should be unique within your network and it is
	    helpful if it describes the group of machines it represents.
	    For example, the Art department at Acme Inc. might be in the
	    "acme-art" NIS domain.</para>
        </sect4>
  
        <sect4>
          <title>Physical Server Requirements</title>
            
	  <para>There are several things to keep in mind when chosing a
	    machine to use as a NIS server.  One of the unfortunate things
	    about NIS is the level of dependency the clients have on the
	    server.  If a client cannot contact the server for its NIS
	    domain, very often the machine becomes unusable.  The lack of
	    user and group information causes most systems to temporarily
	    freeze up.  With this in mind you should make sure to choose a
	    machine that won't be prone to being rebooted regularly, or
	    one that might be used for development.  The NIS server should
	    ideally be a stand alone machine whose sole purpose in life is
	    to be an NIS server.  If you have a network that is not very
	    heavily used, it is acceptable to put the NIS server on a
	    machine running other services, just keep in mind that if the
	    NIS server becomes unavailable, it will affect
	    <emphasis>all</emphasis> of your NIS clients adversely.</para>
        </sect4>
      </sect3>

      <sect3>
        <title>NIS Servers</title>

	<para> The canonical copies of all NIS information are stored on
	  a single machine called the NIS master server.  The databases
	  used to store the information are called NIS maps.  In FreeBSD,
	  these maps are stored in
	  <filename>/var/yp/[domainname]</filename> where
	  <filename>[domainname]</filename> is the name of the NIS domain
	  being served.  A single NIS server can support several domains
	  at once, therefore it is possible to have several such
	  directories, one for each supported domain.  Each domain will
	  have its own independent set of maps.</para>

	<para>NIS master and slave servers handle all NIS requests with
	  the <command>ypserv</command> daemon.  <command>Ypserv</command>
	  is responsible for receiving incoming requests from NIS clients,
	  translating the requested domain and map name to a path to the
	  corresponding database file and transmitting data from the
	  database back to the client.</para>

        <sect4>
	  <title>Setting up a NIS master server</title>

	  <para>Setting up a master NIS server can be relativly straight
	    forward, depending on your needs.  FreeBSD comes with a handy
	    script called <command>ypinit</command> that makes the initial
	    setup procedure very easy.  A few steps are needed ahead of
	    time to make the setup process go smoothly.</para>

	  <itemizedlist>
	    <listitem>
	      <para>Make sure your NIS domainname is set, using the
		<command>domainname</command> command.  You can run
		<command>ypinit</command> for domains other than the one
		your host is in but if <literal>domainname</literal> is
		not set, now is a good time to do so.</para>
	    </listitem>

	    <listitem>
	      <para>Make sure a copy of the
	        <filename>master.passwd</filename> file is in
		<filename>/var/yp</filename>.  This where NIS will get the
		password entries it will share with it's clients.
		<command>ypinit</command> runs with errors if this file is
		not present.  You can either start a new
		<filename>master.passwd</filename> or copy the existing
		one from <filename>/etc/master.passwd</filename>.  If you
		do the latter, make sure the permissions are set properly
		to disallow world/group reading of the file.</para>
	    </listitem>

	    <listitem>
	      <para>Start the <command>ypserv</command> daemon.
		<command>ypinit</command> requires
		<command>ypserv</command> to be running to answer some RPC
		calls it makes.  In its basic configuration
		<command>ypserv</command> does not need to be run with any
		flags.</para>
	    </listitem>
	  </itemizedlist>

	  <para>Once you've done the above steps, run
	    <command>ypinit</command> with the <option>-m</option> flag.
	    You might want to specify the domain you are building a master
	    server for if it is different than what the
	    <literal>domainname</literal> is set to.  In this example,
	    <filename>test-domain</filename> will be our NIS
	    domainname.</para>

	  <screen>
# ypinit -m test-domain
Server Type: MASTER Domain: test-domain

Creating an YP server will require that you answer a few questions.
Questions will all be asked at the beginning of the procedure.

Do you want this procedure to quit on non-fatal errors? [y/n: n]  n

Ok, please remember to go back and redo manually whatever fails.
If you don't, something might not work. 

At this point, we have to construct a list of this domains YP servers.
master.example.com is already known as master server.
Please continue to add any slave servers, one per line. When you are
done with the list, type a &lt;Control D&gt;.
        master server   :  master.example.com
        next host to add:  <userinput>^D</userinput>
The current list of NIS servers looks like this:

master.example.com

Is this correct?  [y/n: y]  <userinput>y</userinput>
Building /var/yp/test-domain/ypservers...
Running /var/yp/Makefile...
NIS Map update started on Fri Dec  3 16:54:12 PST 1999 for domain test-domain
Updating hosts.byname...
Creating new /var/yp/passwd file from /var/yp/master.passwd...
Updating netid.byname...
Updating hosts.byaddr...
Updating networks.byaddr...
Updating networks.byname...
Updating protocols.bynumber...
Updating protocols.byname...
Updating rpc.byname...
Updating rpc.bynumber...
Updating services.byname...
Updating group.byname...
Updating group.bygid...
Updating passwd.byname...
Updating passwd.byuid...
Updating master.passwd.byname...
Updating master.passwd.byuid...
NIS Map update completed.

master.example.com has been setup as an YP master server without any errors.</screen>

	  <para>There are a few crucial lines that need to be added to
	    your <filename>/etc/rc.conf</filename> in order for the NIS
	    server to start properly.  Make sure that these lines are
	    included:</para>

	  <programlisting>
nis_server_enable="YES"
nis_server_flags=""
nis_yppasswdd_enable="YES"
nis_yppasswdd_flags=""</programlisting>

	  <para>You will most likely want to run
	    <command>yppasswd</command> on the NIS server.  This allows
	    users on NIS client machines to change their passwords and
	    other user information remotely. </para>
	</sect4>

        <sect4>
	  <title>Setting up a NIS slave server</title>

	  <para>Setting up an NIS slave server is even more simple than
	    setting up the master. Again the <command>ypinit</command>
	    command helps out a great deal. As in the previous example
	    we'll use <quote>test-domain</quote> as our target NIS
	    domainname.</para>

	  <screen>
# ypinit -s master.example.com test-domain

Server Type: SLAVE Domain: test-domain Master: master.example.com

Creating an YP server will require that you answer a few questions.
Questions will all be asked at the beginning of the procedure.

Do you want this procedure to quit on non-fatal errors? [y/n: n]  <userinput>n</userinput>

Ok, please remember to go back and redo manually whatever fails.
If you don't, something might not work. 
There will be no further questions. The remainder of the procedure
should take a few minutes, to copy the databases from master.example.com.
Transfering netgroup...
ypxfr: Exiting: Map successfully transfered
Transfering netgroup.byuser...
ypxfr: Exiting: Map successfully transfered
Transfering netgroup.byhost...
ypxfr: Exiting: Map successfully transfered
Transfering master.passwd.byuid...
ypxfr: Exiting: Map successfully transfered
Transfering passwd.byuid...
ypxfr: Exiting: Map successfully transfered
Transfering passwd.byname...
ypxfr: Exiting: Map successfully transfered
Transfering group.bygid...
ypxfr: Exiting: Map successfully transfered
Transfering group.byname...
ypxfr: Exiting: Map successfully transfered
Transfering services.byname...
ypxfr: Exiting: Map successfully transfered
Transfering rpc.bynumber...
ypxfr: Exiting: Map successfully transfered
Transfering rpc.byname...
ypxfr: Exiting: Map successfully transfered
Transfering protocols.byname...
ypxfr: Exiting: Map successfully transfered
Transfering master.passwd.byname...
ypxfr: Exiting: Map successfully transfered
Transfering networks.byname...
ypxfr: Exiting: Map successfully transfered
Transfering networks.byaddr...
ypxfr: Exiting: Map successfully transfered
Transfering netid.byname...
ypxfr: Exiting: Map successfully transfered
Transfering hosts.byaddr...
ypxfr: Exiting: Map successfully transfered
Transfering protocols.bynumber...
ypxfr: Exiting: Map successfully transfered
Transfering ypservers...
ypxfr: Exiting: Map successfully transfered
Transfering hosts.byname...
ypxfr: Exiting: Map successfully transfered

slave.example.com has been setup as an YP slave server without any errors. 
Don't forget to update map ypservers on master.example.com.</screen>
        
	  <para>You should now have a directory called 
	    <filename>/var/yp/test-domain</filename>.  Copies of the NIS
	    master server's maps should be in this directory.  You will
	    need to make sure that these stay updated.  The following
	    <filename>/etc/crontab</filename> entries on your slave 
	    servers should do the job:</para>
        
	  <programlisting>
20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>

	  <para>These two lines force the slave to sync its maps with
	    the maps on the master server.  Although this is
	    not mandatory, because the master server
	    tries to make sure any changes to it's NIS maps are
	    communicated to it's slaves, the password
	    information is so vital to systems that depend on the server,
	    that it is a good idea to force the updates.  This is more
	    important on busy networks where map updates might not always
	    complete.</para>
	</sect4>
      </sect3>

      <sect3>
        <title>NIS Clients</title>
	
	<para> An NIS client establishes what is called a binding to a
	  particular NIS server using the
	  <application>ypbind</application> daemon.
	  <application>Ypbind</application> checks the system's default
	  domain (as set by the <command>domainname</command> command),
	  and begins broadcasting RPC requests on the local network.
	  These requests specify the name of the domain for which
	  <command>ypbind</command> is attempting to establish a binding.
	  If a server that has been configured to serve the requested
	  domain receives one of the broadcasts, it will respond to
	  <command>ypbind</command>,  which will record the server's
	  address.  If there are several servers available (a master and
	  several slaves, for example), <command>ypbind</command> will
	  use the address of the first one to respond.  From that point
	  on, the client system will direct all of its NIS requests to
	  that server.  <application>Ypbind</application> will
	  occasionally <quote>ping</quote> the server to make sure it is
	  still up and running.  If it fails to receive a reply to one of
	  its pings within a reasonable amount of time,
	  <command>ypbind</command> will mark the domain as unbound and
	  begin broadcasting again in the hopes of locating another
	  server.</para>

	<sect4>
	  <title>Setting up an NIS client</title>
	  
	  <para>Setting up a FreeBSD machine to be a NIS client is fairly
	    straight forward.</para>
	
	  <itemizedlist>
	    <listitem>
	      <para>Set the host's NIS domainname with the
		<command>domainname</command> command, or at boot time
		with this entry in
		<filename>/etc/rc.conf</filename>:</para>

	      <programlisting>nisdomainname="test-domain"</programlisting>
	    </listitem>

	    <listitem>
	      <para>To import all possible password entries from the NIS
		server, add this line to your
		<filename>/etc/master.passwd</filename> file, using
		<command>vipw</command>:</para>

	      <programlisting>+:::::::::</programlisting>

	      <note>
		<para>This line will afford anyone with a valid account in
		  the NIS server's password maps an account.  There are
		  many ways to configure your NIS client by changing this
		  line.  For more detailed reading see O'Reilly's book on
		  <literal>Managing NFS and NIS</literal>.</para>
	      </note>
	    </listitem>

	    <listitem>
	      <para>To import all possible group entries from the NIS
		server, add this line to your
		<filename>/etc/group</filename> file:</para>

	      <programlisting>+:*::</programlisting>
	    </listitem>
	  </itemizedlist>

	  <para>After completing these steps, you should be able to run
	    <command>ypcat passwd</command> and see the NIS server's
	    passwd map.</para>
	</sect4>
      </sect3>
    </sect2>

    <sect2>
      <title>NIS Security</title>

      <para>In general, any remote user can issue an RPC to ypserv and
	retrieve the contents of your NIS maps, provided the remote user
	knows your domainname.  To prevent such unauthorized transactions,
	ypserv supports a feature called securenets which can be used to
	restrict access to a given set of hosts.  At startup, ypserv will
	attempt to load the securenets information from a file called
	<filename>/var/yp/securenets</filename>.</para>
	
      <note>
	<para>This path varies depending on the path specified with the
	  <option>-p</option> option.  This file contains entries that
	  consist of a network specification and a network mask separated
	  by white space.  Lines starting with <quote>#</quote> are
	  considered to be comments.  A sample securenets file might look
	  like this:</para>
      </note>

      <programlisting>
# allow connections from local host -- mandatory
127.0.0.1     255.255.255.255
# allow connections from any host
# on the 192.168.128.0 network
192.168.128.0 255.255.255.0
# allow connections from any host
# between 10.0.0.0 to 10.0.15.255
10.0.0.0      255.255.240.0</programlisting>

      <para>If ypserv receives a request from an address that matches one
	of these rules, it will process the request normally.  If the
	address fails to match a rule, the request will be ignored and a
	warning message will be logged.  If the
	<filename>/var/yp/securenets</filename> file does not exist,
	ypserv will allow connections from any host.</para>

      <para>The ypserv program also has support for Wietse Venema's
	<application>tcpwrapper</application> package.  This allows the
	administrator to use the tcpwrapper configuration files for access
	control instead of <filename>/var/yp/securenets</filename>.</para>

      <note>
	<para>While both of these access control mechanisms provide some
	  security, they, like the privileged port test, are both
	  vulnerable to <quote>IP spoofing</quote> attacks.</para>
      </note>
    </sect2>

    <sect2>
      <title>NIS v1 compatibility</title>

      <para> FreeBSD's <application>ypserv</application> has some support
	for serving NIS v1 clients.  FreeBSD's NIS implementation only
	uses the NIS v2 protocol, however other implementations include
	support for the v1 protocol for backwards compatibility with older
	systems.  The <application>ypbind</application> daemons supplied
	with these systems will try to establish a binding to an NIS v1
	server even though they may never actually need it (and they may
	persist in broadcasting in search of one even after they receive a
	response from a v2 server).  Note that while support for normal
	client calls is provided, this version of ypserv does not handle
	v1 map transfer requests; consequently, it can not be used as a
	master or slave in conjunction with older NIS servers that only
	support the v1 protocol.  Fortunately, there probably are not any
	such servers still in use today.</para>
    </sect2>

    <sect2>
      <title>NIS servers that are also NIS clients</title>

      <para> Care must be taken when running ypserv in a multi-server
	domain where the server machines are also NIS clients.  It is
	generally a good idea to force the servers to bind to themselves
	rather than allowing them to broadcast bind requests and possibly
	become bound to each other.  Strange failure modes can result if
	one server goes down and others are dependent upon on it.
	Eventually all the clients will time out and attempt to bind to
	other servers, but the delay involved can be considerable and the
	failure mode is still present since the servers might bind to each
	other all over again.</para>

      <para>You can force a host to bind to a particular server by running
	<command>ypbind</command> with the <option>-S</option>
	flag.</para>
    </sect2>

    <sect2>
      <title>libscrypt vs. libdescrypt</title>

      <para>One of the most common issues that people run into when trying
	to implement NIS is crypt library compatibility.  If your NIS
	server is using the DES crypt libraries, it will only support
	clients that are using DES as well. To check which one your server
	and clients are using look at the symlinks in
	<filename>/usr/lib</filename>.  If the machine is configured to
	use the DES libraries, it will look something like this:</para>

      <screen>
&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libdescrypt.a
lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libdescrypt.so
lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libdescrypt.so.2
lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libdescrypt_p.a
-r--r--r--  1 root  wheel  13018 Nov  8 14:27 /usr/lib/libdescrypt.a
lrwxr-xr-x  1 root  wheel     16 Nov  8 14:27 /usr/lib/libdescrypt.so@ -> libdescrypt.so.2
-r--r--r--  1 root  wheel  12965 Nov  8 14:27 /usr/lib/libdescrypt.so.2
-r--r--r--  1 root  wheel  14750 Nov  8 14:27 /usr/lib/libdescrypt_p.a</screen>

      <para>If the machine is configured to use the standard FreeBSD MD5
	crypt libraries they will look somethine like this:</para>

      <screen>
&prompt.user; <userinput>ls -l /usr/lib/*crypt*</userinput>
lrwxrwxrwx  1 root  wheel     13 Jul 15 08:55 /usr/lib/libcrypt.a@ -> libscrypt.a
lrwxrwxrwx  1 root  wheel     14 Jul 15 08:55 /usr/lib/libcrypt.so@ -> libscrypt.so
lrwxrwxrwx  1 root  wheel     16 Jul 15 08:55 /usr/lib/libcrypt.so.2@ -> libscrypt.so.2
lrwxrwxrwx  1 root  wheel     15 Jul 15 08:55 /usr/lib/libcrypt_p.a@ -> libscrypt_p.a
-r--r--r--  1 root  wheel   6194 Nov  8 14:27 /usr/lib/libscrypt.a
lrwxr-xr-x  1 root  wheel     14 Nov  8 14:27 /usr/lib/libscrypt.so@ -> libscrypt.so.2
-r--r--r--  1 root  wheel   7579 Nov  8 14:27 /usr/lib/libscrypt.so.2
-r--r--r--  1 root  wheel   6684 Nov  8 14:27 /usr/lib/libscrypt_p.a</screen>
	
      <para>If you have trouble authenticating on an NIS client, this is a
	pretty good place to start looking for possible problems.</para>
    </sect2>
  </sect1>

  <sect1 id="dhcp">
    <title>DHCP</title>

    <para><emphasis>Written by &a.gsutter;, March 2000.</emphasis></para>

    <sect2>
      <title>What is DHCP?</title>

      <para>DHCP, the Dynamic Host Configuration Protocol, describes
        the means by which a system can connect to a network and obtain the
        necessary information for communication upon that network. FreeBSD
        uses the ISC (Internet Software Consortium) DHCP implementation, so
        all implementation-specific information here is for use with the ISC
        distribution.</para>
    </sect2>

    <sect2>
      <title>What This Section Covers</title>

      <para>This handbook section attempts to describe only the parts
        of the DHCP system that are integrated with FreeBSD; 
        consequently, the server portions are not described.  The DHCP
        manual pages, in addition to the references below, are useful
        resources.</para>
    </sect2>

    <sect2>
      <title>How it Works</title>

      <para>When dhclient, the DHCP client, is executed on the client
        machine, it begins broadcasting requests for configuration
        information. By default, these requests are on UDP port 68. The
        server replies on UDP 67, giving the client an IP address and
        other relevant network information such as netmask, router, and
        DNS servers. All of this information comes in the form of a DHCP
        "lease" and is only valid for a certain time (configured by the
        DHCP server maintainer). In this manner, stale IP addresses for
        clients no longer connected to the network can be automatically
        reclaimed.</para>

      <para>DHCP clients can obtain a great deal of information from 
        the server.  An exhaustive list may be found in
        &man.dhcp-options.5;.</para>
    </sect2>

    <sect2>
      <title>FreeBSD Integration</title>

      <para>FreeBSD fully integrates the ISC DHCP client,
        <command>dhclient</command>.  DHCP client support is provided 
        within both the installer and the base system, obviating the need
        for detailed knowledge of network configurations on any network 
        that runs a DHCP server.  <command>dhclient</command> has been
        included in all FreeBSD distributions since 3.2.</para>

        <para>DHCP is supported by <application>sysinstall</application>.
          When configuring a network interface within sysinstall, 
          the first question asked is, "Do you want to try dhcp
          configuration of this interface?"  Answering affirmatively will
          execute dhclient, and if successful, will fill in the network
          configuration information automatically.</para>

        <para>To have your system use DHCP to obtain network information
          upon startup, edit your <filename>/etc/rc.conf</filename> to
          include the following:</para>

        <programlisting>
ifconfig_fxp0="DHCP"
        </programlisting>

        <note>
          <para>Be sure to replace <literal>fxp0</literal> with the
          designation for the interface that you wish to dynamically 
          configure.</para>
        </note>

        <para>If you are using a different location for
          <command>dhclient</command>, or if you wish to pass additional
          flags to <command>dhclient</command>, also include the
          following (editing as necessary):</para>

        <programlisting>
dhcp_program="/sbin/dhclient"
dhcp_flags=""
        </programlisting>

        <para>The DHCP server, <command>dhcpd</command>, is included
          as part of the <literal>isc-dhcp2</literal> port in the ports
          collection.  This port contains the full ISC DHCP distribution,
          consisting of client, server, relay agent and documentation.
          </para>
    </sect2>

    <sect2>
      <title>Files</title>

      <itemizedlist>
        <listitem><para><filename>/etc/dhclient.conf</filename></para>
          <para><command>dhclient</command> requires a configuration file,
            <filename>/etc/dhclient.conf</filename>. Typically the file
            contains only comments, the defaults being reasonably sane. This
            configuration file is described by the &man.dhclient.conf.5;
            man page.</para>
        </listitem>

        <listitem><para><filename>/sbin/dhclient</filename></para>
          <para><command>dhclient</command> is statically linked and
            resides in <filename>/sbin</filename>.  The &man.dhclient.8;
            manual page gives more information about
            <command>dhclient</command>.</para>
        </listitem>

        <listitem><para><filename>/sbin/dhclient-script</filename></para>
          <para><command>dhclient-script</command> is the FreeBSD-specific
            DHCP client configuration script.  It is described in
            &man.dhclient-script.8;, but should not need any user
            modification to function properly.</para>
        </listitem>

        <listitem><para><filename>/var/db/dhclient.leases</filename></para>
          <para>The DHCP client keeps a database of valid leases in this
            file, which is written as a log.  &man.dhclient.leases.5;
            gives a slightly longer description.</para>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2>
      <title>Further Reading</title>

      <para>The DHCP protocol is fully described in
        <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
        An informational resource has also been set up at
        <ulink url="http://www.dhcp.org/">dhcp.org</ulink>.</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:
-->