diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
index f7484c17f3..640d4f2fc8 100644
--- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
+++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml
@@ -1,3716 +1,3787 @@
<!--
The FreeBSD Documentation Project
- $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.47 2001/06/24 03:06:38 murray Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.48 2001/06/24 03:22:48 murray 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>
+ <indexterm><primary>route</primary></indexterm>
+ <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, 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>
+ <indexterm><primary>default route</primary></indexterm>
<para>The first two lines specify the default route (which we will cover
in the next section) and the <hostid>localhost</hostid> route.</para>
+ <indexterm><primary>loopback device</primary></indexterm>
<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>
+ <indexterm><primary>Ethernet</primary><secondary>MAC address</secondary></indexterm>
<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>
-
+
+ <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">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>=></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>
+ <indexterm><primary>default route</primary></indexterm>
<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] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [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) --> Local1 (10.20.30.1)
Local1 (10.20.30.1, 10.9.9.30) --> T1-GW (10.9.9.1)
</literallayout>
</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 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>
-
+ <indexterm><primary>routing propogation</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>traceroute</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 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="bridging">
<title>Bridging</title>
<para><emphasis>Written by Steve Peterson
<email>steve@zpfe.com</email></emphasis>.</para>
<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 (i.e., 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 bridge. and a FreeBSD system with two network
interface cards can act as a bridge.</para>
<para>The bridge works by learning the MAC layer addresses (i.e.,
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 don't want for whatever reason to
subnet the network and interconnect the subnets with a
router.</para>
<para>Let's 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 "other" 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 address global IP allocation for 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 configuration</primary></indexterm>
+ <indexterm><primary>kernel configuration</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 IPFIREWALL 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. If you want the bridged packets to be filtered by ipfw, you
should also add</para>
<programlisting>net.link.ether.bridge_ipfw=1</programlisting>
<para>as well.</para>
</sect2>
<sect2>
<title>Performance</title>
<para>My bridge/firewall is a Pentium 90 with one 3Com 3C900B and one
3C905B. The protected side of the network runs at 10mbps half duplex
and the connection between the bridge and my router (a Cisco 675) runs
at 100mbps full duplex. With no filtering enabled, I've found that
the bridge adds about 0.4 milliseconds of latency to pings from the
protected 10mbps network to the Cisco 675.</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>
</sect2>
</sect1>
<sect1 id="nfs">
<title>NFS</title>
<para><emphasis>Written by &a.unfurl;, 4 March 2000.</emphasis></para>
-
+ <indexterm><primary>NFS</primary></indexterm>
<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 don't 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 – 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>
-
+ <indexterm><primary>NFS</primary><secondary>server</secondary></indexterm>
+ <indexterm><primary>portmap</primary></indexterm>
+ <indexterm><primary>mountd</primary></indexterm>
+ <indexterm><primary>nfsd</primary></indexterm>
<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>
<listitem>
<para><command>portmap</command> - The portmapper daemon which
allows NFS clients to find out which port the NFS server is
using.</para>
</listitem>
</itemizedlist>
<para>The client side only needs to run a single daemon:</para>
-
+ <indexterm><primary>NFS</primary><secondary>client</secondary></indexterm>
+ <indexterm><primary>nfsiod</primary></indexterm>
<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>
+ <indexterm><primary>NFS</primary><secondary>configuration</secondary></indexterm>
<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 modifications to your <filename>/etc/rc.conf</filename>
file.</para>
<para>On the NFS server make sure you have:</para>
<programlisting>portmap_enable="YES"
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 only a few will be mentioned here. 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>
+ <indexterm><primary>NFS</primary><secondary>exporting filesystems</secondary></indexterm>
<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
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>It's important to remember that you must restart mountd
whenever you modify <filename>/etc/exports</filename> so that
your changes take effect. This can be accomplished by sending
the hangup signal to the mountd process :</para>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
<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>portmap</userinput>
&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>
-
+ <indexterm><primary>NFS</primary><secondary>mounting filesystems</secondary></indexterm>
<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. Some of the more common
ones are listed below.</para>
-
+ <indexterm><primary>NFS</primary><secondary>uses</secondary></indexterm>
<itemizedlist>
<listitem>
<para>Have several machines on a network and share a CD-ROM or
floppy drive among them. This is cheaper and often more
convenient.</para>
</listitem>
<listitem>
<para>With so many machines on a network, it gets old having your
personal files strewn all over the place. You can 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 you log in you will have the same home
directory.</para>
</listitem>
<listitem>
<para>When you get to reinstalling FreeBSD on one of your
machines, NFS is the way to go! Just pop your distribution
CD-ROM into your file server and away you go!</para>
</listitem>
<listitem>
<para>Have a common <filename>/usr/ports/distfiles</filename>
directory that all your machines share. That way, when you go
to install a port that you've already installed on a different
machine, you do not have to download the source all over
again!</para>
</listitem>
</itemizedlist>
</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>
-
+ <indexterm><primary>diskless workstation</primary></indexterm>
<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>
+ <indexterm><primary>HP-UX</primary></indexterm>
<listitem>
<para>HP9000/8xx running HP-UX 9.04 or later (pre 9.04 doesn't
work)</para>
</listitem>
-
+ <indexterm><primary>Solaris</primary></indexterm>
<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>
+ <indexterm><primary>TFTP</primary></indexterm>
+ <indexterm><primary>bootp</primary></indexterm>
<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>
+ <indexterm><primary>NFS</primary><secondary>swapping over</secondary></indexterm>
<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,
e.g.:</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>Although this is not an officially sanctioned or supported way
of doing this, some people report that it works quite well. If
anyone has any suggestions on how to do this cleanly, please tell
&a.doc;.</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>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 road map to ISDN follows:</para>
<itemizedlist>
<listitem>
<para>If you live in Europe you might want to investigate the ISDN card
section.</para>
</listitem>
<listitem>
<para>If you are planning to use ISDN primarily to connect to the
Internet with an Internet Provider on a dial-up non-dedicated basis,
you might look into Terminal Adapters. This will give you the
most flexibility, with the fewest problems, if you change
providers.</para>
</listitem>
<listitem>
<para>If you are connecting two LANs together, or connecting to the
Internet with a dedicated ISDN connection, you might consider
the stand alone router/bridge option.</para>
</listitem>
</itemizedlist>
<para>Cost is a significant factor in determining what solution you will
choose. The following options are listed from least expensive to most
expensive.</para>
<sect2>
<title>ISDN Cards</title>
<para><emphasis>Contributed by &a.hm;.</emphasis></para>
-
+
+ <indexterm><primary>ISDN</primary><secondary>cards</secondary></indexterm>
<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>
+ <indexterm><primary>isdn4bsd</primary></indexterm>
<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>
-
+ <indexterm><primary>modem</primary></indexterm>
<para>Most TA's use the standard hayes modem AT command set, and can be
used as a drop in replacement for a modem.</para>
<para>A TA will operate basically the same as a modem except connection
and throughput speeds will be much faster than your old modem. You
will need to configure <link linkend="ppp">PPP</link> exactly the same
as for a modem setup. Make sure you set your serial speed as high as
possible.</para>
-
+ <indexterm><primary>PPP</primary></indexterm>
<para>The main advantage of using a TA to connect to an Internet
Provider is that you can do Dynamic PPP. As IP address space becomes
more and more scarce, most providers are not willing to provide you
with a static IP anymore. Most stand-alone routers are not able to
accommodate dynamic IP allocation.</para>
<para>TA's completely rely on the PPP daemon that you are running for
their features and stability of connection. This allows you to
upgrade easily from using a modem to ISDN on a FreeBSD machine, if you
already have PPP 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 stand-alone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.</para>
<para>The choice of sync/TA v.s. stand-alone 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>Stand-alone ISDN Bridges/Routers</title>
-
+ <indexterm><primary>ISDN</primary><secondary>stand-alone bridges/routers</secondary></indexterm>
<para>ISDN bridges or routers are not at all specific to FreeBSD
or any other operating system. For a more complete
description of routing and bridging technology, please refer
to a Networking reference book.</para>
<para>In the context of this page, the terms router and bridge will
be used interchangeably.</para>
<para>As the cost of low end ISDN routers/bridges comes down, it
will likely become a more and more popular choice. An ISDN
router is a small box that plugs directly into your local
Ethernet network(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, you
should 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>
+ <indexterm><primary>10 base 2</primary></indexterm>
<para>Network uses a bus based topology with 10 base 2
Ethernet ("thinnet"). Connect router to network cable with
AUI/10BT transceiver, if necessary.</para>
<mediaobject>
<imageobject>
<imagedata fileref="advanced-networking/isdn-bus">
</imageobject>
<textobject>
<literallayout class="monospaced">---Sun workstation
|
---FreeBSD box
|
---Windows 95 (Do not admit to owning it)
|
Stand-alone router
|
ISDN BRI line</literallayout>
</textobject>
<textobject>
<phrase>10 Base 2 Ethernet</phrase>
</textobject>
</mediaobject>
<para>If your home/branch office is only one computer you can use a
twisted pair crossover cable to connect to the stand-alone router
directly.</para>
</example>
<example>
<title>Head office or other LAN</title>
+ <indexterm><primary>10 base T</primary></indexterm>
<para>Network uses a star topology with 10 base T Ethernet
("Twisted Pair").</para>
<mediaobject>
<imageobject>
<imagedata fileref="advanced-networking/isdn-twisted-pair">
</imageobject>
<textobject>
<literallayout class="monospaced"> -------Novell Server
| H |
| ---Sun
| |
| U ---FreeBSD
| |
| ---Windows 95
| B |
|___---Stand-alone router
|
ISDN BRI line</literallayout>
</textobject>
<textobject>
<phrase>ISDN Network Diagram</phrase>
</textobject>
</mediaobject>
</example>
<para>One large advantage of most routers/bridges is that they allow you
to have 2 <emphasis>separate independent</emphasis> PPP connections to
2 separate sites at the <emphasis>same</emphasis> time. This is not
supported on most TA's, except for specific(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 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
dial-in, dial-out or dynamically bond(MPP etc.) with the first B channel
for more bandwidth.</para>
-
+
+ <indexterm><primary>IPX/SPX</primary></indexterm>
<para>An Ethernet bridge will also allow you to transmit more than just
IP traffic, you can also send IPX/SPX or whatever other protocols you
use.</para>
</sect2>
</sect1>
<sect1 id="nis">
<title>NIS/YP</title>
<para><emphasis>Written by &a.unfurl;, 21 January 2000, enhanced
with parts and comments from Eric Ogren
<email>eogren@earthlink.net</email> and Udo Erdelhoff
<email>ue@nathan.ruhr.de</email> in June 2000.</emphasis></para>
<sect2>
<title>What is it?</title>
-
+ <indexterm><primary>NIS</primary></indexterm>
+ <indexterm><primary>Solaris</primary></indexterm>
+ <indexterm><primary>HP-UX</primary></indexterm>
+ <indexterm><primary>AIX</primary></indexterm>
+ <indexterm><primary>Linux</primary></indexterm>
+ <indexterm><primary>NetBSD</primary></indexterm>
+ <indexterm><primary>OpenBSD</primary></indexterm>
<para>NIS, which stands for Network Information Services, was
developed by Sun Microsystems to centralize administration of Unix
(originally SunOS) systems. It has now essentially become an
industry standard; all major Unices (Solaris, HP-UX, AIX, Linux,
NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para>
+ <indexterm><primary>yellow pages (see NIS)</primary></indexterm>
<para>NIS was formerly known as Yellow Pages (or yp), but due to
copyright violations, Sun was forced to change the name.</para>
+ <indexterm><primary>NIS</primary><secondary>domains</secondary></indexterm>
<para>It is a 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>
+ <indexterm><primary>Windows NT</primary></indexterm>
<para>It is similar to Windows NT's domain system; although the
internal implementation of the two aren't at all similar,
the basic functionality can be compared.</para>
</sect2>
<sect2>
<title>Terms/processes you should know</title>
<para>There are several terms and several important user processes
that you will come across when
attempting to implement NIS on FreeBSD, whether you are trying to
create an NIS server or act an NIS client:</para>
<itemizedlist>
<listitem>
<para><emphasis>The NIS domainname</emphasis>. An NIS master
server and all of its clients (including its slave servers) have
a NIS domainname. Similar to an NT domain name, the NIS
domainname does not have anything to do with DNS.</para>
</listitem>
+ <indexterm><primary>portmap</primary></indexterm>
<listitem>
<para><emphasis>portmap</emphasis>. <command>portmap</command>
must be running in order to enable RPC (Remote Procedure Call, a
network protocol used by NIS). If <command>portmap</command> is
not running, it will be impossible to run an NIS server, or to
act as an NIS client.</para>
</listitem>
<listitem>
<para><emphasis>ypbind</emphasis>. <command>ypbind</command>
“binds” an NIS client to its NIS server.
It will take the NIS domainname from the system, and
using RPC, connect to the server. <command>ypbind</command> is
the core of client-server communication in an NIS environment; if
<command>ypbind</command> dies on a client machine, it will not
be able to access the NIS server.</para>
</listitem>
<listitem>
<para><emphasis>ypserv</emphasis>. <command>ypserv</command>,
which should only be running on NIS servers, is the NIS server
process itself. If ypserv dies, then the server will no longer be
able to respond to NIS requests (hopefully, there is a slave
server to take over for it).</para>
<note><para>There are some implementations of NIS (but not the
FreeBSD one), that don't try to reconnect to another server
if the server it used before dies. Often, the only thing
that helps in this case is to restart the server process (or
even the whole server) or the <command>ypbind</command> process
on the client.</para></note>
</listitem>
<listitem>
<para><emphasis>rpc.yppasswdd</emphasis>.
<command>rpc.yppasswdd</command>, another process that should
only be running on NIS master servers, is a daemon that will
allow NIS clients to change their NIS passwords.
If this daemon is not running, users will have to login to the
NIS master server and change their passwords there.</para>
</listitem>
<!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
on the master -->
</itemizedlist>
</sect2>
<sect2>
<title>How does it work?</title>
<para>There are three types of hosts in an NIS environment; master
servers, slave servers, and clients. Servers act as a central
repository for host configuration information. Master servers
hold the authoritative 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>
<sect3>
<title>Machine types</title>
<itemizedlist>
+ <indexterm><primary>NIS</primary><secondary>master server</secondary></indexterm>
<listitem>
<para>A <emphasis>NIS master server</emphasis>.
This server, analogous to a Windows
NT primary domain controller, maintains the files used by all
of the NIS clients. The <filename>passwd</filename>,
<filename>group</filename>, and other various files used by the
NIS clients live on the master server.</para>
<note><para>It is possible for one machine to be an NIS
master server for more than one NIS domain. However, this will
not be covered in this introduction, which assumes a relatively
small-scale NIS environment.</para></note>
</listitem>
+ <indexterm><primary>NIS</primary><secondary>slave server</secondary></indexterm>
<listitem>
<para><emphasis>NIS slave servers</emphasis>.
Similar to NT's backup domain
controllers, NIS slave servers maintain copies of the NIS
master's data files. NIS slave servers provide the redundancy,
which is needed in important environments. They also help
to balance the load of the master server: NIS Clients always
attach to the NIS server whose response they get first, and
this includes slave-server-replies.</para>
</listitem>
+ <indexterm><primary>NIS</primary><secondary>client</secondary></indexterm>
<listitem>
<para><emphasis>NIS clients</emphasis>. NIS clients, like most
NT workstations, authenticate against the NIS server (or the NT
domain controller in the NT Workstation case) to log on.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>Using NIS/YP</title>
<para>This section will deal with setting up a sample NIS
environment.</para>
<note><para>This section assumes that you are running FreeBSD 3.3
or later. The instructions given here will
<emphasis>probably</emphasis> work for any version of FreeBSD greater
than 3.0, but there are no guarantees that this is
true.</para></note>
<sect3>
<title>Planning</title>
<para>Let's assume that you are the administrator of a small
university lab. This lab, which consists of 15 FreeBSD machines,
currently has no centralized point of administration; each machine
has its own <filename>/etc/passwd</filename> and
<filename>/etc/master.passwd</filename>. These files are kept in
sync with each other only through manual intervention;
currently, when you add a user to the lab, you must run
<command>adduser</command> on all 15 machines.
Clearly, this has to change, so you have decided to convert the
lab to use NIS, using two of the machines as servers.</para>
<para>Therefore, the configuration of the lab now looks something
like:</para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Machine name</entry>
<entry>IP address</entry>
<entry>Machine role</entry>
</row>
</thead>
<tbody>
<row>
<entry><hostid>ellington</hostid></entry>
<entry><hostid role="ipaddr">10.0.0.2</hostid></entry>
<entry>NIS master</entry>
</row>
<row>
<entry><hostid>coltrane</hostid></entry>
<entry><hostid role="ipaddr">10.0.0.3</hostid></entry>
<entry>NIS slave</entry>
</row>
<row>
<entry><hostid>basie</hostid></entry>
<entry><hostid role="ipaddr">10.0.0.4</hostid></entry>
<entry>Faculty workstation</entry>
</row>
<row>
<entry><hostid>bird</hostid></entry>
<entry><hostid role="ipaddr">10.0.0.5</hostid></entry>
<entry>Client machine</entry>
</row>
<row>
<entry><hostid>cli[1-11]</hostid></entry>
<entry><hostid role="ipaddr">10.0.0.[6-17]</hostid></entry>
<entry>Other client machines</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<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>
-
+
+ <indexterm><primary>NIS</primary><secondary>domainname</secondary></indexterm>
<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 some 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. For this example, assume you have
chosen the name <emphasis>test-domain</emphasis>.</para>
+ <indexterm><primary>SunOS</primary></indexterm>
<para>However, some operating systems (notably SunOS) use their
NIS domain name as their Internet domain name.
If one or more machines on your network have this restriction,
you <emphasis>must</emphasis> use the Internet domain name as
your NIS domain name.</para>
</sect4>
<sect4>
<title>Physical Server Requirements</title>
<para>There are several things to keep in mind when choosing 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>
-
+ <indexterm><primary>NIS</primary><secondary>server configuration</secondary></indexterm>
<para>Setting up a master NIS server can be relatively straight
forward, depending on your needs. FreeBSD comes with support
for NIS out-of-the-box. All you need is to add the following
lines to <filename>/etc/rc.conf</filename>, and FreeBSD will
do the rest for you.</para>
<itemizedlist>
<listitem>
<para><programlisting>nisdomainname="test-domain"</programlisting>
This line will set the NIS domainname to
<emphasis>test-domain</emphasis>
upon network setup (e.g. after reboot).</para>
</listitem>
<listitem>
<para><programlisting>nis_server_enable="YES"</programlisting>
This will tell FreeBSD to start up the NIS server processes
when the networking is next brought up.</para>
</listitem>
<listitem>
<para><programlisting>nis_yppasswdd_enable="YES"</programlisting>
This will enable the <command>rpc.yppasswdd</command>
daemon, which, as mentioned above, will allow users to
change their NIS password from a client machine.</para>
</listitem>
</itemizedlist>
<para>Now, all you have to do is to run the command
<command>/etc/netstart</command> as superuser. It will
setup everything for you, using the values you defined in
<filename>/etc/rc.conf</filename>.</para>
</sect4>
<sect4>
<title>Initializing the NIS maps</title>
-
+ <indexterm><primary>NIS maps</primary></indexterm>
<para>The <emphasis>NIS maps</emphasis> are database files,
that are kept in the <filename>/var/yp</filename> directory.
They are generated from configuration files in the
<filename>/etc</filename> directory of the NIS master, with one
exception: the <filename>/etc/master.passwd</filename> file.
This is for a good reason; you don't want to propagate
passwords to your root and other administrative accounts to
all the servers in the NIS domain. Therefore, before we
initialize the NIS maps, you should:</para>
<screen>
&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput>
&prompt.root; <userinput>cd /var/yp</userinput>
&prompt.root; <userinput>vi master.passwd</userinput>
</screen>
<para>You should remove all entries regarding system accounts
(bin, tty, kmem, games, etc), as well as any accounts that you
don't want to be propagated to the NIS clients (for example
root and any other UID 0 (superuser) accounts).</para>
<note><para>Make sure the
<filename>/var/yp/master.passwd</filename> is neither group
nor world readable (mode 600)! Use the
<command>chmod</command> command, if appropriate.</para></note>
+ <indexterm><primary>Tru64 Unix</primary></indexterm>
<para>When you have finished, it's time to initialize the NIS
maps! FreeBSD includes a script named
<command>ypinit</command> to do this for you
(see its man page for more information). Note that this
script is available on most UNIX OSs, but not on all.
On Digital Unix/Compaq Tru64 Unix it is called
<command>ypsetup</command>.
Because we are generating maps for an NIS master, we are
going to pass the <option>-m</option> option to
<command>ypinit</command>.
To generate the NIS maps, assuming you already performed
the steps above, run:</para>
<screen>
ellington&prompt.root; <userinput>ypinit -m test-domain</userinput>
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] <userinput>n</userinput>
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.
rod.darktech.org 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 <control D>.
master server : ellington
next host to add: <userinput>coltrane</userinput>
next host to add: <userinput>^D</userinput>
The current list of NIS servers looks like this:
ellington
coltrane
Is this correct? [y/n: y] <userinput>y</userinput>
[..output from map generation..]
NIS Map update completed.
ellington has been setup as an YP master server without any errors.
</screen>
<para><command>ypinit</command> should have created
<filename>/var/yp/Makefile</filename> from
<filename>/var/yp/Makefile.dist</filename>.
When created, this file assumes that you are operating
in a single server NIS environment with only FreeBSD
machines. Since <emphasis>test-domain</emphasis> has
a slave server as well, you must edit
<filename>/var/yp/Makefile</filename>:</para>
<screen>
ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput>
</screen>
<para>You should comment out the line that says `NOPUSH =
"True"' (if it is not commented out already).</para>
</sect4>
<sect4>
<title>Setting up a NIS slave server</title>
-
+ <indexterm><primary>NIS</primary><secondary>configuring a
+ slave server</secondary></indexterm>
<para>Setting up an NIS slave server is even more simple than
setting up the master. Log on to the slave server and edit the
file <filename>/etc/rc.conf</filename> as you did before.
The only difference is that we now must use the
<option>-s</option> option when running <command>ypinit</command>.
The <option>-s</option> option requires the name of the NIS
master be passed to it as well, so our command line looks
like:</para>
<screen>
coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput>
Server Type: SLAVE Domain: test-domain Master: ellington
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 ellington.
Transferring netgroup...
ypxfr: Exiting: Map successfully transferred
Transferring netgroup.byuser...
ypxfr: Exiting: Map successfully transferred
Transferring netgroup.byhost...
ypxfr: Exiting: Map successfully transferred
Transferring master.passwd.byuid...
ypxfr: Exiting: Map successfully transferred
Transferring passwd.byuid...
ypxfr: Exiting: Map successfully transferred
Transferring passwd.byname...
ypxfr: Exiting: Map successfully transferred
Transferring group.bygid...
ypxfr: Exiting: Map successfully transferred
Transferring group.byname...
ypxfr: Exiting: Map successfully transferred
Transferring services.byname...
ypxfr: Exiting: Map successfully transferred
Transferring rpc.bynumber...
ypxfr: Exiting: Map successfully transferred
Transferring rpc.byname...
ypxfr: Exiting: Map successfully transferred
Transferring protocols.byname...
ypxfr: Exiting: Map successfully transferred
Transferring master.passwd.byname...
ypxfr: Exiting: Map successfully transferred
Transferring networks.byname...
ypxfr: Exiting: Map successfully transferred
Transferring networks.byaddr...
ypxfr: Exiting: Map successfully transferred
Transferring netid.byname...
ypxfr: Exiting: Map successfully transferred
Transferring hosts.byaddr...
ypxfr: Exiting: Map successfully transferred
Transferring protocols.bynumber...
ypxfr: Exiting: Map successfully transferred
Transferring ypservers...
ypxfr: Exiting: Map successfully transferred
Transferring hosts.byname...
ypxfr: Exiting: Map successfully transferred
coltrane has been setup as an YP slave server without any errors.
Don't forget to update map ypservers on ellington.</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 its NIS maps are
communicated to its 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>
<para>Now, run the command <command>/etc/netstart</command> on the
slave server as well, which again starts the NIS server.</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
<command>ypbind</command> daemon.
<command>ypbind</command> 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. <command>Ypbind</command> 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>
-
+ <indexterm><primary>NIS</primary><secondary>client configuration</secondary></indexterm>
<para>Setting up a FreeBSD machine to be a NIS client is fairly
straightforward.</para>
<itemizedlist>
<listitem>
<para>Edit the file <filename>/etc/rc.conf</filename> and
add the following lines in order to set the NIS domainname
and start <command>ypbind</command> upon network
startup:</para>
<programlisting>nisdomainname="test-domain"
nis_client_enable="YES"</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. See the <link linkend="netgroups">netgroups
part</link> below for more information.
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
# this includes the machines in the testlab
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
vulnerable to <quote>IP spoofing</quote> attacks. All
NIS-related traffic should be blocked at your firewall.</para>
<para>Servers using <filename>/var/yp/securenets</filename>
may fail to serve legitimate NIS clients with archaic TCP/IP
implementations. Some of these implementations set all
host bits to zero when doing broadcasts and/or fail to
observe the subnet mask when calculating the broadcast
address. While some of these problems can be fixed by
changing the client configuration, other problems may force
the retirement of the client systems in question or the
abandonment of <filename>/var/yp/securenets</filename>.</para>
<para>Using <filename>/var/yp/securenets</filename> on a
server with such an archaic implementation of TCP/IP is a
really bad idea and will lead to loss of NIS functionality
for large parts of your network.</para>
+ <indexterm><primary>tcpwrapper</primary></indexterm>
<para>The use of the <application>tcpwrapper</application>
package increases the latency of your NIS server. The
additional delay may be long enough to cause timeouts in
client programs, especially in busy networks or with slow
NIS servers. If one or more of your client systems
suffers from these symptoms, you should convert the client
systems in question into NIS slave servers and force them
to bind to themselves.</para>
</note>
</sect2>
<sect2>
<title>Barring some users from logging on</title>
<para>In our lab, there is a machine <hostid>basie</hostid> that is
supposed to be a faculty only workstation. We don't want to take this
machine out of the NIS domain, yet the <filename>passwd</filename>
file on the master NIS server contains accounts for both faculty and
students. What can we do?</para>
<para>There is a way to bar specific users from logging on to a
machine, even if they are present in the NIS database. To do this,
all you must do is add
<emphasis>-<replaceable>username</replaceable></emphasis> to the end of
the <filename>/etc/master.passwd</filename> file on the client
machine, where <replaceable>username</replaceable> is the username of
the user you wish to bar from logging in. This should preferably be
done using <command>vipw</command>, since <command>vipw</command>
will sanity check your changes to
<filename>/etc/master.passwd</filename>, as well as
automatically rebuild the password database when you
finish editing. For example, if we wanted to bar user
<emphasis>bill</emphasis> from logging on to <hostid>basie</hostid>
we would:</para>
<screen>
basie&prompt.root; <userinput>vipw</userinput>
<userinput>[add -bill to the end, exit]</userinput>
vipw: rebuilding the database...
vipw: done
basie&prompt.root; <userinput>cat /etc/master.passwd</userinput>
root:[password]:0:0::0:0:The super-user:/root:/bin/csh
toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh
daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin
operator:*:2:5::0:0:System &:/:/sbin/nologin
bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin
tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin
kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin
games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin
news:*:8:8::0:0:News Subsystem:/:/sbin/nologin
man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin
bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin
uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico
xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin
pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin
nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin
+:::::::::
-bill
basie&prompt.root;</screen>
</sect2>
<sect2 id="netgroups">
<title>Using netgroups</title>
+ <indexterm><primary>netgroups</primary></indexterm>
<para><emphasis>The netgroups part was contributed by
Udo Erdelhoff <email>ue@nathan.ruhr.de</email> in July
2000.</emphasis></para>
<para>The method shown in the previous chapter works reasonably
well if you need special rules for a very small number of
users and/or machines. On larger networks, you
<emphasis>will</emphasis> forget to bar some users from logging
onto sensitive machines, or you may even have to modify each
machine separately, thus losing the main benefit of NIS,
<emphasis>centralized</emphasis> administration.</para>
<para>The NIS developers' solution for this problem is called
<emphasis>netgroups</emphasis>. Their purpose and semantics
can be compared to the normal groups used by Unix file
systems. The main differences are the lack of a numeric id
and the ability to define a netgroup by including both user
accounts and other netgroups.</para>
<para>Netgroups were developed to handle large, complex networks
with hundreds of users and machines. On one hand, this is
a Good Thing if you are forced to deal with such a situation.
On the other hand, this complexity makes it almost impossible to
explain netgroups with really simple examples. The example
used in the remainder of this chapter demonstrates this
problem.</para>
<para>Let us assume that your successful introduction of NIS in
your laboratory caught your superiors' interest. Your next
job is to extend your NIS domain to cover some of the other
machines on campus. The two tables contain the names of the
new users and new machines as well as brief descriptions of
them.</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>User Name(s)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>alpha, beta</entry>
<entry>Normal employees of the IT department</entry>
</row>
<row>
<entry>charlie, delta</entry>
<entry>The new apprentices of the IT department</entry>
</row>
<row>
<entry>echo, foxtrott, golf, ...</entry>
<entry>Ordinary employees</entry>
</row>
<row>
<entry>able, baker, ...</entry>
<entry>The current interns</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Machine Name(s)</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<!-- Names taken from "Good Omens" by Neil Gaiman and Terry
Pratchett. Many thanks for a brilliant book. -->
<entry>war, death, famine, pollution</entry>
<entry>Your most important servers. Only the IT
employees are allowed to log onto these
machines.</entry>
</row>
<row>
<!-- gluttony was omitted because it was too fat ;-) -->
<entry>pride, greed, envy, wrath, lust, sloth</entry>
<entry>Less important servers. All members of the IT
department are allowed to login onto these machines.</entry>
</row>
<row>
<entry>one, two, three, four, ...</entry>
<entry>Ordinary workstations. Only the
<emphasis>real</emphasis> employees are allowed to use
these machines.</entry>
</row>
<row>
<entry>trashcan</entry>
<entry>A very old machine without any critical data.
Even the intern is allowed to use this box.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>If you tried to implement these restrictions by separately
blocking each user, you would have to add one
-<replaceable>user</replaceable> line to each system's passwd
for each user who is not allowed to login onto that system.
If you forget just one entry, you could be in trouble. It may
be feasible to do this correctly during the initial setup,
however you <emphasis>will</emphasis> eventually forget to add
the lines for new users during day-to-day operations. After
all, Murphy was an optimist.</para>
<para>Handling this situation with netgroups offers several
advantages. Each user need not be handled separately;
you assign a user to one or more netgroups and allow or forbid
logins for all members of the netgroup. If you add a new
machine, you will only have to define login restrictions for
netgroups. If a new user is added, you will only have to add
the user to one or more netgroups. Those changes are
independent of each other; no more <quote>for each combination
of user and machine do...</quote> If your NIS setup is planned
carefully, you will only have to modify exactly one central
configuration file to grant or deny access to machines.</para>
<para>The first step is the initialization of the NIS map
netgroup. FreeBSD's ypinit does not create this map by
default, but its NIS implementation will support it once it has
been created. To create an empty map, simply type</para>
<screen>
ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput>
</screen>
<para>and start adding content. For our example, we need at
least four netgroups: IT employees, IT apprentices, normal
employees and interns.</para>
<programlisting>IT_EMP (,alpha,test-domain) (,beta,test-domain)
IT_APP (,charlie,test-domain) (,delta,test-domain)
USERS (,echo,test-domain) (,foxtrott,test-domain) \
(,golf,test-domain)
INTERNS (,able,test-domain) (,baker,test-domain)</programlisting>
<para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc.
are the names of the netgroups. Each bracketed group adds
one or more user accounts to it. The three fields inside a
group are:</para>
<orderedlist>
<listitem>
<para>The name of the host(s) where the following items are
valid. If you do not specify a hostname, the entry is
valid on all hosts. If you do specify a hostname, you
will enter a realm of darkness, horror and utter confusion.</para>
</listitem>
<listitem>
<para>The name of the account that belongs to this
netgroup.</para>
</listitem>
<listitem>
<para>The NIS domain for the account. You can import
accounts from other NIS domains into your netgroup if you
are one of unlucky fellows with more than one NIS
domain.</para>
</listitem>
</orderedlist>
<para>Each of these fields can contain wildcards. See
&man.netgroup.5; for details.</para>
<note>
+ <indexterm><primary>netgroups</primary></indexterm>
<para>Netgroup names longer than 8 characters should not be
used, especially if you have machines running other
operating systems within your NIS domain. The names are
case sensitive; using capital letters for your netgroup
names is an easy way to distinguish between user, machine
and netgroup names.</para>
<para>Some NIS clients (other than FreeBSD) cannot handle
netgroups with a large number of entries. For example, some
older versions of SunOS start to cause trouble if a netgroup
contains more than 15 <emphasis>entries</emphasis>. You can
circumvent this limit by creating several sub-netgroups with
15 users or less and a real netgroup that consists of the
sub-netgroups:</para>
<programlisting>BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...]
BIGGRP2 (,joe16,domain) (,joe17,domain) [...]
BIGGRP3 (,joe31,domain) (,joe32,domain)
BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3</programlisting>
<para>You can repeat this process if you need more than 225
users within a single netgroup.</para>
</note>
<para>Activating and distributing your new NIS map is
easy:</para>
<screen>
ellington&prompt.root; <userinput>cd /var/yp</userinput>
ellington&prompt.root; <userinput>make</userinput>
</screen>
<para>This will generate the three NIS maps
<filename>netgroup</filename>,
<filename>netgroup.byhost</filename> and
<filename>netgroup.byuser</filename>. Use &man.ypcat.1; to
check if your new NIS maps are available:</para>
<screen>
ellington&prompt.user; <userinput>ypcat -k netgroup</userinput>
ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput>
ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput>
</screen>
<para>The output of the first command should resemble the
contents of <filename>/var/yp/netgroup</filename>. The second
command will not produce output if you have not specified
host-specific netgroups. The third command can be used to
get the list of netgroups for a user.</para>
<para>The client setup is quite simple. To configure the server
<replaceable>war</replaceable>, you only have to start
&man.vipw.8; and replace the line</para>
<programlisting>+:::::::::</programlisting>
<para>with</para>
<programlisting>+@IT_EMP:::::::::</programlisting>
<para>Now, only the data for the users defined in the netgroup
<replaceable>IT_EMP</replaceable> is imported into
<replaceable>war</replaceable>'s password database and only
these users are allowed to login.</para>
<para>Unfortunately, this limitation also applies to the ~
function of the shell and all routines converting between user
names and numerical user ids. In other words, cd
~<replaceable>user</replaceable> will not work, <command>ls
-l</command> will show the numerical id instead of the
username and <command>find . -user joe -print</command> will
fail with <quote>No such user</quote>. To fix this, you will
have to import all user entries <emphasis>without
allowing them to login onto your servers</emphasis>.</para>
<para>This can be achieved by adding another line to
<filename>/etc/master.passwd</filename>. This line should
contain <literal>+:::::::::/sbin/nologin</literal>, meaning
<quote>Import all entries but replace the shell with
<filename>/sbin/nologin</filename> in the imported
entries</quote>. You can replace any field
in the passwd entry by placing a default value in your
<filename>/etc/master.passwd</filename>.</para>
<!-- Been there, done that, got the scars to prove it - ue -->
<warning>
<para>Make sure that the line
<literal>+:::::::::/sbin/nologin</literal> is placed after
<literal>+@IT_EMP:::::::::</literal>. Otherwise, all user
accounts imported from NIS will have /sbin/nologin as their
login shell.</para>
</warning>
<para>After this change, you will only have to change one NIS
map if a new employee joins the IT department. You could use
a similar approach for the less important servers by replacing
the old <literal>+:::::::::</literal> in their local version
of <filename>/etc/master.passwd</filename> with something like
this:</para>
<programlisting>+@IT_EMP:::::::::
+@IT_APP:::::::::
+:::::::::/sbin/nologin</programlisting>
<para>The corresponding lines for the normal workstations
could be:</para>
<programlisting>+@IT_EMP:::::::::
+@USERS:::::::::
+:::::::::/sbin/nologin</programlisting>
<para>And everything would be fine until there is a policy
change a few weeks later: The IT department starts hiring
interns. The IT interns are allowed to use the normal
workstations and the less important servers; and the IT
apprentices are allowed to login onto the main servers. You
add a new netgroup IT_INTERN, add the new IT interns to this
netgroup and start to change the config on each and every
machine... As the old saying goes: <quote>Errors in
centralized planning lead to global mess</quote>.</para>
<para>NIS' ability to create netgroups from other netgroups can
be used to prevent situations like these. One possibility
is the creation of role-based netgroups. For example, you
could create a netgroup called
<replaceable>BIGSRV</replaceable> to define the login
restrictions for the important servers, another netgroup
called <replaceable>SMALLSRV</replaceable> for the less
important servers and a third netgroup called
<replaceable>USERBOX</replaceable> for the normal
workstations. Each of these netgroups contains the netgroups
that are allowed to login onto these machines. The new
entries for your NIS map netgroup should look like this:</para>
<programlisting>BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN USERS</programlisting>
<para>This method of defining login restrictions works
reasonably well if you can define groups of machines with
identical restrictions. Unfortunately, this is the exception
and not the rule. Most of the time, you will need the ability
to define login restrictions on a per-machine basis.</para>
<para>Machine-specific netgroup definitions are the other
possibility to deal with the policy change outlined above. In
this scenario, the <filename>/etc/master.passwd</filename> of
each box contains two lines starting with ``+''. The first of
them adds a netgroup with the accounts allowed to login onto
this machine, the second one adds all other accounts with
<filename>/sbin/nologin</filename> as shell. It is a good
idea to use the ALL-CAPS version of the machine name as the
name of the netgroup. In other words, the lines should look
like this:</para>
<programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
+:::::::::/sbin/nologin</programlisting>
<para>Once you have completed this task for all your machines,
you will not have to modify the local versions of
<filename>/etc/master.passwd</filename> ever again. All
further changes can be handled by modifying the NIS map. Here
is an example of a possible netgroup map for this
scenario with some additional goodies.</para>
<programlisting># Define groups of users first
IT_EMP (,alpha,test-domain) (,beta,test-domain)
IT_APP (,charlie,test-domain) (,delta,test-domain)
DEPT1 (,echo,test-domain) (,foxtrott,test-domain)
DEPT2 (,golf,test-domain) (,hotel,test-domain)
DEPT3 (,india,test-domain) (,juliet,test-domain)
ITINTERN (,kilo,test-domain) (,lima,test-domain)
D_INTERNS (,able,test-domain) (,baker,test-domain)
#
# Now, define some groups based on roles
USERS DEPT1 DEPT2 DEPT3
BIGSRV IT_EMP IT_APP
SMALLSRV IT_EMP IT_APP ITINTERN
USERBOX IT_EMP ITINTERN USERS
#
# And a groups for a special tasks
# Allow echo and golf to access our anti-virus-machine
SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain)
#
# machine-based netgroups
# Our main servers
WAR BIGSRV
FAMINE BIGSRV
# User india needs access to this server
POLLUTION BIGSRV (,india,test-domain)
#
# This one is really important and needs more access restrictions
DEATH IT_EMP
#
# The anti-virus-machine mentioned above
ONE SECURITY
#
# Restrict a machine to a single user
TWO (,hotel,test-domain)
# [...more groups to follow]</programlisting>
<para>If you are using some kind of database to manage your user
accounts, you should be able to create the first part of the
map with your database's report tools. This way, new users
will automatically have access to the boxes.</para>
<para>One last word of caution: It may not always be advisable
to use machine-based netgroups. If you are deploying a couple
dozen or even hundreds of identical machines for student labs,
you should use role-based netgroups instead of machine-based
netgroups to keep the size of the NIS map within reasonable
limits.</para>
</sect2>
<sect2>
<title>Important things to remember</title>
<para>There are still a couple of things that you will need to do
differently now that you are in an NIS environment.</para>
<itemizedlist>
<listitem>
<para>Every time you wish to add a user to the lab, you
must add it to the master NIS server <emphasis>only</emphasis>,
and <emphasis>you must remember to rebuild the NIS
maps</emphasis>. If you forget to do this, the new user will
not be able to login anywhere except on the NIS master.
For example, if we needed to add a new user
“jsmith” to the lab, we would:</para>
<screen>
&prompt.root; <userinput>pw useradd jsmith</userinput>
&prompt.root; <userinput>cd /var/yp</userinput>
&prompt.root; <userinput>make test-domain</userinput></screen>
<para>You could also run <command>adduser jsmith</command> instead
of <command>pw useradd jsmith</command>.</para>
</listitem>
<listitem>
<para><emphasis>Keep the administration accounts out of the NIS
maps</emphasis>. You don't want to be propagating administrative
accounts and passwords to machines that will have users that
shouldn't have access to those accounts.</para>
</listitem>
<listitem>
<para><emphasis>Keep the NIS master and slave
secure, and minimize their downtime</emphasis>.
If somebody either hacks or simply turns off
these machines, they have effectively rendered many people without
the ability to login to the lab.</para>
<para>This is the chief weakness of any centralized administration
system, and it is probably the most important weakness. If you do
not protect your NIS servers, you will have a lot of angry
users!</para>
</listitem>
</itemizedlist>
</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 v.s. libdescrypt</title>
-
+ <indexterm><primary>NIS</primary><secondary>crypto library</secondary></indexterm>
<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 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@ -> 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.
If you want to deploy an NIS server for a heterogenous
network, you will probably have to use DES on all systems
because it is the lowest common standard.</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>
+ <indexterm><primary>Dynamic Host Configuration Protocol (DHCP)</primary></indexterm>
+ <indexterm><primary>Internet Software Consortium (ISC)</primary></indexterm>
<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>
-
+ <indexterm><primary>UDP</primary></indexterm>
<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>
-
+ <indexterm><primary>sysinstall</primary></indexterm>
<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>There are two things you must do to have your system use
DHCP upon startup:</para>
-
+ <indexterm><primary>DHCP</primary><secondary>requirements</secondary></indexterm>
<itemizedlist>
<listitem>
<para>Make sure that the <devicename>bpf</devicename>
device is compiled into your kernel. To do this, add
<literal>pseudo-device bpf</literal> to your kernel
configuration file, and rebuild the kernel. For more
information about building kernels, see <xref
linkend="kernelconfig">.</para>
<para>The <devicename>bpf</devicename> device is already
part of the <filename>GENERIC</filename> kernel that is
supplied with FreeBSD, so if you don't have a custom
kernel, you shouldn't need to create one in order to get
DHCP working.</para>
<note>
<para>For those who are particularly security conscious,
you should be warned that <devicename>bpf</devicename>
is also the device that allows packet sniffers to work
correctly (although they still have to be run as
root). <devicename>bpf</devicename>
<emphasis>is</emphasis> required to use DHCP, but if
you are very sensitive about security, you probably
shouldn't add <devicename>bpf</devicename> to your
kernel in the expectation that at some point in the
future you will be using DHCP.</para>
</note>
</listitem>
<listitem>
<para>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>
</listitem>
</itemizedlist>
+ <indexterm><primary>DHCP</primary><secondary>server</secondary></indexterm>
<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>
-
+ <indexterm><primary>DHCP</primary><secondary>configuration files</secondary></indexterm>
<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>
<sect1 id="dns">
<title>DNS</title>
<para><emphasis>Contributed by &a.chern;, April 12, 2001.
</emphasis>
</para>
<sect2>
<title>Overview</title>
+ <indexterm><primary>BIND</primary></indexterm>
+
<para>FreeBSD utilizes, by default, a version of BIND (Berkeley
Internet Name Domain), which is the most common implementation of the
DNS protocol. DNS is the protocol through which names are mapped to
IPs, and vice versa. For example, a query for www.freebsd.org
will send back a reply for the IP address of The FreeBSD Project's
webpage, whereas, a query for ftp.freebsd.org will return the IP
of the corresponding ftp machine. Likewise, the opposite can
happen. A query for an IP address can resolve its hostname.
</para>
+ <indexterm><primary>DNS</primary></indexterm>
<para>DNS is coordinated across the Internet through a somewhat
complex system of authoritative root name servers, and other
smaller-scale nameservers who host and relay individual domain
information.
</para>
<para>
This document refers to BIND 8.x, as it is the most current,
stable version used in FreeBSD.
</para>
<para>
RFC1034 and RFC1035 dictates the DNS protocol.
</para>
<para>
Currently, BIND is maintained by the <ulink
url="http://www.isc.org">
Internet Software Consortium (www.isc.org)</ulink>
</para>
</sect2>
<sect2>
<title>Terminology</title>
+ <indexterm><primary>zones</primary></indexterm>
<para><emphasis>zone</emphasis> - Each individual domain, subdomain,
or 'area' dictated by DNS is considered a zone.
</para>
<para>Examples of zones:
</para>
<itemizedlist>
<listitem>
<para>. is the root zone</para>
</listitem>
<listitem>
<para>org. is a zone under the root zone</para>
</listitem>
<listitem>
<para>foobardomain.org is a zone under the org. zone</para>
</listitem>
<listitem>
<para>foo.foobardomain.org. is a subdomain, a zone under the
foobardomain.org. zone
</para>
</listitem>
<listitem>
<para>
1.2.3.in-addr.arpa is a zone referencing all ips which fall
under the 3.2.1.* ip space.
</para>
</listitem>
</itemizedlist>
<para><emphasis>named, bind, name server</emphasis> - these are all
common names for the BIND name server package within FreeBSD.
</para>
+ <indexterm><primary>resolver</primary></indexterm>
<para><emphasis>resolver</emphasis> - a network process by which a
system queries a nameserver for answers
</para>
+ <indexterm><primary>root zone</primary></indexterm>
<para><emphasis>root zone</emphasis> - literally, a '.', refers to
the root, or beginning zone. All zones fall under this, as do all
files in fall under the root directory. It is the beginning of the
Internet zone hierarchy
</para>
<para><emphasis>origin</emphasis> - refers to the point of start for
the particular zone
</para>
<para><emphasis>forward dns</emphasis> - mapping of hostnames to ip
addresses
</para>
+ <indexterm><primary>reverse DNS</primary></indexterm>
<para><emphasis>reverse dns</emphasis> - the opposite, mapping of ip
addresses to hostnames
</para>
</sect2>
<sect2>
<title>Reasons to run a name server</title>
<itemizedlist>
<listitem>
<para>
You need your machine to host DNS information to the world
</para>
<itemizedlist>
<listitem>
<para>An authoritative nameserver replies exclusively
to requests.
</para>
</listitem>
<listitem>
<para>For example, you register foobardomain.org and wish
to assign hostnames to the proper IP addresses.
</para>
</listitem>
<listitem>
<para>A slave nameserver, which replies to queries for a
domain when the primary is down or inaccessible.
</para>
</listitem>
<listitem>
<para>The above two can also be done with in-addr.arpa, IP
to hostname entries
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
You wish your machine to act as a local relay of DNS
information
</para>
<itemizedlist>
<listitem>
<para>DNS traffic has been measured to be about 5% or more
of the total Internet traffic.
</para>
</listitem>
<listitem>
<para>A local DNS server may have some added benefit by
providing a local cache of DNS information.
</para>
</listitem>
<listitem>
<para>
For example, when one queries for www.freebsd.org,
their resolver goes out to (usually) your ISP's name
server, and retrieves the query.
</para>
</listitem>
<listitem>
<para>
With a local, caching DNS server, the query only has to
be made once to the outside world. Every additional
query will not have to go outside of the local network,
since the information is cached.
</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>How it works</title>
<para>
A DNS server in FreeBSD relies on the BIND daemon. This daemon is
called 'named' for obvious reasons.
</para>
<para><command>named</command> - the bind daemon</para>
<para><command>ndc</command> - name daemon control program</para>
<para>
<filename>/etc/namedb</filename> - directory where all the bind
information resides
</para>
<para>
<filename>/etc/namedb/named.conf</filename> - daemon configuration
file
</para>
<para>
zone files are usually contained within the
<filename>/etc/namedb</filename>
directory, and contain the information (query answers from
your site) served by your name server.
</para>
</sect2>
<sect2>
<title>Starting BIND</title>
+ <indexterm><primary>BIND</primary><secondary>starting</secondary></indexterm>
<para>
Since bind is installed by default, configuring it all is
relatively simple.
</para>
<para>
To ensure the named daemon is started at boot, put the following
modifications in your <filename>/etc/rc.conf</filename>
</para>
<programlisting>named_enable="YES"</programlisting>
<para>To start the daemon manually (after configuring it)</para>
<screen>&prompt.root; <userinput>ndc start</userinput></screen>
</sect2>
<sect2>
<title>Configuration files</title>
+ <indexterm><primary>BIND</primary><secondary>configuration files</secondary></indexterm>
<sect3>
<title>make-localhost</title>
<para>Be sure to
</para>
<screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
&prompt.root; <userinput>sh make-localhost</userinput>
</screen>
<para>to properly create your local reverse dns zone file in
<filename>/etc/namedb/localhost.rev</filename>.
</para>
</sect3>
<sect3>
<title><filename>/etc/namedb/named.conf</filename></title>
- <programlisting>// $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.47 2001/06/24 03:06:38 murray Exp $
+ <programlisting>// $FreeBSD: doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml,v 1.48 2001/06/24 03:22:48 murray Exp $
//
// Refer to the named(8) man page for details. If you are ever going
// to setup a primary server, make sure you've understood the hairy
// details of how DNS is working. Even with simple mistakes, you can
// break connectivity for affected parties, or cause huge amount of
// useless Internet traffic.
options {
directory "/etc/namedb";
// In addition to the "forwarders" clause, you can force your name
// server to never initiate queries of its own, but always ask its
// forwarders only, by enabling the following line:
//
// forward only;
// If you've got a DNS server around at your upstream provider, enter
// its IP address here, and enable the line below. This will make you
// benefit from its cache, thus reduce overall DNS traffic in the
Internet.
/*
forwarders {
127.0.0.1;
};
*/</programlisting>
<para>
Just as the comment says, if you want to benefit from your
uplink's cache, you can enable this section of the config file.
Normally, your nameserver will recursively query different
nameservers until it finds the answer it is looking for. Having
this enabled will have it automatically see if your
uplink's (or whatever provided) ns has the requested query.
If your uplink has a heavily trafficked, fast nameserver,
enabling this properly could work to your advantage.
127.0.0.1 will *NOT* work here; change this to the IP of a
nameserver at your uplink.
</para>
<programlisting> /*
* If there is a firewall between you and nameservers you want
* to talk to, you might need to uncomment the query-source
* directive below. Previous versions of BIND always asked
* questions using port 53, but BIND 8.1 uses an unprivileged
* port by default.
*/
// query-source address * port 53;
/*
* If running in a sandbox, you may have to specify a different
* location for the dumpfile.
*/
// dump-file "s/named_dump.db";
};
// Note: the following will be supported in a future release.
/*
host { any; } {
topology {
127.0.0.0/8;
};
};
*/
// Setting up secondaries is way easier and the rough picture for this
// is explained below.
//
// If you enable a local name server, don't forget to enter 127.0.0.1
// into your /etc/resolv.conf so this server will be queried first.
// Also, make sure to enable it in /etc/rc.conf.
zone "." {
type hint;
file "named.root";
};
zone "0.0.127.IN-ADDR.ARPA" {
type master;
file "localhost.rev";
};
zone
"0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.INT" {
type master;
file "localhost.rev";
};
// NB: Do not use the IP addresses below, they are faked, and only
// serve demonstration/documentation purposes!
//
// Example secondary config entries. It can be convenient to become
// a secondary at least for the zone where your own domain is in. Ask
// your network administrator for the IP address of the responsible
// primary.
//
// Never forget to include the reverse lookup (IN-ADDR.ARPA) zone!
// (This is the first bytes of the respective IP address, in reverse
// order, with ".IN-ADDR.ARPA" appended.)
//
// Before starting to setup a primary zone, better make sure you fully
// understand how DNS and BIND works, however. There are sometimes
// unobvious pitfalls. Setting up a secondary is comparably simpler.
//
// NB: Don't blindly enable the examples below. :-) Use actual names
// and addresses instead.
//
// NOTE!!! FreeBSD runs bind in a sandbox (see named_flags in rc.conf).
// The directory containing the secondary zones must be write accessible
// to bind. The following sequence is suggested:
//
// mkdir /etc/namedb/s
// chown bind:bind /etc/namedb/s
// chmod 750 /etc/namedb/s
/*
zone "domain.com" {
type slave;
file "s/domain.com.bak";
masters {
192.168.1.1;
};
};
zone "0.168.192.in-addr.arpa" {
type slave;
file "s/0.168.192.in-addr.arpa.bak";
masters {
192.168.1.1;
};
};
*/</programlisting>
<para>
These are example slave entries, read below to see more.
</para>
<para>
For each new domain added to your nameserver, you must add one
of these entries to your <filename>named.conf</filename>
</para>
<para>
The simplest zone entry, can look like
</para>
<programlisting>zone "foobardomain.org" {
type master;
file "foorbardomain.org";
};</programlisting>
<para>For a master entry with the zone information within
foobardomain.org, or
</para>
<programlisting>zone "foobardomain.org" {
type slave;
file "foobardomain.org";
};</programlisting>
<para>
for a slave. Note that slave zones automatically query the
listed master (authoritative) name servers for the zone file.
</para>
</sect3>
<sect3>
<title>Zone files</title>
<para>
An example master 'foobardomain.org' (existing within
/etc/namedb/foobardomain.org) is as follows:
</para>
<programlisting>$TTL 3600
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ) ; Minimum TTL
; DNS Servers
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
; Machine Names
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
; Aliases
www IN CNAME @
; MX Record
@ IN MX 10 mail.foobardomain.org.</programlisting>
<para>
Note that every hostname ending in a '.' is an exact
hostname, whereas everything without a trailing '.' is
referenced to the origin. For example, www is translated
into www + origin. In our fictitious zone file, our origin
is foobardomain.org, so www would be www.foobardomain.org.
</para>
<para>
The format of this file follows:
</para>
<programlisting>recordname IN recordtype value</programlisting>
+ <indexterm><primary>DNS</primary><secondary>records</secondary></indexterm>
<para>
The most commonly used DNS records:
</para>
<para><emphasis>SOA</emphasis> - start of zone authority</para>
<para><emphasis>NS</emphasis> - an authoritative nameserver</para>
<para><emphasis>A</emphasis> - A host address</para>
<para><emphasis>CNAME</emphasis> - the canonical name for an
alias</para>
<para><emphasis>MX</emphasis> - mail exchange</para>
<para><emphasis>PTR</emphasis> - a domain name pointer (used in
reverse dns)</para>
<programlisting>
foobardomain.org. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh after 3 hours
3600 ; Retry after 1 hour
604800 ; Expire after 1 week
86400 ) ; Minimum TTL of 1 day
</programlisting>
<para>
<emphasis>foobardomain.org.</emphasis> - the domain name, also
the origin for this zone file.
</para>
<para><emphasis>ns1.foobardomain.org.</emphasis> - the
primary/authoritative nameserver for this zone
</para>
<para><emphasis>admin.foobardomain.org.</emphasis> - the
responsible person for this zone, e-mail address with @
replaced. (admin@foobardomain.org becomes admin.foobardomain.org)
</para>
<para>
<emphasis>5</emphasis> - the serial number of the file. this
must
be incremented each time the zone file is modified. Nowadays,
many admins prefer a yyyymmddrr format for the serial number.
2001041002 would mean last modified 04/10/2001, the latter 02 being
the second time the zone file has been modified this day. The
serial number is important as it alerts slave nameservers for a zone
when it is updated.
</para>
<programlisting>
@ IN NS ns1.foobardomain.org.
</programlisting>
<para>
This is an NS entry. Every nameserver that is going to reply
authoritatively for the zone must have one of these entries.
The @ as seen here could have been 'foobardomain.org.' The @
translates to the origin.
</para>
<programlisting>
localhost IN A 127.0.0.1
ns1 IN A 3.2.1.2
ns2 IN A 3.2.1.3
mail IN A 3.2.1.10
@ IN A 3.2.1.30
</programlisting>
<para>
The A record indicates machine names. As seen above,
ns1.foobardomain.org would resolve to 3.2.1.2. Again, the
origin symbol, @, is used here, thus meaning foobardomain.org would
resolve to 3.2.1.30.
</para>
<programlisting>
www IN CNAME @
</programlisting>
<para>
The canonical name record is usually used for giving aliases
to a machine. In the example, www is aliased to the machine
addressed to the origin, or foobardomain.org (3.2.1.30).
CNAMEs can be used to provide alias hostnames, or round
robin one hostname among multiple machines.
</para>
<programlisting>
@ IN MX 10 mail.foobardomain.org.
</programlisting>
<para>
The MX record indicates which mail servers are responsible
for handling incoming mail for the zone.
mail.foobardomain.org is the hostname of the mail server,
and 10 being the priority of that mailserver.
</para>
<para>
One can have several mailservers, with priorities of 3, 2,
1. A mail server attempting to deliver to foobardomain.org
would first try the highest priority MX, then the second
highest, etc, until the mail can be properly delivered.
</para>
<para>
For in-addr.arpa zone files (reverse dns), the same format is
used, except with PTR entries instead of A or CNAME.
</para>
<programlisting>$TTL 3600
1.2.3.in-addr.arpa. IN SOA ns1.foobardomain.org. admin.foobardomain.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
@ IN NS ns1.foobardomain.org.
@ IN NS ns2.foobardomain.org.
2 IN PTR ns1.foobardomain.org.
3 IN PTR ns2.foobardomain.org.
10 IN PTR mail.foobardomain.org.
30 IN PTR foobardomain.org.</programlisting>
<para>
This file gives the proper IP to hostname mappings of our above
fictitious domain.
</para>
</sect3>
</sect2>
<sect2>
<title>Caching Name Server</title>
+ <indexterm><primary>BIND</primary><secondary>caching name server</secondary></indexterm>
<para>
A caching nameserver is simply a nameserver that is not
authoritative for any zones. It simply asks queries of its own,
and remembers them for later use. To set one up, just configure
the name server as usual, omitting any inclusions of zones.
</para>
</sect2>
<sect2 id="named-sandbox">
<title>Running named in a Sandbox</title>
-
+ <indexterm><primary>BIND</primary><secondary>running in a sandbox</secondary></indexterm>
<para><emphasis>Contributed by Mike Makonnen
<email>mike_makonnen@yahoo.com</email>, May 1, 2001</emphasis>
</para>
+ <indexterm><primary>chroot</primary></indexterm>
<para>For added security you may want to run &man.named.8; in a
sandbox. This will reduce the potential damage should it be
compromised. If you include a sandbox directory in its command
line, named will &man.chroot.8;
into that directory immediately upon finishing processing its
command line. It is also a good idea to have named run as a
non-privileged user in the sandbox. The default FreeBSD install
contains a user bind with group bind. If we wanted the sandbox in
the <filename>/etc/namedb/sandbox</filename> directory the command
line for named would look like this:
</para>
<screen> &prompt.root; <userinput>/usr/sbin/named -u bind -g bind -t /etc/namedb/sandbox <path_to_named.conf> </userinput>
</screen>
<para>The following steps should be taken in order to
successfully run named in a sandbox. Throughout the following
discussion we will assume the path to your sandbox is
<filename>/etc/namedb/sandbox</filename>
</para>
<itemizedlist>
<listitem>
<para>Create the sandbox directory:
<filename>/etc/namedb/sandbox</filename></para>
</listitem>
<listitem>
<para>Create other necessary directories off of the sandbox
directory: <filename>etc</filename> and
<filename>var/run</filename></para>
</listitem>
<listitem>
<para>copy <filename>/etc/localtime</filename> to
<filename>sandbox/etc</filename>
</para>
</listitem>
<listitem>
<para>make bind:bind the owner of all files and directories in
the sandbox:
<screen>&prompt.root; <userinput>chown -R bind:bind /etc/namedb/sandbox</userinput> </screen>
<screen>&prompt.root; <userinput>chmod -R 750 /etc/namedb/sandbox</userinput> </screen>
</para>
</listitem>
</itemizedlist>
<para>There are some issues you need to be aware of when running
named in a sandbox.</para>
<itemizedlist>
<listitem>
<para>Your &man.named.conf.5; file and all your zone files must
be in the sandbox
</para>
</listitem>
<listitem>
<para><filename>sandbox/etc/localtime</filename> is needed
in order to have the correct time for your time zone in
log messages.</para>
</listitem>
<listitem>
<para> &man.named.8; will write its process id to a file in
<filename>sandbox/var/run</filename></para>
</listitem>
<listitem>
<para>The Unix socket used for communication by the &man.ndc.8;
utility will be created in
<filename>sandbox/var/run</filename></para>
</listitem>
<listitem>
<para>When using the ndc utility you need to specify the
location of the Unix socket created in the sandbox, by
&man.named.8;, by using the -c switch:
<command>&prompt.root; ndc -c /etc/namedb/sandbox/var/run/ndc</command>
</para>
</listitem>
<listitem>
<para>If you enable logging to file, the log files must be
in the sandbox</para>
</listitem>
</itemizedlist>
<para>&man.named.8; can be started in a sandbox properly, if the
following is in <filename>/etc/rc.conf</filename>
</para>
<programlisting>named_flags="-u bind -g bind -t /etc/namedb/sandbox"</programlisting>
</sect2>
<sect2>
<title>How to use the nameserver</title>
<para>If setup properly, the nameserver should be accessible through
the network and locally. <filename>/etc/resolv.conf</filename> must
contain a nameserver entry with the local ip so it will query the
local name server first.
</para>
<para>
To access it over the network, the machine must have the
nameserver's IP address set properly in its own nameserver
configuration options.
</para>
</sect2>
<sect2>
<title>Security</title>
<para>Although BIND is the most common implementation of DNS,
there is always the issue of security. Possible and
exploitable security holes are sometimes found.
</para>
<para>
It is a good idea to subscribe to <ulink
url="http://www.cert.org">CERT</ulink> and
<ulink url="http://www.freebsd.org/handbook/eresources.html#ERESOURCES-MAIL">freebsd-announce</ulink>
to stay up to date with the current Internet and FreeBSD security
issues.
</para>
<para>
If a problem arises, keeping your sources up to date and having a
fresh build of named can't hurt.
</para>
</sect2>
<sect2>
<title>Further Reading</title>
<para>
&man.ndc.8; &man.named.8; &man.named.conf.5;
</para>
<para>
Official ISC BIND Page
<ulink url="http://www.isc.org/products/BIND/">http://www.isc.org/products/BIND/</ulink>
</para>
<para>
BIND FAQ
<ulink url="http://www.nominum.com/resources/faqs/bind-faqs.html">
http://www.nominum.com/resources/faqs/bind-faqs.html</ulink>
</para>
<para>
<ulink url="http://www.oreilly.com/catalog/dns4/">O'Reilly DNS and BIND 4th Edition</ulink>
</para>
<para>
<ulink url="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1034.txt">RFC1034 - Domain Names -
Concepts and Facilities</ulink>
</para>
<para>
<ulink url="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1035.txt">RFC1035 - Domain Names -
Implementation and Specification</ulink>
</para>
</sect2>
</sect1>
<sect1 id="natd">
<title>Network Address Translation daemon (natd)</title>
<para><emphasis>Contributed by &a.chern;, June 2001.
</emphasis>
</para>
<sect2 id="overview">
<title>Overview</title>
+ <indexterm><primary>natd</primary></indexterm>
<para>FreeBSD's Network Address Translation daemon, commonly known as
&man.natd.8; is a daemon that accepts incoming raw IP packets,
changes the source to the local machine and re-injects these packets
back into the outgoing IP packet stream. natd does this by changing
the source ip and port such that when data is received back, it is
able to determine the original location of the data and forward it
back to its original requestor.</para>
-
+ <indexterm><primary>Internet connection sharing</primary></indexterm>
+ <indexterm><primary>IP masquerading</primary></indexterm>
<para>The most common use of NAT is to perform what is commonly known as
Internet Connection Sharing.</para>
</sect2>
<sect2 id="setup">
<title>Setup</title>
<para>Due to the diminishing ip space in ipv4, and the increased number
of users on high-speed consumer lines such as cable or DSL, people are
in more and more need of an Internet Connection Sharing solution. The
ability to connect several computers online through one connection and
ip makes &man.natd.8; a reasonable choice.</para>
<para>Most commonly, a user has a machine connected to a cable or DSL
line with one ip and wishes to use this one connected computer to
provide internet access to several more over a LAN.</para>
<para>To do this, the FreeBSD machine on the Internet must act as a
gateway. This gateway machine must have two NICs--one for connecting
to the Internet router, the other connecting to a LAN. All the
machines on the LAN are connected through a hub or switch.</para>
<mediaobject>
<imageobject>
<imagedata fileref="advanced-networking/natd">
</imageobject>
<textobject>
<literallayout class="monospaced"> _______ __________ ________
| | | | | |
| Hub |-----| Client B |-----| Router |----- Internet
|_______| |__________| |________|
|
____|_____
| |
| Client A |
|__________|</literallayout>
</textobject>
<textobject>
<phrase>Network Layout</phrase>
</textobject>
</mediaobject>
<para>With this setup, the machine without Internet access can use
the machine with access as a gateway to access the outside
world.</para>
</sect2>
<sect2 id="configuration">
+ <indexterm><primary>kernel</primary><secondary>configuration</secondary></indexterm>
<title>Configuration</title>
<para>The following options must be in the kernel configuration
file:</para>
<programlisting>options IPFIREWALL
options IPDIVERT</programlisting>
<para>Additionally, at choice, the following may also be suitable:</para>
<programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT
options IPFIREWALL_VERBOSE</programlisting>
<para>The following must be in <filename>/etc/rc.conf</filename>:</para>
<programlisting>gateway_enable="YES"
firewall_enable="YES"
firewall_type="OPEN"
natd_enable="YES"
natd_interface="<replaceable>fxp0</replaceable>"
natd_flags=""</programlisting>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry>gateway_enable="YES"</entry>
<entry>Sets up the machine to act as a gateway. Running
<command>sysctl -w net.inet.ip.forwarding=1</command>
would have the same effect.</entry>
</row>
<row><entry>firewall_enable="YES"</entry>
<entry>Enables the firewall rules in
<filename>/etc/rc.firewall</filename> at boot.</entry>
</row>
<row><entry>firewall_type="OPEN"</entry>
<entry>This specifies a predefined firewall ruleset that
allows anything in. See
<filename>/etc/rc.firewall</filename> for additional
types.</entry>
</row>
<row>
<entry>natd_interface="fxp0"</entry>
<entry>Indicates which interface to forward packets through.
(the interface connected to the Internet)</entry>
</row>
<row>
<entry>natd_flags=""</entry>
<entry>Any additional configuration options passed to
&man.natd.8; on boot.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Having the previous options defined in
<filename>/etc/rc.conf</filename> would run
<command>natd -interface fxp0</command> at boot. This can also
be run manually.</para>
<para>Each machine and interface behind the LAN should be assigned ip
numbers in the private network space as defined by
<ulink url="http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1918.txt">RFC 1918</ulink>
and have a default gateway of the natd machine's internal ip.</para>
<para>For example, client a and b behind the LAN have ips of 192.168.0.2
and 192.168.0.3, while the natd machine's LAN interface has an ip of
192.168.0.1. Client a and b's default gateway must be set to that of
the natd machine, 192.168.0.1. The natd machine's external, or
Internet interface does not require any special modification for natd
to work.</para>
</sect2>
<sect2 id="port-redirection">
<title>Port Redirection</title>
<para>The drawback with natd is that the LAN clients are not accessible
from the Internet. Clients on the LAN can make outgoing connections to
the world but cannot receive incoming ones. This presents a problem
if trying to run Internet services on one of the LAN client machines.
A simple way around this is to redirect selected Internet ports on the
natd machine to a LAN client.
</para>
<para>For example, an IRC server runs on Client A, and a web server runs
on Client B. For this to work properly, connections received on ports
6667 (irc) and 80 (web) must be redirected to the respective machines.
</para>
<para>The <command>-redirect_port</command> must be passed to
&man.natd.8; with the proper options. The syntax is as follows:</para>
<para><programlisting> -redirect_port proto targetIP:targetPORT[-targetPORT]
[aliasIP:]aliasPORT[-aliasPORT]
[remoteIP[:remotePORT[-remotePORT]]]</programlisting></para>
<para>In the above example, the argument should be:
<programlisting> -redirect_port tcp 192.168.0.2:6667 6667
-redirect_port tcp 192.168.0.3:80 80</programlisting>
This will redirect the proper <emphasis>tcp</emphasis> ports to the
LAN client machines.
</para>
<para>The -redirect_port argument can be used to indicate port
ranges over individual ports. For example, <replaceable>tcp
192.168.0.2:2000-3000 2000-3000</replaceable> would redirect
all connections received on ports 2000 to 3000 to ports 2000
to 3000 on Client A.</para>
<para>These options can be used when directly running
&man.natd.8; or placed within the
<programlisting>natd_flags=""</programlisting> option in
<filename>/etc/rc.conf</filename>.</para>
<para>For further configuration options, consult &man.natd.8;</para>
</sect2>
<sect2 id="address-redirection">
<title>Address Redirection</title>
+ <indexterm><primary>address redirection</primary></indexterm>
<para>Address redirection is useful if several ips are available, yet
they must be on one machine. With this, &man.natd.8; can assign each
LAN client its own external ip. &man.natd.8; then rewrites outgoing
packets from the LAN clients with the proper external ip and redirects
all traffic incoming on that particular ip back to the specific LAN
client. This is also known as static NAT. For example, the ips
128.1.1.1, 128.1.1.2, and 128.1.1.3 belong to the natd gateway
machine. 128.1.1.1 can be used as the natd gateway machine's external
ip address, while 128.1.1.2 and 128.1.1.3 are forwarded back to LAN
clients A and B.</para>
<para>The -redirect_address syntax is as follows:</para>
<para><programlisting> -redirect_address localIP publicIP</programlisting>
</para>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry>localIP</entry>
<entry>The internal ip of the LAN client.</entry>
</row>
<row>
<entry>publicIP</entry>
<entry>The external ip corresponding to the LAN client.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>In the example, this argument would read:</para>
<programlisting> -redirect_address 192.168.0.2 128.1.1.2
-redirect_address 192.168.0.3 128.1.1.3</programlisting>
<para>Like -redirect_port, these arguments are also placed within
natd_flags of <filename>/etc/rc.conf</filename>. With address
redirection, there is no need for port redirection since all data
received on a particular ip address is redirected.</para>
<para>The external ips on the natd machine must be active and aliased
to the external interface. Look at &man.rc.conf.5; to do so.</para>
</sect2>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
<!-- LocalWords: config mnt www -->