os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
doc/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml

6514 lines
248 KiB
Text
Raw Blame History

<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="advanced-networking">
<title>Advanced Networking</title>
<sect1>
<title>Synopsis</title>
<para>This chapter will cover some of the more frequently used network
services on Unix systems. We will cover how to define, setup, test and
maintain all of the network services that FreeBSD utilizes. In addition,
there have been example configuration files included throughout this
chapter for you to benefit from.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>The basics of gateways and routes.</para>
</listitem>
<listitem>
<para>How to make FreeBSD act as a bridge.</para>
</listitem>
<listitem>
<para>How to setup a network filesystem.</para>
</listitem>
<listitem>
<para>How to setup network booting on a diskless machine.</para>
</listitem>
<listitem>
<para>How to setup a network information server for sharing user
accounts.</para>
</listitem>
<listitem>
<para>How to setup automatic network settings using DHCP.</para>
</listitem>
<listitem>
<para>How to setup a domain name server.</para>
</listitem>
<listitem>
<para>How to synchronize the time and date, and setup a
time server, with the NTP protocol.</para>
</listitem>
<listitem>
<para>How to setup network address translation.</para>
</listitem>
<listitem>
<para>How to manage the <command>inetd</command> daemon.</para>
</listitem>
<listitem>
<para>How to connect two computers via PLIP.</para>
</listitem>
<listitem>
<para>How to setup IPv6 on a FreeBSD machine.</para>
</listitem>
</itemizedlist>
<para>Before reading this chapter, you should:</para>
<itemizedlist>
<listitem>
<para>Understand the basics of the <filename>/etc/rc</filename> scripts.</para>
</listitem>
<listitem>
<para>Be familiar with basic network terminology.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="routing">
<sect1info>
<authorgroup>
<author>
<firstname>Coranth</firstname>
<surname>Gryphon</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Gateways and Routes</title>
<indexterm><primary>routing</primary></indexterm>
<indexterm><primary>gateway</primary></indexterm>
<indexterm><primary>subnet</primary></indexterm>
<para>For one machine to be able to find another over a network, there
must be a
mechanism in place to describe how to get from one to the other. This is
called <firstterm>routing</firstterm>. A <quote>route</quote> is a defined pair of addresses: a
<quote>destination</quote> and a <quote>gateway</quote>. The pair
indicates that if you are trying to get to this
<emphasis>destination</emphasis>, communicate through this
<emphasis>gateway</emphasis>. There are three types of destinations:
individual hosts, subnets, and <quote>default</quote>. The
<quote>default route</quote> is used if none of the other routes apply.
We will talk a little bit more about default routes later on. There are
also three types of gateways: individual hosts, interfaces (also called
<quote>links</quote>), and Ethernet hardware addresses (MAC addresses).
</para>
<sect2>
<title>An Example</title>
<para>To illustrate different aspects of routing, we will use the
following example from <command>netstat</command>:</para>
<screen>&prompt.user; <userinput>netstat -r</userinput>
Routing tables
Destination Gateway Flags Refs Use Netif Expire
default outside-gw UGSc 37 418 ppp0
localhost localhost UH 0 181 lo0
test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77
10.20.30.255 link#1 UHLW 1 2421
example.com link#1 UC 0 0
host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0
host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 =>
host2.example.com link#1 UC 0 0
224 link#1 UC 0 0</screen>
<indexterm><primary>default route</primary></indexterm>
<para>The first two lines specify the default route (which we
will cover in the <link linkend="routing-default">next
section</link>) and the <hostid>localhost</hostid> route.</para>
<indexterm><primary>loopback device</primary></indexterm>
<para>The interface (<literal>Netif</literal> column) that this routing table specifies
to use for <literal>localhost</literal> is
<devicename>lo0</devicename>, also known as the loopback device. This
says to keep all traffic for this destination internal, rather than
sending it out over the LAN, since it will only end up back where it
started.</para>
<indexterm>
<primary>Ethernet</primary>
<secondary>MAC address</secondary>
</indexterm>
<para>The next thing that stands out are the addresses beginning
with <hostid role="mac">0:e0:</hostid>. These are Ethernet
hardware addresses, which are also known as MAC addresses.
FreeBSD will automatically identify any hosts
(<hostid>test0</hostid> in the example) on the local Ethernet and add
a route for that host, directly to it over the Ethernet interface,
<devicename>ed0</devicename>. There is also a timeout
(<literal>Expire</literal> column) associated with this type of route,
which is used if we fail to hear from the host in a specific amount of
time. When this happens, the route to this host will be automatically deleted. These
hosts are identified using a mechanism known as RIP (Routing
Information Protocol), which figures out routes to local hosts based
upon a shortest path determination.</para>
<indexterm><primary>subnet</primary></indexterm>
<para>FreeBSD will also add subnet routes for the local subnet (<hostid
role="ipaddr">10.20.30.255</hostid> is the broadcast address for the
subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid
role="domainname">example.com</hostid> is the domain name associated
with that subnet). The designation <literal>link#1</literal> refers
to the first Ethernet card in the machine. You will notice no
additional interface is specified for those.</para>
<para>Both of these groups (local network hosts and local subnets) have
their routes automatically configured by a daemon called
<application>routed</application>. If this is not run, then only
routes which are statically defined (i.e. entered explicitly) will
exist.</para>
<para>The <literal>host1</literal> line refers to our host, which it
knows by Ethernet address. Since we are the sending host, FreeBSD
knows to use the loopback interface (<devicename>lo0</devicename>)
rather than sending it out over the Ethernet interface.</para>
<para>The two <literal>host2</literal> lines are an example of what
happens when we use an &man.ifconfig.8; alias (see the section on Ethernet for
reasons why we would do this). The <literal>=&gt;</literal> symbol
after the <devicename>lo0</devicename> interface says that not only
are we using the loopback (since this address also refers to the
local host), but specifically it is an alias. Such routes only show
up on the host that supports the alias; all other hosts on the local
network will simply have a <literal>link#1</literal> line for
such routes.</para>
<para>The final line (destination subnet <literal>224</literal>) deals
with multicasting, which will be covered in another section.</para>
<para>Finally, various attributes of each route can be seen in the
<literal>Flags</literal> column. Below is a short table of some of these
flags and their meanings:</para>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry>U</entry>
<entry>Up: The route is active.</entry>
</row>
<row>
<entry>H</entry>
<entry>Host: The route destination is a single host.</entry>
</row>
<row>
<entry>G</entry>
<entry>Gateway: Send anything for this destination on to this
remote system, which will figure out from there where to send
it.</entry>
</row>
<row>
<entry>S</entry>
<entry>Static: This route was configured manually, not
automatically generated by the system.</entry>
</row>
<row>
<entry>C</entry>
<entry>Clone: Generates a new route based upon this route for
machines we connect to. This type of route is normally used
for local networks.</entry>
</row>
<row>
<entry>W</entry>
<entry>WasCloned: Indicated a route that was auto-configured
based upon a local area network (Clone) route.</entry>
</row>
<row>
<entry>L</entry>
<entry>Link: Route involves references to Ethernet
hardware.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2 id="routing-default">
<title>Default Routes</title>
<indexterm><primary>default route</primary></indexterm>
<para>When the local system needs to make a connection to a remote host,
it checks the routing table to determine if a known path exists. If
the remote host falls into a subnet that we know how to reach (Cloned
routes), then the system checks to see if it can connect along that
interface.</para>
<para>If all known paths fail, the system has one last option: the
<quote>default</quote> route. This route is a special type of gateway
route (usually the only one present in the system), and is always
marked with a <literal>c</literal> in the flags field. For hosts on a
local area network, this gateway is set to whatever machine has a
direct connection to the outside world (whether via PPP link,
DSL, cable modem, T1, or another network interface).</para>
<para>If you are configuring the default route for a machine which
itself is functioning as the gateway to the outside world, then the
default route will be the gateway machine at your Internet Service
Provider's (ISP) site.</para>
<para>Let us look at an example of default routes. This is a common
configuration:</para>
<literallayout>
[Local2] &lt;--ether--&gt; [Local1] &lt;--PPP--&gt; [ISP-Serv] &lt;--ether--&gt; [T1-GW]
</literallayout>
<para>The hosts <hostid>Local1</hostid> and
<hostid>Local2</hostid> are at your site.
<hostid>Local1</hostid> is connected to an ISP via a dial up
PPP connection. This PPP server computer is connected through
a local area network to another gateway computer through an
external interface to the ISPs Internet feed.</para>
<para>The default routes for each of your machines will be:</para>
<informaltable frame="none">
<tgroup cols="3">
<thead>
<row>
<entry>Host</entry>
<entry>Default Gateway</entry>
<entry>Interface</entry>
</row>
</thead>
<tbody>
<row>
<entry>Local2</entry>
<entry>Local1</entry>
<entry>Ethernet</entry>
</row>
<row>
<entry>Local1</entry>
<entry>T1-GW</entry>
<entry>PPP</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>A common question is <quote>Why (or how) would we set
the <hostid>T1-GW</hostid> to be the default gateway for
<hostid>Local1</hostid>, rather than the ISP server it is
connected to?</quote>.</para>
<para>Remember, since the PPP interface is using an address on the ISP's
local network for your side of the connection, routes for any other
machines on the ISP's local network will be automatically generated.
Hence, you will already know how to reach the <hostid>T1-GW</hostid>
machine, so there is no need for the intermediate step
of sending traffic to the ISP server.</para>
<para>As a final note, it is common to use the address <hostid
role="ipaddr">X.X.X.1</hostid> as the gateway address for your local
network. So (using the same example), if your local class-C address
space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was
using <hostid role="ipaddr">10.9.9</hostid> then the default routes
would be:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Host</entry>
<entry>Default Route</entry>
</row>
</thead>
<tbody>
<row>
<entry>Local2 (10.20.30.2)</entry>
<entry>Local1 (10.20.30.1)</entry>
</row>
<row>
<entry>Local1 (10.20.30.1, 10.9.9.30)</entry>
<entry>T1-GW (10.9.9.1)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect2>
<sect2>
<title>Dual Homed Hosts</title>
<indexterm><primary>dual homed hosts</primary></indexterm>
<para>There is one other type of configuration that we should cover, and
that is a host that sits on two different networks. Technically, any
machine functioning as a gateway (in the example above, using a PPP
connection) counts as a dual-homed host. But the term is really only
used to refer to a machine that sits on two local-area
networks.</para>
<para>In one case, the machine has two Ethernet cards, each having an
address on the separate subnets. Alternately, the machine may only
have one Ethernet card, and be using &man.ifconfig.8; aliasing. The former is
used if two physically separate Ethernet networks are in use, the
latter if there is one physical network segment, but two logically
separate subnets.</para>
<para>Either way, routing tables are set up so that each subnet knows
that this machine is the defined gateway (inbound route) to the other
subnet. This configuration, with the machine acting as a router
between the two subnets, is often used when we need to implement
packet filtering or firewall security in either or both
directions.</para>
<para>If you want this machine to actually forward packets
between the two interfaces, you need to tell FreeBSD to enable
this ability.</para>
</sect2>
<sect2 id="dedicated-router">
<title>Building a Router</title>
<indexterm><primary>router</primary></indexterm>
<para>A network router is simply a system that forwards packets
from one interface to another. Internet standards and good
engineering practice prevent the FreeBSD Project from enabling
this by default in FreeBSD. You can enable this feature by
changing the following variable to <literal>YES</literal> in
&man.rc.conf.5;:</para>
<programlisting>gateway_enable=YES # Set to YES if this host will be a gateway</programlisting>
<para>This option will set the &man.sysctl.8; variable
<filename>net.inet.ip.forwarding</filename> to
<literal>1</literal>. If you should need to stop routing
temporarily, you can reset this to <literal>0</literal> temporarily.</para>
<para>Your new router will need routes to know where to send the
traffic. If your network is simple enough you can use static
routes. FreeBSD also comes with the standard BSD routing
daemon &man.routed.8;, which speaks RIP (both version 1 and
version 2) and IRDP. For more complex situations you may want
to try <filename role="package">net/gated</filename>.</para>
<para>Even when FreeBSD is configured in this way, it does not
completely comply with the Internet standard requirements for
routers. It comes close enough for ordinary use,
however.</para>
</sect2>
<sect2>
<title>Routing Propagation</title>
<indexterm><primary>routing propagation</primary></indexterm>
<para>We have already talked about how we define our routes to the
outside world, but not about how the outside world finds us.</para>
<para>We already know that routing tables can be set up so that all
traffic for a particular address space (in our examples, a class-C
subnet) can be sent to a particular host on that network, which will
forward the packets inbound.</para>
<para>When you get an address space assigned to your site, your service
provider will set up their routing tables so that all traffic for your
subnet will be sent down your PPP link to your site. But how do sites
across the country know to send to your ISP?</para>
<para>There is a system (much like the distributed DNS information) that
keeps track of all assigned address-spaces, and defines their point of
connection to the Internet Backbone. The <quote>Backbone</quote> are
the main trunk lines that carry Internet traffic across the country,
and around the world. Each backbone machine has a copy of a master
set of tables, which direct traffic for a particular network to a
specific backbone carrier, and from there down the chain of service
providers until it reaches your network.</para>
<para>It is the task of your service provider to advertise to the
backbone sites that they are the point of connection (and thus the
path inward) for your site. This is known as route
propagation.</para>
</sect2>
<sect2>
<title>Troubleshooting</title>
<indexterm>
<primary><command>traceroute</command></primary>
</indexterm>
<para>Sometimes, there is a problem with routing propagation, and some
sites are unable to connect to you. Perhaps the most useful command
for trying to figure out where routing is breaking down is the
&man.traceroute.8; command. It is equally useful if you cannot seem
to make a connection to a remote machine (i.e. &man.ping.8;
fails).</para>
<para>The &man.traceroute.8; command is run with the name of the remote
host you are trying to connect to. It will show the gateway hosts
along the path of the attempt, eventually either reaching the target
host, or terminating because of a lack of connection.</para>
<para>For more information, see the manual page for
&man.traceroute.8;.</para>
</sect2>
</sect1>
<sect1 id="wireless">
<sect1info>
<authorgroup>
<author>
<firstname>Eric</firstname>
<surname>Anderson</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Wireless</title>
<sect2>
<title>Introduction</title>
<para>It can be very useful to be able to use a computer without the
annoyance of having a network cable attached at all times. FreeBSD can
be used as a wireless client, and even as a wireless <quote>access
point</quote>.</para>
</sect2>
<sect2>
<title>Wireless Devices</title>
<para>There are two main types of wireless devices: access points, and clients.<para>
<sect3>
<title>Access Points</title>
<para>Access points are wireless networking devices that allow one or more wireless
clients to use the device as a central hub. When using an access point, all
clients communicate through the access point. Multiple access points are often
used to cover a complete area such as a house, business, or park with a wireless
network.</para>
<para>Access points typically have multiple network connections: the wireless card,
and one or more wired ethernet adapters for connection to the rest of the network.
</para>
<para>Access points can either be purchased prebuilt, or you can build
your own with FreeBSD and a supported wireless card. Several vendors make
wireless access points and wireless cards with various features.</para>
</sect3>
<sect3>
<title>Building a FreeBSD Access Point</title>
<sect4><title>Requirements</title>
<para>In order to set up a wireless access point with FreeBSD, you need to have
a compatible wireless card. Currently, only cards with the Prism chipset are
supported. You will also need a wired network card that is supported by FreeBSD
(this should not be difficult to find, FreeBSD supports a lot of different
devices). For this guide, we will assume you want to &man.bridge.4; all traffic between
the wireless device and the network attached to the wired network card.</para>
</sect4>
<sect4>
<title>Setting it up</title>
<para>First, make sure your system can see the wireless card:</para>
<screen>&prompt.root; <userinput>ifconfig -a</userinput>
wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
ether 00:09:2d:2d:c9:50
media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
status: no carrier
ssid ""
stationname "FreeBSD Wireless node"
channel 10 authmode OPEN powersavemode OFF powersavesleep 100
wepmode OFF weptxkey 1</screen>
<para>Do not worry about the details now, just make sure it shows you
something to indicate you have a wireless card installed.</para>
<para>Next, you will need to load a module in order to get the bridging part
of FreeBSD ready for the access point. In order to load the &man.bridge.4; module,
simply run the following command:</para>
<screen>&prompt.root; <userinput>kldload bridge</userinput></screen>
<para>It should not have produced any errors when loading the module. If it
did, you may need to compile the &man.bridge.4; code into your kernel. The
<link linkend="bridging">Bridging</link> section of the handbook should be able
to help you accomplish that task.</para>
<para>Now that you have the bridging stuff done, we need to tell the FreeBSD
kernel which interfaces to bridge together. We do that by using &man.sysctl.8;:</para>
<screen>&prompt.root; <userinput>sysctl net.link.ether.bridge=1</userinput>
&prompt.root; <userinput>sysctl net.link.ether.bridge_cfg="wi0 xl0"</userinput>
&prompt.root; <userinput>sysctl net.inet.ip.forwarding=1</userinput></screen>
<para>Now it is time for the wireless card setup.</para>
<para>The following commands will set the card into BSS mode (turning it
into an access point):</para>
<screen>&prompt.root; <userinput>wicontrol -s "FreeBSD AP""</userinput>
&prompt.root; <userinput>ifconfig wi0 inet ssid my_net channel 11 media DS/11Mbps mediaopt hostap up</userinput>
<para>The first &man.wicontrol.8; command tells FreeBSD that the name of this access point
is <literal>FreeBSD AP</literal> by using the <option>-s</option> flag,
Check out &man.wicontrol.8; for more information.</para>
<para>The &man.ifconfig.8; line brings the <devicename>wi0</devicename> interface up, and sets its SSID to <literal>my_net</literal>.
This is a little redundant, but it is shown here to emphasize that you can do
these settings in either place. You will also notice a <option>mediaopt hostap</option> setting;
this setting is to tell &man.ifconfig.8; to put the interface into access point mode.
The <option>media DS/11Mbps</option> is needed so that the <option>mediaopt hostap</option> setting will become effective.
The <option>channel 11</option> sets the 802.11b channel to use. The &man.wicontrol.7;
man page has valid channel options for your regulatory domain.
</para>
<para>Now you should have a complete functioning access point up and running. You
are encouraged to read &man.wicontrol.8;, &man.ifconfig.8;, and &man.wi.4; for further information.
</para>
<para>It is also suggested that you read the section on encryption that follows.</para>
</sect4>
</sect3>
<sect3>
<title>Clients</title>
<para>A wireless client is a system that accesses an access point or another client
directly. </para>
<para>Typically, wireless clients only have one network device, the wireless
networking card.<para>
<para>There are a few different ways to configure a wireless client. These are based
on the different wireless modes, generally BSS (infrastructure mode, which requires an
access point), and IBSS (ad-hoc, or peer-to-peer mode). In our example, we will use the
most popular of the two, BSS mode, to talk to an access point.</para>
<sect4>
<title>Requirements</title>
<para>There is only one real requirement for setting up FreeBSD as a wireless client.
You will need a wireless card that is supported by FreeBSD.</para>
</sect4>
<sect4>
<title>Setting Up A Wireless FreeBSD Client</title>
<para>You will need to know a few things about the wireless network you are joining before
you start. In this example, we are joining a network that has a name of <literal>my_net</literal>, and
encryption turned off.</para>
<para>Note: In this example, we are not using encryption, which is a dangerous situation.
In the next section, you will learn how to turn on encryption, and why it is important to
do so, and why some encryption technologies still do not completely protect you.</para>
<para>Make sure your card is recognized by FreeBSD:</para>
<screen>&prompt.root; <userinput>ifconfig -a</userinput>
wi0: flags=8843&lt;UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
inet6 fe80::202:2dff:fe2d:c938%wi0 prefixlen 64 scopeid 0x7
inet 0.0.0.0 netmask 0xff000000 broadcast 255.255.255.255
ether 00:09:2d:2d:c9:50
media: IEEE 802.11 Wireless Ethernet autoselect (DS/2Mbps)
status: no carrier
ssid ""
stationname "FreeBSD Wireless node"
channel 10 authmode OPEN powersavemode OFF powersavesleep 100
wepmode OFF weptxkey 1</screen>
<para>Now, we will set the card to the correct settings for our network:</para>
<screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net</userinput></screen>
<para>Replace <hostid role="IPAddr">192.168.0.20</hostid> and <hostid role="Netmask">255.255.255.0</hostid> with a valid IP address and netmask on
your wired network. Remember, our access point is bridging the data between the
wireless network, and the wired network, so it will appear to the other devices on
your network that you are on the wired network just as they are.</para>
<para>Once you have done that, you should be able to ping hosts on the wired network
just as if you were connected using a standard wired connection.</para>
<para>If you are experiencing problems with your wireless connection, check to make
sure that your are associated (connected) to the access point:</para>
<screen>&prompt.root; <userinput>ifconfig wi0</userinput></screen>
<para>should return some information, and you should see:</para>
<screen>status: associated</screen>
<para>If it does not show associated, then you may be out of range of the access point, do not have
encryption on, or possibly have a configuration problem.</para>
</sect4>
</sect3>
<sect3>
<title>Encryption</title>
<para>Encryption on a wireless network is important because you no longer have the
ability to keep the network contained in a well protected area. Your wireless data
will be broadcast across your entire neighborhood, so anyone who cares to read it
can. This is where encryption comes in. By encrypting the data that is sent over
the airwaves, you make it much more difficult for any interested party to grab your
data right out of the air. </para>
<para>The two most common ways to encrypt the data between your client and the access
point, are WEP, and &man.ipsec.4;.</para>
<sect4>
<title>WEP</title>
<para>WEP is an abbreviation for Wired Equivalency Protocol. WEP is an attempt to
make wireless networks as safe and secure as a wired network. Unfortunately, it
has been cracked, and is fairly trivial to break. This also means it is not something
to rely on when it comes to encrypting sensitive data. </para>
<para>It is better than nothing, so use the following to turn on WEP on your new FreeBSD
access point:</para>
<screen>&prompt.root; <userinput>ifconfig wi0 inet up ssid my_net wepmode on wepkey 0x1234567890 media DS/11Mbps mediaopt hostap</userinput></screen>
<para>And you can turn on WEP on a client with this command:</para>
<screen>&prompt.root; <userinput>ifconfig wi0 inet 192.168.0.20 netmask 255.255.255.0 ssid my_net wepmode on wepkey 0x1234567890</userinput></screen>
<para>Note that you should replace the <literal>0x1234567890</literal> with a more unique key.</para>
</sect4>
<sect4>
<title>IPsec</title>
<para>&man.ipsec.4; is a much more robust and powerful tool for encrypting data across a
network. This is definitely the preferred way to encrypt wireless data over a
network. You can read more about &man.ipsec.4; security and how to implement it in the
<link linkend="ipsec">IPsec</link> section of the handbook.</para>
</sect4>
</sect3>
<sect3>
<title>Tools</title>
<para>There are a small number of tools available for use in debugging and setting
up your wireless network, and here we will attempt to describe some of them and what
they do.</para>
<sect4>
<title><application>bsd-airtools</application></title>
<para>The <application>bsd-airtools</application> package is a complete toolset that includes wireless auditing tools for WEP key
cracking, access point detection, etc.</para>
<para>The <application>bsd-airtools</application> utilities can be installed from the <filename role="package">net/bsd-airtools</filename> port. Information on
installing ports can be found in <xref linkend="ports"> of the handbook.<para>
<para>The program <command>dstumbler</command> is the packaged tool that allows for access point discovery and
signal to noise ratio graphing. If you are having a hard time getting your access
point up and running, <command>dstumbler</command> may help you get started.</para>
<para>To test your wireless network security, you may choose to use <quote>dweputils</quote> (<command>dwepcrack</command>, <command>dwepdump</command> and <command>dwepkeygen</command>) to
help you determine if WEP is the right solution to your wireless security needs.</para>
</sect4>
<sect4>
<title>wicontrol, ancontrol, raycontrol</title>
<para>These are the tools you use to control how your wireless card behaves on the
wireless network. In the examples above, we have chosen to use &man.wicontrol.8;, since our
wireless card is a <devicename>wi0</devicename> interface. If you had a Cisco wireless device, it would come
up as <devicename>an0</devicename>, and therefore you would use &man.ancontrol.8;.<para>
</sect4>
<sect4>
<title>ifconfig</title>
<para>&man.ifconfig.8; can be used to do many of the same options as &man.wicontrol.8;, however it
does lack a few options. Check &man.ifconfig.8; for command line parameters and options.</para>
</sect4>
</sect3>
<sect3>
<title>Supported Cards</title>
<sect4>
<title>Access Points</title>
<para>The only cards that are currently supported for BSS (as an access point) mode are
devices based on the Prism (or Prism 2, 2.5, 3) chipsets. For a complete list, look
at &man.wi.4;.</para>
</sect4>
<sect4>
<title>Clients</title>
<para>Almost all 802.11b wireless cards are currently supported under FreeBSD. Most
cards based on Prism, Spectrum24, Hermes, Aironet, and Raylink will work as a wireless
network card in IBSS (ad-hoc, peer-to-peer, and BSS) mode.</para>
</sect4>
</sect3>
</sect2>
</sect1>
<sect1 id="bridging">
<sect1info>
<authorgroup>
<author>
<firstname>Steve</firstname>
<surname>Peterson</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Bridging</title>
<sect2>
<title>Introduction</title>
<indexterm><primary>IP subnet</primary></indexterm>
<indexterm><primary>bridge</primary></indexterm>
<para>It is sometimes useful to divide one physical network (such as an
Ethernet segment) into two separate network segments without having
to create IP subnets and use a router to connect the segments
together. A device that connects two networks together in this
fashion is called a <quote>bridge</quote>. A FreeBSD system with two network
interface cards can act as a bridge.</para>
<para>The bridge works by learning the MAC layer addresses
(Ethernet addresses) of the devices on each of its network interfaces.
It forwards traffic between two networks only when its source and
destination are on different networks.</para>
<para>In many respects, a bridge is like an Ethernet switch with very
few ports.</para>
</sect2>
<sect2>
<title>Situations Where Bridging Is Appropriate</title>
<para>There are two common situations in which a bridge is used
today.</para>
<sect3>
<title>High Traffic on a Segment</title>
<para>Situation one is where your physical network segment is
overloaded with traffic, but you do not want for whatever reason to
subnet the network and interconnect the subnets with a
router.</para>
<para>Let us consider an example of a newspaper where the Editorial and
Production departments are on the same subnetwork. The Editorial
users all use server A for file service, and the Production users
are on server B. An Ethernet is used to connect all users together,
and high loads on the network are slowing things down.</para>
<para>If the Editorial users could be segregated on one network
segment and the Production users on another, the two network
segments could be connected with a bridge. Only the network traffic
destined for interfaces on the <quote>other</quote> side of the bridge would be
sent to the other network, reducing congestion on each network
segment.</para>
</sect3>
<sect3>
<title>Filtering/Traffic Shaping Firewall</title>
<indexterm><primary>firewall</primary></indexterm>
<indexterm><primary>IP Masquerading</primary></indexterm>
<para>The second common situation is where firewall functionality is
needed without IP Masquerading (NAT).</para>
<para>An example is a small company that is connected via DSL or ISDN
to their ISP. They have a 13 globally-accessible IP addresses
from their ISP and have 10 PCs on their network. In this situation, using a
router-based firewall is difficult because of subnetting
issues.</para>
<indexterm><primary>router</primary></indexterm>
<indexterm><primary>DSL</primary></indexterm>
<indexterm><primary>ISDN</primary></indexterm>
<para>A bridge-based firewall can be configured and dropped into the
path just downstream of their DSL/ISDN router without any IP
numbering issues.</para>
</sect3>
</sect2>
<sect2>
<title>Configuring a Bridge</title>
<sect3>
<title>Network Interface Card Selection</title>
<para>A bridge requires at least two network cards to function.
Unfortunately, not all network interface cards as of FreeBSD&nbsp;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 <varname>IPFIREWALL</varname> option as well. Read <xref
linkend="firewalls"> for general information on configuring the
bridge as a firewall.</para>
<para>If you need to allow non-IP packets (such as ARP) to flow
through the bridge, there is an undocumented firewall option that
must be set. This option is
<literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal>. Note that this
changes the default rule for the firewall to accept any packet.
Make sure you know how this changes the meaning of your ruleset
before you set it.</para>
</sect3>
<sect3>
<title>Traffic Shaping Support</title>
<para>If you want to use the bridge as a traffic shaper, you will need
to add the <literal>DUMMYNET</literal> option to your kernel
configuration. Read &man.dummynet.4; for further
information.</para>
</sect3>
</sect2>
<sect2>
<title>Enabling the Bridge</title>
<para>Add the line:</para>
<programlisting>net.link.ether.bridge=1</programlisting>
<para>to <filename>/etc/sysctl.conf</filename> to enable the bridge at
runtime, and the line:</para>
<programlisting>net.link.ether.bridge_cfg=<replaceable>if1</replaceable>,<replaceable>if2</replaceable></programlisting>
<para>to enable bridging on the specified interfaces (replace <replaceable>if1</replaceable> and
<replaceable>if2</replaceable> with the names of your two network interfaces). If you want the
bridged packets to be filtered by &man.ipfw.8;, you should add:</para>
<programlisting>net.link.ether.bridge_ipfw=1</programlisting>
<para>as well.</para>
</sect2>
<sect2>
<title>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 10&nbsp;mbps half duplex
and the connection between the bridge and my router (a Cisco 675) runs
at 100&nbsp;mbps full duplex. With no filtering enabled, I have found that
the bridge adds about 0.4&nbsp;milliseconds of latency to pings from the
protected 10&nbsp;mbps 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">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Reorganized and enhanced by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Bill</firstname>
<surname>Swingle</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
</sect1info>
<title>NFS</title>
<indexterm><primary>NFS</primary></indexterm>
<para>Among the many different filesystems that FreeBSD supports is
the Network File System, also known as <acronym>NFS</acronym>.
<acronym>NFS</acronym> allows a system to share directories and files
with others over a network. By using <acronym>NFS</acronym>, users and
programs can access files on remote systems almost as if they were local
files.</para>
<para>Some of the most notable benefits that <acronym>NFS</acronym> can provide are:</para>
<itemizedlist>
<listitem>
<para>Local workstations use less disk space because
commonly used data can be stored on a single machine and still
remain accessible to others over the network.</para>
</listitem>
<listitem>
<para>There is no need for users to have separate home directories
on every network machine. Home directories could be setup on the
<acronym>NFS</acronym> server and made available throughout
the network.</para>
</listitem>
<listitem>
<para>Storage devices such as floppy disks, CDROM drives, and
ZIP drives can be used by other machines on the network.
This may reduce the number of removable media drives
throughout the network.</para>
</listitem>
</itemizedlist>
<sect2>
<title>How <acronym>NFS</acronym> Works</title>
<para><acronym>NFS</acronym> consists of at least two main parts:
a server and one or more clients. The client remotely accesses
the data that is stored
on the server machine. In order for this to function properly a few
processes have to be configured and running:</para>
<para>The server has to be running the following daemons:</para>
<indexterm>
<primary>NFS</primary>
<secondary>server</secondary>
</indexterm>
<indexterm>
<primary><application>portmap</application></primary>
</indexterm>
<indexterm>
<primary><application>mountd</application></primary>
</indexterm>
<indexterm>
<primary><application>nfsd</application></primary>
</indexterm>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Daemon</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>nfsd</entry>
<entry>The <acronym>NFS</acronym> daemon which services requests from
the <acronym>NFS</acronym> clients.</entry>
</row>
<row>
<entry>mountd</entry>
<entry>The <acronym>NFS</acronym> mount daemon which carries out
the requests that &man.nfsd.8; passes on to it.</entry>
</row>
<row>
<entry>portmap</entry>
<entry> The portmapper daemon
allows <acronym>NFS</acronym> clients to discover which port the <acronym>NFS</acronym> server
is using.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The client can also run a daemon, known as
<application>nfsiod</application>. The <application>nfsiod</application>
daemon services the requests from the <acronym>NFS</acronym> server. This
is optional, and improves performance, but is not required for normal
and correct operation. See the &man.nfsiod.8; manual page for more information.
</para>
</sect2>
<sect2 id="configuring-nfs">
<title>Configuring <acronym>NFS</acronym></title>
<indexterm>
<primary>NFS</primary>
<secondary>configuration</secondary>
</indexterm>
<para><acronym>NFS</acronym> configuration is a relatively straightforward
process. The processes that need to be running can all start at boot time with
a few modifications to your <filename>/etc/rc.conf</filename>
file.</para>
<para>On the <acronym>NFS</acronym> server, make sure that the following options
are configured in the <filename>/etc/rc.conf</filename> file:</para>
<programlisting>portmap_enable="YES"
nfs_server_enable="YES"
mountd_flags="-r"</programlisting>
<para><command>mountd</command> runs automatically whenever the
<acronym>NFS</acronym> server is enabled.</para>
<para>On the client, make sure this option is present in
<filename>/etc/rc.conf</filename>:</para>
<programlisting>nfs_client_enable="YES"</programlisting>
<para>
The <filename>/etc/exports</filename>
file specifies which filesystems <acronym>NFS</acronym> should export (sometimes
referred to as <quote>share</quote>).
Each line in <filename>/etc/exports</filename> specifies a filesystem to be exported and
which machines have access to that filesystem. Along with what machines have access
to that filesystem, access options may also be specified. There are many such options
that can be used in this file but only a few will be mentioned here. You can easily discover
other options by reading over the &man.exports.5; manual page.</para>
<para>Here are a few example <filename>/etc/exports</filename>
entries:</para>
<indexterm>
<primary>NFS</primary>
<secondary>Examples of exporting filesystems</secondary>
</indexterm>
<para>The following examples give an idea of how to export filesystems,
although the settings may be different depending on
your environment and network configuration.
For instance, to export the <filename>/cdrom</filename> directory to
three example machines that have the same domain name as the server
(hence the lack of a domain name for each) or have entries in your
<filename>/etc/hosts</filename> file. The <option>-ro</option>
flag makes the exported filesystem read-only. With this flag, the
remote system will not be able to write any changes to the
exported filesystem.</para>
<programlisting>/cdrom -ro host1 host2 host3</programlisting>
<para>The following line exports <filename>/home</filename> to three
hosts by IP address. This is a useful setup if you have a
private network without a <acronym>DNS</acronym> server configured.
Optionally the <filename>/etc/hosts</filename> file could be configured
for internal hostnames; please review &man.hosts.5; for more
information. The <option>-alldirs</option> flag allows the subdirectories
to be mount points. In other words, it will not mount the subdirectories
but permit the client to mount only the directories that are required or
needed.</para>
<programlisting>/home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
<para>The following line exports <filename>/a</filename> so that two
clients from different domains may access the filesystem. The
<option>-maproot=root</option> flag allows the <username>root</username>
user on the remote system to write data on the exported filesystem as
<username>root</username>. If the <literal>-maproot=root</literal> flag is not specified, then even if
a user has <username>root</username> access on the remote system, they will not
be able to modify files on the exported filesystem.</para>
<programlisting>/a -maproot=root host.example.com box.example.org</programlisting>
<para>In order for a client to access an exported filesystem, the client must
have permission to do so. Make sure the client is listed in your
<filename>/etc/exports</filename> file.</para>
<para>In <filename>/etc/exports</filename>, each line represents
the export information for one filesystem to one host. A
remote host can only be specified once per filesystem, and may only
have one default entry. For example, assume that <filename>/usr</filename>
is a single filesystem. The following <filename>/etc/exports</filename>
would be invalid:</para>
<programlisting>/usr/src client
/usr/ports client</programlisting>
<para>One filesystem, <filename>/usr</filename>, has two lines
specifying exports to the same host, <hostid>client</hostid>.
The correct format for this situation is:</para>
<programlisting>/usr/src /usr/ports client</programlisting>
<para>The properties of one filesystem exported to a given host
must all occur on one line. Lines without a client specified
are treated as a single host. This limits how you can export
filesystems, but for most people this is not an issue.</para>
<para>The following is an example of a valid export list, where
<filename>/usr</filename> and <filename>/exports</filename>
are local filesystems:</para>
<programlisting># Export src and ports to client01 and client02, but only
# client01 has root privileges on it
/usr/src /usr/ports -maproot=root client01
/usr/src /usr/ports client02
# The client machines have root and can mount anywhere
# on /exports. Anyone in the world can mount /exports/obj read-only
/exports -alldirs -maproot=root client01 client02
/exports/obj -ro</programlisting>
<para>You must restart
<command>mountd</command> whenever you modify
<filename>/etc/exports</filename> so the changes can take effect.
This can be accomplished by sending the HUP signal
to the <command>mountd</command> process:</para>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
<para>Alternatively, a reboot will make FreeBSD set everything
up properly. A reboot is not necessary though.
Executing the following commands as <username>root</username>
should start everything up.</para>
<para>On the <acronym>NFS</acronym> server:</para>
<screen>&prompt.root; <userinput>portmap</userinput>
&prompt.root; <userinput>nfsd -u -t -n 4</userinput>
&prompt.root; <userinput>mountd -r</userinput></screen>
<para>On the <acronym>NFS</acronym> client:</para>
<screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen>
<para>Now everything should be ready to actually mount a remote file
system. In these examples the
server's name will be <literal>server</literal> and the client's
name will be <literal>client</literal>. If you only want to
temporarily mount a remote filesystem or would rather test the
configuration, just execute a command like this as <username>root</username> on the
client:</para>
<indexterm>
<primary>NFS</primary>
<secondary>mounting filesystems</secondary>
</indexterm>
<screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
<para>This will mount the <filename>/home</filename> directory
on the server at <filename>/mnt</filename> on the client. If
everything is set up correctly you should be able to enter
<filename>/mnt</filename> on the client and see all the files
that are on the server.</para>
<para>If you want to automatically mount a remote filesystem
each time the computer boots, add the filesystem to the
<filename>/etc/fstab</filename> file. Here is an example:</para>
<programlisting>server:/home /mnt nfs rw 0 0</programlisting>
<para>The &man.fstab.5; manual page lists all the available options.</para>
</sect2>
<sect2>
<title>Practical Uses</title>
<para><acronym>NFS</acronym> has many practical uses. Some of the more common
ones are listed below:</para>
<indexterm>
<primary>NFS</primary>
<secondary>uses</secondary>
</indexterm>
<itemizedlist>
<listitem>
<para>Set several machines to share a CDROM or
other media among them. This is cheaper and often
a more convenient method to install software on multiple machines.</para>
</listitem>
<listitem>
<para>On large networks, it might be more convenient to configure a
central <acronym>NFS</acronym> server in which to store all the user
home directories. These home directories can then be exported to
the network so that users would always have the same home directory,
regardless of which workstation they log in to.</para>
</listitem>
<listitem>
<para>Several machines could have a common
<filename>/usr/ports/distfiles</filename> directory.
That way, when you need to install a port on several machines, you can
quickly access the source without downloading it on each machine.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="amd">
<sect2info>
<authorgroup>
<author>
<firstname>Wylie</firstname>
<surname>Stilwell</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Chern</firstname>
<surname>Lee</surname>
<contrib>Rewritten by </contrib>
</author>
</authorgroup>
</sect2info>
<title>amd</title>
<indexterm><primary>amd</primary></indexterm>
<indexterm><primary>automatic mounter daemon</primary></indexterm>
<para>&man.amd.8; (the automatic mounter daemon)
automatically mounts a
remote filesystem whenever a file or directory within that
filesystem is accessed. Filesystems that are inactive for a
period of time will also be automatically unmounted by
<application>amd</application>. Using
<application>amd</application> provides a simple alternative
to permanent mounts, as permanent mounts are usually listed in
<filename>/etc/fstab</filename>.</para>
<para><application>amd</application> operates by attaching
itself as an NFS server to the <filename>/host</filename> and
<filename>/net</filename> directories. When a file is accessed
within one of these directories, <application>amd</application>
looks up the corresponding remote mount and automatically mounts
it. <filename>/net</filename> is used to mount an exported
filesystem from an IP address, while <filename>/host</filename>
is used to mount an export from a remote hostname.</para>
<para>An access to a file within
<filename>/host/foobar/usr</filename> would tell
<application>amd</application> to attempt to mount the
<filename>/usr</filename> export on the host
<hostid>foobar</hostid>.</para>
<example>
<title>Mounting an Export with <application>amd</application></title>
<para>You can view the available mounts of a remote host with
the <command>showmount</command> command. For example, to
view the mounts of a host named <hostid>foobar</hostid>, you
can use:</para>
<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
Exports list on foobar:
/usr 10.10.10.0
/a 10.10.10.0
&prompt.user; cd /host/foobar/usr</screen>
</example>
<para>As seen in the example, the <command>showmount</command> shows
<filename>/usr</filename> as an export. When changing directories to
<filename>/host/foobar/usr</filename>, <application>amd</application>
attempts to resolve the hostname <hostid>foobar</hostid> and
automatically mount the desired export.</para>
<para><application>amd</application> can be started by the
startup scripts by placing the following lines in
<filename>/etc/rc.conf</filename>:</para>
<programlisting>amd_enable="YES"</programlisting>
<para>Additionally, custom flags can be passed to
<application>amd</application> from the
<varname>amd_flags</varname> option. By default,
<varname>amd_flags</varname> is set to:</para>
<programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting>
<para>The <filename>/etc/amd.map</filename> file defines the
default options that exports are mounted with. The
<filename>/etc/amd.conf</filename> file defines some of the more
advanced features of <application>amd</application>.</para>
<para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages for more
information.</para>
</sect2>
<sect2 id="nfs-integration">
<sect2info>
<authorgroup>
<author>
<firstname>John</firstname>
<surname>Lind</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect2info>
<title>Problems Integrating with Other Systems</title>
<para>Certain Ethernet adapters for ISA PC systems have limitations
which can lead to serious network problems, particularly with NFS.
This difficulty is not specific to FreeBSD, but FreeBSD systems
are affected by it.</para>
<para>The problem nearly always occurs when (FreeBSD) PC systems are
networked with high-performance workstations, such as those made
by Silicon Graphics, Inc., and Sun Microsystems, Inc. The NFS
mount will work fine, and some operations may succeed, but
suddenly the server will seem to become unresponsive to the
client, even though requests to and from other systems continue to
be processed. This happens to the client system, whether the
client is the FreeBSD system or the workstation. On many systems,
there is no way to shut down the client gracefully once this
problem has manifested itself. The only solution is often to
reset the client, because the NFS situation cannot be
resolved.</para>
<para>Though the <quote>correct</quote> solution is to get a higher
performance and capacity Ethernet adapter for the FreeBSD system,
there is a simple workaround that will allow satisfactory
operation. If the FreeBSD system is the
<emphasis>server</emphasis>, include the option
<option>-w=1024</option> on the mount from the client. If the
FreeBSD system is the <emphasis>client</emphasis>, then mount the
NFS filesystem with the option <option>-r=1024</option>. These
options may be specified using the fourth field of the
<filename>fstab</filename> entry on the client for automatic
mounts, or by using the <option>-o</option> parameter of the mount
command for manual mounts.</para>
<para>It should be noted that there is a different problem,
sometimes mistaken for this one, when the NFS servers and clients
are on different networks. If that is the case, make
<emphasis>certain</emphasis> that your routers are routing the
necessary UDP information, or you will not get anywhere, no matter
what else you are doing.</para>
<para>In the following examples, <hostid>fastws</hostid> is the host
(interface) name of a high-performance workstation, and
<hostid>freebox</hostid> is the host (interface) name of a FreeBSD
system with a lower-performance Ethernet adapter. Also,
<filename>/sharedfs</filename> will be the exported NFS
filesystem (see &man.exports.5;), and
<filename>/project</filename> will be the mount point on the
client for the exported filesystem. In all cases, note that
additional options, such as <option>hard</option> or
<option>soft</option> and <option>bg</option> may be desirable in
your application.</para>
<para>Examples for the FreeBSD system (<hostid>freebox</hostid>) as
the client in <filename>/etc/fstab</filename> on freebox:</para>
<programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting>
<para>As a manual mount command on <hostid>freebox</hostid>:</para>
<screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen>
<para>Examples for the FreeBSD system as the server in
<filename>/etc/fstab</filename> on <hostid>fastws</hostid>:</para>
<programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting>
<para>As a manual mount command on <hostid>fastws</hostid>:</para>
<screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen>
<para>Nearly any 16-bit Ethernet adapter will allow operation
without the above restrictions on the read or write size.</para>
<para>For anyone who cares, here is what happens when the failure
occurs, which also explains why it is unrecoverable. NFS
typically works with a <quote>block</quote> size of 8&nbsp;k (though it
may do fragments of smaller sizes). Since the maximum Ethernet
packet is around 1500&nbsp;bytes, the NFS <quote>block</quote> gets
split into multiple Ethernet packets, even though it is still a
single unit to the upper-level code, and must be received,
assembled, and <emphasis>acknowledged</emphasis> as a unit. The
high-performance workstations can pump out the packets which
comprise the NFS unit one right after the other, just as close
together as the standard allows. On the smaller, lower capacity
cards, the later packets overrun the earlier packets of the same
unit before they can be transferred to the host and the unit as a
whole cannot be reconstructed or acknowledged. As a result, the
workstation will time out and try again, but it will try again
with the entire 8&nbsp;K unit, and the process will be repeated, ad
infinitum.</para>
<para>By keeping the unit size below the Ethernet packet size
limitation, we ensure that any complete Ethernet packet received
can be acknowledged individually, avoiding the deadlock
situation.</para>
<para>Overruns may still occur when a high-performance workstations
is slamming data out to a PC system, but with the better cards,
such overruns are not guaranteed on NFS <quote>units</quote>. When
an overrun occurs, the units affected will be retransmitted, and
there will be a fair chance that they will be received, assembled,
and acknowledged.</para>
</sect2>
</sect1>
<sect1 id="diskless">
<sect1info>
<authorgroup>
<author>
<firstname>Jean-Fran&ccedil;ois</firstname>
<surname>Dock&egrave;s</surname>
<contrib>Updated by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Diskless Operation</title>
<indexterm><primary>diskless workstation</primary></indexterm>
<indexterm><primary>diskless operation</primary></indexterm>
<para>A FreeBSD machine can boot over the network and operate without a
local disk, using filesystems mounted from an NFS server. No system
modification is necessary, beyond standard configuration files.
Such a system is easy to set up because all the necessary elements
are readily available:</para>
<itemizedlist>
<listitem>
<para>There are at least two possible methods to load the kernel over
the network:</para>
<itemizedlist>
<listitem>
<para><emphasis>PXE</emphasis>: Intel's Preboot Execution
Environment system is a form of smart boot ROM built into some
networking cards or motherboards. See &man.pxeboot.8; for more
details.</para>
</listitem>
<listitem>
<para><emphasis>The <application>etherboot</application>
port</emphasis> (<filename role="package">net/etherboot</filename>)
produces ROM-able code to boot kernels over the network. The code
can be either burnt into a boot PROM on a network card, or loaded
from a local floppy (or hard) disk drive, or from a running
MS-DOS system. Many network cards are supported.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>A sample script
(<filename>/usr/share/examples/diskless/clone_root</filename>) eases
the creation and maintenance of the workstation's root filesystem
on the server. The script will probably require a little
customization but it will get you started very quickly.</para>
</listitem>
<listitem>
<para>Standard system startup files exist in <filename>/etc</filename>
to detect and support a diskless system startup.</para>
</listitem>
<listitem>
<para>Swapping, if needed, can be done either to an NFS file or to
a local disk.</para>
</listitem>
</itemizedlist>
<para>There are many ways to set up diskless workstations. Many
elements are involved, and most can be customized to suit local
taste. The following will describe the setup of a complete system,
emphasizing simplicity and compatibility with the
standard FreeBSD startup scripts. The system described has the
following characteristics:</para>
<itemizedlist>
<listitem>
<para>The diskless workstations use a shared
read-only <filename>root</filename> filesystem, and a shared
read-only <filename>/usr</filename>.</para>
<para>The <filename>root</filename> filesystem is a copy of a
standard FreeBSD root (typically the server's), with some
configuration files overridden by ones specific to diskless
operation or, possibly, to the workstation they belong to.</para>
<para>The parts of the <filename>root</filename> which have to be
writable are overlaid with &man.mfs.8; filesystems. Any changes
will be lost when the system reboots.</para>
</listitem>
<listitem>
<para>The kernel is loaded by <application>etherboot
</application>, using DHCP (or BOOTP) and TFTP.</para>
</listitem>
</itemizedlist>
<caution><para>As described, this system is insecure. It should
live in a protected area of a network, and be untrusted by
other hosts.</para>
</caution>
<sect2>
<title>Setup Instructions</title>
<sect3>
<title>Configuring DHCP/BOOTP</title>
<para>There are two protocols that are commonly used to boot a
workstation that retrieves its configuration over the network: BOOTP
and DHCP. They are used at several points in the workstation
bootstrap:</para>
<itemizedlist>
<listitem><para><application>etherboot</application> uses
DHCP (by default) or BOOTP (needs a configuration option) to
find the kernel. (PXE uses DHCP).</para>
</listitem>
<listitem><para>The kernel uses BOOTP to locate the NFS
root.</para>
</listitem>
</itemizedlist>
<para>It is possible to configure a system to use only BOOTP.
The &man.bootpd.8; server program is included in the
base FreeBSD system.</para>
<para>However, DHCP has a number of advantages over BOOTP (nicer
configuration files, possibility of using PXE, plus many others
not directly related to diskless operation), and we shall describe
both a pure BOOTP, and a BOOTP+DHCP configuration, with an
emphasis on the latter, which will use the ISC DHCP software
package.</para>
<sect4>
<title>Configuration Using ISC DHCP</title>
<para>The <application>isc-dhcp</application> server can answer
both BOOTP and DHCP requests.</para>
<para>As of release 4.4, <application>isc-dhcp
3.0</application> is not part of the base
system. You will first need to install the
<filename role="package">net/isc-dhcp3</filename> port or the
corresponding package. Please refer to <xref linkend="ports">
for general information about ports and packages.</para>
<para>Once <application>isc-dhcp</application> is installed, it
needs a configuration file to run, (normally named
<filename>/usr/local/etc/dhcpd.conf</filename>). Here follows
a commented example:</para>
<programlisting>
default-lease-time 600;
max-lease-time 7200;
authoritative;
option domain-name "example.com";
option domain-name-servers 192.168.4.1;
option routers 192.168.4.1;
subnet 192.168.4.0 netmask 255.255.255.0 {
use-host-decl-names on; <co id="co-dhcp-host-name">
option subnet-mask 255.255.255.0;
option broadcast-address 192.168.4.255;
host margaux {
hardware ethernet 01:23:45:67:89:ab;
fixed-address margaux.example.com;
next-server 192.168.4.4;<co id="co-dhcp-next-server">
filename "/tftpboot/kernel.diskless";<co id="co-dhcp-filename">
option root-path "192.168.4.4:/data/misc/diskless";<co id="co-dhcp-root-path">
}
}
</programlisting>
<calloutlist>
<callout arearefs="co-dhcp-host-name"><para>This option tells
<command>dhcpd</command> to send the value in the
<literal>host</literal> declarations as the hostname for the
diskless host. An alternate way would be to add an
<literal>option host-name
<replaceable>margaux</replaceable></literal> inside the
host declarations.</para>
</callout>
<callout arearefs="co-dhcp-next-server"><para>The
<literal>next-server</literal> directive designates
the TFTP server (the default is to use the same host as the
DHCP server).</para>
</callout>
<callout arearefs="co-dhcp-filename"><para>The
<literal>filename</literal> directive defines the file that
<application>etherboot</application> will load as a
kernel.
<note><para>PXE appears to prefer a relative file
name, and it loads <command>pxeboot</command>, not the
kernel (<literal>option filename
"pxeboot"</literal>).</para>
</note>
</para>
</callout>
<callout arearefs="co-dhcp-root-path"><para>The
<literal>root-path</literal> option defines the path to
the root filesystem, in usual NFS notation.</para>
</callout>
</calloutlist>
</sect4>
<sect4>
<title>Configuration Using BOOTP</title>
<para>Here follows an equivalent <command>bootpd</command>
configuration. This would be found in
<filename>/etc/bootptab</filename>.</para>
<para>Please note that <application>etherboot</application> must
be compiled with the non-default option
<literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, and that PXE
<emphasis>needs</emphasis> DHCP. The only obvious advantage of
<application>bootpd</application> is that it exists in the base system.</para>
<programlisting>
.def100:\
:hn:ht=1:sa=192.168.4.4:vm=rfc1048:\
:sm=255.255.255.0:\
:ds=192.168.4.1:\
:gw=192.168.4.1:\
:hd="/tftpboot":\
:bf="/kernel.diskless":\
:rp="192.168.4.4:/data/misc/diskless":
margaux:ha=0123456789ab:tc=.def100
</programlisting>
</sect4>
</sect3>
<sect3>
<title>Preparing a Boot Program with
<application>Etherboot</application></title>
<para><ulink url="http://etherboot.sourceforge.net">Etherboot's Web
site</ulink> contains
<ulink url="http://etherboot.sourceforge.net/doc/html/userman.html">
extensive documentation</ulink> mainly intended for Linux
systems, but nonetheless containing useful information. The following
will just outline how you would use
<application>etherboot</application> on a FreeBSD system.</para>
<para>You must first install the
<filename role="package">net/etherboot</filename> package or port. The
<application>etherboot</application> port can normally be found in
<filename>/usr/ports/net/etherboot</filename>. If the ports tree is
installed on your system, just typing <literal>make</literal> in
this directory should take care of everything. Else refer to
<xref linkend="ports"> for information about ports and
packages.</para>
<para>For our setup, we shall use a boot floppy. For other methods
(PROM, or dos program), please refer to the
<application>etherboot</application> documentation.</para>
<para>To make a boot floppy, insert a floppy in the drive on the
machine where you installed <application>etherboot</application>,
then change your current directory to the <filename>src</filename>
directory in the <application>etherboot</application> tree and
type:</para>
<screen>
&prompt.root; <userinput>gmake bin32/<replaceable>devicetype</replaceable>.fd0</userinput>
</screen>
<para><replaceable>devicetype</replaceable> depends on the type of
the Ethernet card in the diskless workstation. Refer to the
<filename>NIC</filename> file in the same directory to determine the
right <replaceable>devicetype</replaceable>.</para>
</sect3>
<sect3>
<title>Configuring the TFTP and NFS Servers</title>
<para>You need to enable <command>tftpd</command> on the TFTP
server:</para>
<procedure>
<step>
<para>Create a directory from which <command>tftpd</command>
will serve the files, i.e.: <filename>/tftpboot</filename></para>
</step>
<step>
<para>Add this line to your
<filename>/etc/inetd.conf</filename>:</para>
<programlisting>tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot</programlisting>
<note><para>It appears that at least some PXE versions want
the TCP version of TFTP. In this case, add a second line,
replacing <literal>dgram udp</literal> with <literal>stream
tcp</literal>.</para>
</note>
</step>
<step>
<para>Tell <command>inetd</command> to reread its configuration
file:</para>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
</step>
</procedure>
<para>You can place the <filename>tftpboot</filename>
directory anywhere on the server. Make sure that the
location is set in both <filename>inetd.conf</filename> and
<filename>dhcpd.conf</filename>.</para>
<para>You also need to enable NFS and export the
appropriate filesystem on the NFS server.</para>
<procedure>
<step>
<para>Add this to <filename>/etc/rc.conf</filename>:</para>
<programlisting>nfs_server_enable="YES"</programlisting>
</step>
<step>
<para>Export the filesystem where the diskless root directory
is located by adding the following to
<filename>/etc/exports</filename> (adjust the volume mount
point and replace <replaceable>margaux</replaceable>
with the name of the diskless workstation):</para>
<programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux</replaceable></programlisting>
</step>
<step>
<para>Tell <command>mountd</command> to reread its configuration
file. If you actually needed to enable NFS in
<filename>/etc/rc.conf</filename>
at the first step, you probably want to reboot instead.</para>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen>
</step>
</procedure>
</sect3>
<sect3>
<title>Building a Diskless Kernel</title>
<para>Create a kernel configuration file for the diskless client
with the following options (in addition to the usual
ones):</para>
<programlisting>
options BOOTP # Use BOOTP to obtain IP address/hostname
options BOOTP_NFSROOT # NFS mount root filesystem using BOOTP info
options BOOTP_COMPAT # Workaround for broken bootp daemons.
</programlisting>
<para>You may also want to use <literal>BOOTP_NFSV3</literal> and
<literal>BOOTP_WIRED_TO</literal> (refer to <filename>LINT</filename>).</para>
<para>Build the kernel (See <xref linkend="kernelconfig">),
and copy it to the tftp directory, under the name listed
in <filename>dhcpd.conf</filename>.</para>
</sect3>
<sect3>
<title>Preparing the root Filesystem</title>
<para>You need to create a root filesystem for the diskless
workstations, in the location listed as
<literal>root-path</literal> in
<filename>dhcpd.conf</filename>.</para>
<para>The easiest way to do this is to use the
<filename>/usr/share/examples/diskless/clone_root</filename>
shell script. This script needs customization, at least to adjust
the place where the filesystem will be created (the
<literal>DEST</literal> variable).
<para>Refer to the comments at the top of the script for
instructions. They explain how the base filesystem is built,
and how files may be selectively overridden by versions specific
to diskless operation, to a subnetwork, or to an individual
workstation. They also give examples for the diskless
<filename>/etc/fstab</filename> and <filename>
/etc/rc.conf</filename> files.</para>
<para>The <filename>README</filename> files in
<filename>/usr/share/examples/diskless</filename> contain a lot
of interesting background information, but, together with the
other examples in the <filename>diskless</filename> directory,
they actually document a configuration method which is distinct
from the one used by <filename>clone_root</filename> and
<filename>/etc/rc.diskless[12]</filename>, which is a little
confusing. Use them for reference only, except if you prefer
the method that they describe, in which case you will need
customized <filename>rc</filename> scripts.</para>
</sect3>
<sect3>
<title>Configuring Swap</title>
<para>If needed, a swap file located on the server can be
accessed via NFS. The exact <filename>bootptab</filename>
or <filename>dhcpd.conf</filename> options are not clearly
documented at this time. The following configuration
suggestions have been reported to work in some installations
using isc-dhcp 3.0rc11.</para>
<procedure>
<step><para>Add the following lines to
<filename>dhcpd.conf</filename>:</para>
<programlisting>
# Global section
option swap-path code 128 = string;
option swap-size code 129 = integer 32;
host margaux {
... # Standard lines, see above
option swap-path <replaceable>"192.168.4.4:/netswapvolume/netswap"</replaceable>;
option swap-size <replaceable>64000</replaceable>;
}
</programlisting>
<para>The idea is that, at least for a FreeBSD client,
DHCP/BOOTP option code 128 is the path to the NFS swap file,
and option code 129 is the swap size in kilobytes. Older
versions of <command>dhcpd</command> allowed a syntax of
<literal>option option-128 "...</literal>, which does not
seem to work any more.</para>
<para><filename>/etc/bootptab</filename> would use the
following syntax instead:</para>
<para><literal>T128="192.168.4.4:/netswapvolume/netswap":T129=64000
</literal></para>
</step>
<step>
<para>On the NFS swap file server, create the swap
file(s)</para>
<screen>
&prompt.root; <userinput>mkdir <replaceable>/netswapvolume/netswap</replaceable></userinput>
&prompt.root; <userinput>cd <replaceable>/netswapvolume/netswap</replaceable></userinput>
&prompt.root; <userinput>dd if=/dev/zero bs=1024 count=<replaceable>64000</replaceable> of=swap.<replaceable>192.168.4.6</replaceable></userinput>
&prompt.root; <userinput>chmod 0600 swap.<replaceable>192.168.4.6</replaceable></userinput>
</screen>
<para><replaceable>192.168.4.6</replaceable> is the IP address
for the diskless client.</para>
</step>
<step>
<para>On the NFS swap file server, add the following line to
<filename>/etc/exports</filename>:</para>
<programlisting>
<replaceable>/netswapvolume</replaceable> -maproot=0:10 -alldirs <replaceable>margaux</replaceable>
</programlisting>
<para>Then tell <application>mountd</application> to reread the
exports file, as above.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Miscellaneous Issues</title>
<sect4>
<title>Running with a read-only <filename>/usr</filename></title
<para>If the diskless workstation is configured to run X, you
will have to adjust the xdm configuration file, which puts
the error log on <filename>/usr</filename> by default.</para>
</sect4>
<sect4>
<title>Using a non-FreeBSD Server</title>
<para>When the server for the root filesystem is not running FreeBSD,
you will have to create the root filesystem on a
FreeBSD machine, then copy it to its destination, using
<command>tar</command> or <command>cpio</command>.</para>
<para>In this situation, there are sometimes
problems with the special files in <filename>/dev</filename>,
due to differing major/minor integer sizes. A solution to this
problem is to export a directory from the non-FreeBSD server,
mount this directory onto a FreeBSD machine, and run
<command>MAKEDEV</command> on the FreeBSD machine
to create the correct device entries (FreeBSD 5.0 and later
use &man.devfs.5; to allocate device nodes transparently for
the user, running <command>MAKEDEV</command> on these
versions is useless).</para>
</sect4>
</sect3>
</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 id="isdn-cards">
<sect2info>
<authorgroup>
<author>
<firstname>Hellmuth</firstname>
<surname>Michaelis</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect2info>
<title>ISDN Cards</title>
<indexterm>
<primary>ISDN</primary>
<secondary>cards</secondary>
</indexterm>
<para>FreeBSD's ISDN implementation supports only the DSS1/Q.931
(or Euro-ISDN) standard using passive cards. Starting with
FreeBSD&nbsp;4.4, some active cards are supported where the firmware
also supports other signaling protocols; this also includes the
first supported Primary Rate (PRI) ISDN card.</para>
<para><application>Isdn4bsd</application> allows you to connect
to other ISDN routers using either IP over raw HDLC or by using
synchronous PPP: either by using kernel PPP with isppp, a
modified sppp driver, or by using userland &man.ppp.8;. By using
userland &man.ppp.8;, channel bonding of two or more ISDN
B-channels is possible. A telephone answering machine
application is also available as well as many utilities such as
a software 300 Baud modem.</para>
<para>Some growing number of PC ISDN cards are supported under
FreeBSD and the reports show that it is successfully used all
over Europe and in many other parts of the world.</para>
<para>The passive ISDN cards supported are mostly the ones with
the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets,
but also ISDN cards with chips from Cologne Chip (ISA bus only),
PCI cards with Winbond W6692 chips, some cards with the
Tiger300/320/ISAC chipset combinations and some vendor specific
chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the
AVM Fritz!Card PnP.</para>
<para>Currently the active supported ISDN cards are the AVM B1
(ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para>
<para>For documentation on <application>isdn4bsd</application>,
have a look at <filename>/usr/share/examples/isdn/</filename>
directory on your FreeBSD system or at the <ulink
url="http://www.freebsd-support.de/i4b/">homepage of
isdn4bsd</ulink> which also has pointers to hints, erratas and
much more documentation such as the <ulink
url="http://people.FreeBSD.org/~hm/">isdn4bsd
handbook</ulink>.</para>
<para>In case you are interested in adding support for a
different ISDN protocol, a currently unsupported ISDN PC card or
otherwise enhancing <application>isdn4bsd</application>, please
get in touch with &a.hm;.</para>
<para>For questions regarding the installation, configuration
and troubleshooting <application>isdn4bsd</application>, a
majordomo maintained mailing list is available. To join, send
mail to &a.majordomo; and specify:</para>
<para><literal>subscribe freebsd-isdn</literal></para>
<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 known to work with FreeBSD.</para>
<itemizedlist>
<listitem>
<para>Motorola BitSurfer and Bitsurfer Pro</para>
</listitem>
<listitem>
<para>Adtran</para>
</listitem>
</itemizedlist>
<para>Most other TA's will probably work as well, TA vendors try to make
sure their product can accept most of the standard modem AT command
set.</para>
<para>The real problem with external TA's is that, like modems, you need a good
serial card in your computer.</para>
<para>You should read the <ulink
url="../../articles/serial-uart/index.html">FreeBSD Serial
Hardware</ulink> tutorial for a detailed understanding of
serial devices, and the differences between asynchronous and
synchronous serial ports.</para>
<para>A TA running off a standard PC serial port (asynchronous) limits
you to 115.2&nbsp;Kbs, even though you have a 128&nbsp;Kbs connection.
To fully utilize the 128&nbsp;Kbs that ISDN is capable of,
you must move the TA to a synchronous serial card.</para>
<para>Do not be fooled into buying an internal TA and thinking you have
avoided the synchronous/asynchronous issue. Internal TA's simply have
a standard PC serial port chip built into them. All this will do is
save you having to buy another serial cable and find another empty
electrical socket.</para>
<para>A synchronous card with a TA is at least as fast as a stand-alone
router, and with a simple 386 FreeBSD box driving it, probably more
flexible.</para>
<para>The choice of 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="../../../../search/index.html">archives</ulink> for
the complete discussion.</para>
</sect2>
<sect2>
<title>Stand-alone ISDN Bridges/Routers</title>
<indexterm>
<primary>ISDN</primary>
<secondary>stand-alone bridges/routers</secondary>
</indexterm>
<para>ISDN bridges or routers are not at all specific to FreeBSD
or any other operating system. For a more complete
description of routing and bridging technology, please refer
to a Networking reference book.</para>
<para>In the context of this 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, and manages its own connection to the other
bridge/router. It has built in software to communicate via
PPP and other popular protocols.</para>
<para>A router will allow you much faster throughput than a
standard TA, since it will be using a full synchronous ISDN
connection.</para>
<para>The main problem with ISDN routers and bridges is that
interoperability between manufacturers can still be a problem.
If you are planning to connect to an Internet provider, you
should discuss your needs with them.</para>
<para>If you are planning to connect two LAN segments together,
such as your home LAN to the office LAN, this is the simplest
lowest
maintenance solution. Since you are buying the equipment for
both sides of the connection you can be assured that the link
will work.</para>
<para>For example to connect a home computer or branch office
network to a head office network the following setup could be
used.</para>
<example>
<title>Branch Office or Home Network</title>
<indexterm><primary>10 base 2</primary></indexterm>
<para>Network uses a bus based topology with 10 base 2
Ethernet (<quote>thinnet</quote>). Connect router to network cable with
AUI/10BT transceiver, if necessary.</para>
<mediaobject>
<imageobject>
<imagedata fileref="advanced-networking/isdn-bus">
</imageobject>
<textobject>
<literallayout class="monospaced">---Sun workstation
|
---FreeBSD box
|
---Windows 95 (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
(<quote>Twisted Pair</quote>).</para>
<mediaobject>
<imageobject>
<imagedata fileref="advanced-networking/isdn-twisted-pair">
</imageobject>
<textobject>
<literallayout class="monospaced"> -------Novell Server
| H |
| ---Sun
| |
| U ---FreeBSD
| |
| ---Windows 95
| B |
|___---Stand-alone router
|
ISDN BRI line</literallayout>
</textobject>
<textobject>
<phrase>ISDN Network Diagram</phrase>
</textobject>
</mediaobject>
</example>
<para>One large advantage of most routers/bridges is that they allow you
to have 2 <emphasis>separate independent</emphasis> PPP connections to
2 separate sites at the <emphasis>same</emphasis> time. This is not
supported on most TA's, except for specific (usually expensive) models
that
have two serial ports. Do not confuse this with channel bonding, MPP,
etc.</para>
<para>This can be a very useful feature if, for example, you have an
dedicated ISDN connection at your office and would like to
tap into it, but do not want to get another ISDN line at work. A router
at the office location can manage a dedicated B channel connection
(64&nbsp;Kbps) to the Internet and use the other B channel for a
separate data connection. The second B channel can be used for
dial-in, dial-out or dynamically bonding (MPP, etc.) with the first
B channel for more bandwidth.</para>
<indexterm><primary>IPX/SPX</primary></indexterm>
<para>An Ethernet bridge will also allow you to transmit more than just
IP traffic. You can also send IPX/SPX or whatever other protocols you
use.</para>
</sect2>
</sect1>
<sect1 id="nis">
<sect1info>
<authorgroup>
<author>
<firstname>Bill</firstname>
<surname>Swingle</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Eric</firstname>
<surname>Ogren</surname>
<contrib>Enhanced by </contrib>
</author>
<author>
<firstname>Udo</firstname>
<surname>Erdelhoff</surname>
</author>
</authorgroup>
</sect1info>
<title>NIS/YP</title>
<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 Unix systems (Solaris, HP-UX, AIX, Linux,
NetBSD, OpenBSD, FreeBSD, etc) support NIS.</para>
<indexterm><primary>yellow pages</primary><see>NIS</see></indexterm>
<para>NIS was formerly known as Yellow Pages, but because of
trademark issues, Sun changed the name. The old term (and yp) is
still often seen and used.</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 are not 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 as an NIS client:</para>
<indexterm>
<primary><application>portmap</application></primary>
</indexterm>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Term</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>NIS domainname</entry>
<entry>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.</entry>
</row>
<row>
<entry>portmap</entry>
<entry>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.</entry>
</row>
<row>
<entry>ypbind</entry>
<entry><quote>binds</quote> 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.</entry>
</row>
<row>
<entry>ypserv</entry>
<entry>Should only be running on NIS servers, is the NIS
server process itself. If &man.ypserv.8; 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). There are some implementations of NIS (but not the
FreeBSD one), that do not 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.
</entry>
</row>
<row>
<entry>rpc.yppasswdd</entry>
<entry>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.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<!-- XXX Missing: rpc.ypxfrd (not important, though) May only run
on the master -->
</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
NIS server that it is bound to instead.</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&nbsp;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 us 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
<quote>acme-art</quote> 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 will not 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>
<procedure>
<step>
<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>
</step>
<step>
<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>
</step>
<step>
<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>
</step>
</procedure>
<note>
<para>Depending on your NIS setup, you may need to add
further entries. See the <link
linkend="nis-server-is-client">section about NIS servers
that are also NIS clients</link>, below, for
details.</para>
</note>
<para>Now, all you have to do is to run the command
<command>/etc/netstart</command> as superuser. It will
set up 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</primary>
<secondary>maps</secondary>
</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 do not want to propagate
passwords to your <username>root</username> 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
(<username>bin</username>, <username>tty</username>,
<username>kmem</username>, <username>games</username>, etc), as
well as any accounts that you do not want to be propagated to the
NIS clients (for example <username>root</username> 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 is time to initialize the NIS
maps! FreeBSD includes a script named
<command>ypinit</command> to do this for you
(see its manual page for more information). Note that this
script is available on most Unix Operating Systems, 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 &lt;control D&gt;.
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</para>
<programlisting>NOPUSH = "True"</programlisting>
<para>(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 these entries are
not mandatory, since the master server attempts to ensure
any changes to its NIS maps are communicated to its slaves
and because password information is vital to systems
depending on the server, 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>
<procedure>
<step>
<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>
</step>
<step>
<para>To import all possible password entries from the NIS
server, remove all user accounts from your
<filename>/etc/master.passwd</filename> file and use
<command>vipw</command> to add the following line to
the end of the file:</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
section</link> below for more information.
For more detailed reading see O'Reilly's book on
<literal>Managing NFS and NIS</literal>.</para>
</note>
<note>
<para>You should keep at least one local account (i.e.
not imported via NIS) in your
<filename>/etc/master.passwd</filename> and this
account should also be a member of the group
<groupname>wheel</groupname>. If there is something
wrong with NIS, this account can be used to log in
remotely, become root, and fix things.</para>
</note>
</step>
<step>
<para>To import all possible group entries from the NIS
server, add this line to your
<filename>/etc/group</filename> file:</para>
<programlisting>+:*::</programlisting>
</step>
</procedure>
<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 &man.ypserv.8; and
retrieve the contents of your NIS maps, provided the remote user
knows your domainname. To prevent such unauthorized transactions,
&man.ypserv.8; supports a feature called securenets which can be used to
restrict access to a given set of hosts. At startup, &man.ypserv.8; 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 &man.ypserv.8; 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,
<command>ypserv</command> will allow connections from any host.</para>
<para>The <command>ypserv</command> program also has support for Wietse
Venema's
<application>tcpwrapper</application> package. This allows the
administrator to use the <application>tcpwrapper</application> 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 do not 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">
<sect2info>
<authorgroup>
<author>
<firstname>Udo</firstname>
<surname>Erdelhoff</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect2info>
<title>Using Netgroups</title>
<indexterm><primary>netgroups</primary></indexterm>
<para>The method shown in the previous section 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 section 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
<filename>passwd</filename>
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 &man.ypinit.8; 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 the 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,
<command>cd ~<replaceable>user</replaceable></command> 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 <errorname>No such user</errorname>. 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:</para>
<para><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 <quote>+</quote>. 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 of
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
<quote>jsmith</quote> 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 do not want to be propagating administrative
accounts and passwords to machines that will have users that
should not 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 cannot 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 id="nis-server-is-client">
<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 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. If you do not want to do this manually each time you
reboot your NIS server, you can add the following lines to
your <filename>/etc/rc.conf</filename>:</para>
<programlisting>nis_client_enable="YES" # run client stuff as well
nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting>
<para>See &man.ypbind.8; for further information.</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 libcrypt.a@ -> libdescrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 libcrypt.so@ -> libdescrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 libcrypt.so.2@ -> libdescrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 libcrypt_p.a@ -> libdescrypt_p.a
-r--r--r-- 1 root wheel 13018 Nov 8 14:27 libdescrypt.a
lrwxr-xr-x 1 root wheel 16 Nov 8 14:27 libdescrypt.so@ -> libdescrypt.so.2
-r--r--r-- 1 root wheel 12965 Nov 8 14:27 libdescrypt.so.2
-r--r--r-- 1 root wheel 14750 Nov 8 14:27 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 libcrypt.a@ -> libscrypt.a
lrwxrwxrwx 1 root wheel 14 Jul 15 08:55 libcrypt.so@ -> libscrypt.so
lrwxrwxrwx 1 root wheel 16 Jul 15 08:55 libcrypt.so.2@ -> libscrypt.so.2
lrwxrwxrwx 1 root wheel 15 Jul 15 08:55 libcrypt_p.a@ -> libscrypt_p.a
-r--r--r-- 1 root wheel 6194 Nov 8 14:27 libscrypt.a
lrwxr-xr-x 1 root wheel 14 Nov 8 14:27 libscrypt.so@ -> libscrypt.so.2
-r--r--r-- 1 root wheel 7579 Nov 8 14:27 libscrypt.so.2
-r--r--r-- 1 root wheel 6684 Nov 8 14:27 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">
<sect1info>
<authorgroup>
<author>
<firstname>Greg</firstname>
<surname>Sutter</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
</sect1info>
<title>DHCP</title>
<sect2>
<title>What Is DHCP?</title>
<indexterm>
<primary>Dynamic Host Configuration Protocol</primary>
<see>DHCP</see>
</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 section describes both the client-side and server-side
components of the ISC DHCP system. The client-side program,
<command>dhclient</command>, comes integrated within FreeBSD, and
the server-side portion is available from the
<filename role="package">net/isc-dhcp3</filename> port. The
&man.dhclient.8;, &man.dhcp-options.5;, and &man.dhclient.conf.5;
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 <command>dhclient</command>, 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
<quote>lease</quote> 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><application>sysinstall</application></primary>
</indexterm>
<para>DHCP is supported by <application>sysinstall</application>.
When configuring a network interface within sysinstall,
the first question asked is, <quote>Do you want to try DHCP
configuration of this interface?</quote> Answering affirmatively will
execute <command>dhclient</command>, 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 do not have a custom
kernel, you should not 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
<username>root</username>). <devicename>bpf</devicename>
<emphasis>is</emphasis> required to use DHCP, but if
you are very sensitive about security, you probably
should not 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 <filename role="package">net/isc-dhcp3</filename> 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;
manual 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>
<sect2 id="dhcp-server">
<sect2info>
<authorgroup>
<author>
<firstname>Ceri</firstname>
<surname>Davies</surname>
<contrib>Written by </contrib>
<affiliation>
<address><email>ceri@FreeBSD.org</email></address>
</affiliation>
</author>
</authorgroup>
</sect2info>
<title>Installing And Configuring A DHCP Server</title>
<sect3>
<title>What this Section Covers</title>
<para>This section provides information on how to configure
a FreeBSD system to act as a DHCP server using the ISC
(Internet Software Consortium) implementation of the DHCP
suite.</para>
<para>The server portion of the suite is not provided as part of
FreeBSD, and so you will need to install the
<filename role="package">net/isc-dhcp3</filename>
port to provide this service. See <xref linkend="ports"> for
more information on using the ports collection.</para>
</sect3>
<sect3>
<title>DHCP Server Installation</title>
<indexterm>
<primary>DHCP</primary>
<secondary>installation</secondary>
</indexterm>
<para>In order to configure your FreeBSD system as a DHCP server,
you will need to ensure that the &man.bpf.4;
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 you do not need to create a custom
kernel in order to get DHCP working.</para>
<note>
<para>Those who are particularly security conscious
should note that <devicename>bpf</devicename>
is also the device that allows packet sniffers to work
correctly (although such programs still need privileged
access). <devicename>bpf</devicename>
<emphasis>is</emphasis> required to use DHCP, but if
you are very sensitive about security, you probably
should not include <devicename>bpf</devicename> in your
kernel purely because you expect to use DHCP at some
point in the future.</para>
</note>
<para>The next thing that you will need to do is edit the sample
<filename>dhcpd.conf</filename> which was installed by the
<filename role="package">net/isc-dhcp3</filename> port.
By default, this will be
<filename>/usr/local/etc/dhcpd.conf.sample</filename>, and you
should copy this to
<filename>/usr/local/etc/dhcpd.conf</filename> before proceeding
to make changes.</para>
</sect3>
<sect3>
<title>Configuring the DHCP Server</title>
<indexterm>
<primary>DHCP configuration</primary>
<secondary>dhcpd.conf</secondary>
</indexterm>
<para><filename>dhcpd.conf</filename> is
comprised of declarations regarding subnets and hosts, and is
perhaps most easily explained using an example :</para>
<programlisting>option domain-name "example.com";<co id="domain-name">
option domain-name-servers 192.168.4.100;<co id="domain-name-servers">
option subnet-mask 255.255.255.0;<co id="subnet-mask">
default-lease-time 3600;<co id="default-lease-time">
max-lease-time 86400;<co id="max-lease-time">
ddns-update-style none;<co id="ddns-update-style">
subnet 192.168.4.0 netmask 255.255.255.0 {
range 192.168.4.129 192.168.4.254;<co id="range">
option routers 192.168.4.1;<co id="routers">
}
host mailhost {
hardware ethernet 02:03:04:05:06:07;<co id="hardware">
fixed-address mailhost.example.com;<co id="fixed-address">
}</programlisting>
<calloutlist>
<callout arearefs="domain-name">
<para>This option specifies the domain that will be provided
to clients as the default search domain. See
&man.resolv.conf.5; for more information on what this
means.</para>
</callout>
<callout arearefs="domain-name-servers">
<para>This option specifies a comma separated list of DNS
servers that the client should use.</para>
</callout>
<callout arearefs="subnet-mask">
<para>The netmask that will be provided to clients.</para>
</callout>
<callout arearefs="default-lease-time">
<para>A client may request a specific length of time that a
lease will be valid. Otherwise the server will assign
a lease with this expiry value (in seconds).</para>
</callout>
<callout arearefs="max-lease-time">
<para>This is the maximum length of time that the server will
lease for. Should a client request a longer lease, a lease
will be issued, although it will only be valid for
<literal>max-lease-time</literal> seconds.</para>
</callout>
<callout arearefs="ddns-update-style">
<para>This option specifies whether the DHCP server should
attempt to update DNS when a lease is accepted or released.
In the ISC implementation, this option is
<emphasis>required</emphasis>.</para>
</callout>
<callout arearefs="range">
<para>This denotes which IP addresses should be used in the
pool reserved for allocating to clients. IP addresses between,
and including, the ones stated are handed out to clients.</para>
</callout>
<callout arearefs="routers">
<para>Declares the default gateway that will be provided to
clients.</para>
</callout>
<callout arearefs="hardware">
<para>The hardware MAC address of a host (so that the DHCP server
can recognise a host when it makes a request).</para>
</callout>
<callout arearefs="fixed-address">
<para>Specifies that the host should always be given the same
IP address. Note that a hostname is OK here, since the DHCP
server will resolve the hostname itself before returning the
lease information.</para>
</callout>
</calloutlist>
<para>Once you have finished writing your
<filename>dhcpd.conf</filename>, you can proceed to start the
server by issuing the following command:</para>
<screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd.sh start</userinput></screen>
<para>Should you need to make changes to the configuration of your
server in the future, it is important to note that sending a
<literal>SIGHUP</literal> signal to
<application>dhcpd</application> does <emphasis>not</emphasis>
result in the configuration being reloaded, as it does with most
daemons. You will need to send a <literal>SIGTERM</literal>
signal to stop the process, and then restart it using the command
above.</para>
</sect3>
<sect3>
<title>Files</title>
<indexterm>
<primary>DHCP</primary>
<secondary>configuration files</secondary>
</indexterm>
<itemizedlist>
<listitem><para><filename>/usr/local/sbin/dhcpd</filename></para>
<para><application>dhcpd</application> is statically linked and
resides in <filename>/usr/local/sbin</filename>. The
dhcpd(8) manual page installed with the
port gives more information about
<application>dhcpd</application>.</para>
</listitem>
<listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
<para><application>dhcpd</application> requires a configuration
file, <filename>/usr/local/etc/dhcpd.conf</filename> before it
will start providing service to clients. This file needs to
contain all the information that should be provided to clients
that are being serviced, along with information regarding the
operation of the server. This configuration file is described
by the dhcpd.conf(5) manual page installed
by the port.</para>
</listitem>
<listitem><para><filename>/var/db/dhcpd.leases</filename></para>
<para>The DHCP server keeps a database of leases it has issued
in this file, which is written as a log. The manual page
dhcpd.leases(5), installed by the port
gives a slightly longer description.</para>
</listitem>
<listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
<para><application>dhcrelay</application> is used in advanced
environments where one DHCP server forwards a request from a
client to another DHCP server on a separate network. The
dhcrelay(8) manual page provided with the
port contains more detail.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="dns">
<sect1info>
<authorgroup>
<author>
<firstname>Chern</firstname>
<surname>Lee</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>DNS</title>
<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
IP addresses, and vice versa. For example, a query for
<hostid>www.FreeBSD.org</hostid>
will receive a reply with the IP address of The FreeBSD Project's
web server, whereas, a query for <hostid>ftp.FreeBSD.org</hostid>
will return the IP
address of the corresponding FTP machine. Likewise, the opposite can
happen. A query for an IP address can resolve its hostname. It is
not necessary to run a name server to perform DNS lookups on a system.
</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 name servers who host and cache individual domain
information.
</para>
<para>
This document refers to BIND 8.x, as it is the stable version
used in FreeBSD. BIND 9.x in FreeBSD can be installed through
the <filename role="package">net/bind9</filename> port.
</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>
<para>To understand this document, some terms related to DNS must be
understood.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Term</entry>
<entry>Definition</entry>
</row>
</thead>
<tbody>
<row>
<entry>forward DNS</entry>
<entry>mapping of hostnames to IP addresses</entry>
</row>
<row>
<entry>origin</entry>
<entry>refers to the domain covered for the particular zone
file</entry>
</row>
<row>
<entry>named, bind, name server</entry>
<entry>common names for the BIND name server package within
FreeBSD</entry>
</row>
<indexterm><primary>resolver</primary></indexterm>
<row>
<entry>resolver</entry>
<entry>a system process through which a
machine queries a name server for zone information</entry>
</row>
<indexterm><primary>reverse DNS</primary></indexterm>
<row>
<entry>reverse DNS</entry>
<entry>the opposite of forward DNS, mapping of IP addresses to
hostnames</entry>
</row>
<indexterm><primary>root zone</primary></indexterm>
<row>
<entry>root zone</entry>
<entry>literally, a <quote>.</quote>, 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.</entry>
</row>
<row>
<entry>zone</entry>
<entry>Each individual domain, subdomain, or area dictated by
DNS</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<indexterm>
<primary>zones</primary>
<secondary>examples</secondary>
</indexterm>
<para>Examples of zones:
</para>
<itemizedlist>
<listitem>
<para>. is the root zone</para>
</listitem>
<listitem>
<para><hostid>org.</hostid> is a zone under the root zone</para>
</listitem>
<listitem>
<para><hostid>example.org</hostid> is a zone under the org. zone</para>
</listitem>
<listitem>
<para><hostid>foo.example.org.</hostid> is a subdomain, a zone under the
<hostid>example.org.</hostid> zone
</para>
</listitem>
<listitem>
<para>
<hostid>1.2.3.in-addr.arpa</hostid> is a zone referencing all IP addresses
which fall under the 3.2.1.* IP space.
</para>
</listitem>
</itemizedlist>
<para>As one can see, the more specific part of a hostname appears to
its left. For example, <hostid>example.org.</hostid> is more
specific than <hostid>org.</hostid>, as <hostid>org.</hostid> is
more specific than the root zone. The layout of each part of
a hostname is much like a filesystem: the <filename>/dev</filename>
directory falls within the root, and so on.</para>
</sect2>
<sect2>
<title>Reasons to Run a Name Server</title>
<para>Name servers usually come in two forms: an authoritative
name server, and a caching name server.</para>
<para>An authoritative name server is needed when:</para>
<itemizedlist>
<listitem>
<para>one wants to serve DNS information to the
world, replying authoritatively to queries.</para>
</listitem>
<listitem>
<para>a domain, such as <hostid>example.org</hostid>, is
registered and IP addresses need to be assigned to hostnames
under it.</para>
</listitem>
<listitem>
<para>an IP address block requires reverse DNS entries (IP to
hostname).</para>
</listitem>
<listitem>
<para>a backup name server, called a slave, must reply to queries
when the primary is down or inaccessible.</para>
</listitem>
</itemizedlist>
<para>A caching name server is needed when:</para>
<itemizedlist>
<listitem>
<para>a local DNS server may cache and respond more quickly
then querying an outside name server.</para>
</listitem>
<listitem>
<para>a reduction in overall network traffic is desired (DNS
traffic has been measured to account for 5% or more of total
Internet traffic).</para>
</listitem>
</itemizedlist>
<para>When one queries for <hostid>www.FreeBSD.org</hostid>, the
resolver usually queries the uplink ISP's name server, and retrieves
the reply. With a local, caching DNS server, the query only has to
be made once to the outside world by the caching DNS server. Every
additional query will not have to look to the outside of the local
network, since the information is cached locally.</para>
</sect2>
<sect2>
<title>How It Works</title>
<para>In FreeBSD, the BIND daemon is called
<application>named</application> for obvious reasons.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>File</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><application>named</application></entry>
<entry>the BIND daemon</entry>
</row>
<row>
<entry><command>ndc</command></entry>
<entry>name daemon control program</entry>
</row>
<row>
<entry><filename>/etc/namedb</filename></entry>
<entry>directory where BIND zone information resides</entry>
</row>
<row>
<entry><filename>/etc/namedb/named.conf</filename></entry>
<entry>daemon configuration file</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
Zone files are usually contained within the
<filename>/etc/namedb</filename>
directory, and contain the DNS zone information
served by the 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 <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 the local reverse DNS zone file in
<filename>/etc/namedb/localhost.rev</filename>.
</para>
</sect3>
<sect3>
<title><filename>/etc/namedb/named.conf</filename></title>
<programlisting>// &dollar;FreeBSD$
//
// Refer to the named(8) manual 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, to benefit from an uplink's cache,
<literal>forwarders</literal> can be enabled here. Under normal
circumstances, a name server will recursively query the Internet
looking at certain name servers until it finds the answer it is
looking for. Having this enabled will have it query the uplink's
name server (or name server provided) first, taking advantage of
its cache. If the uplink name server in question is a heavily
trafficked, fast name server, enabling this may be worthwhile.
</para>
<warning><para><hostid role="ipaddr">127.0.0.1</hostid>
will <emphasis>not</emphasis> work here.
Change this IP address to a name server at your uplink.</para>
</warning>
<programlisting> /*
* If there is a firewall between you and name servers 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</programlisting>
<para>For more information on running BIND in a sandbox, see
<link linkend="named-sandbox">Running named in a sandbox</link>.
</para>
<programlisting>/*
zone "example.com" {
type slave;
file "s/example.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>In <filename>named.conf</filename>, these are examples of slave
entries for a forward and reverse zone.</para>
<para>For each new zone served, a new zone entry must be added to
<filename>named.conf</filename></para>
<para>For example, the simplest zone entry for
<hostid role="domainname">example.org</hostid> can look like:</para>
<programlisting>zone "example.org" {
type master;
file "example.org";
};</programlisting>
<para>The zone is a master, as indicated by the <option>type</option>
statement, holding its zone information in
<filename>/etc/namedb/example.org</filename> indicated by
the <option>file</option> statement.</para>
<programlisting>zone "example.org" {
type slave;
file "example.org";
};</programlisting>
<para>In the slave case, the zone information is transferred from
the master name server for the particular zone, and saved in the
file specified. If and when the master server dies or is
unreachable, the slave name server will have the transferred
zone information and will be able to serve it.</para>
</sect3>
<sect3>
<title>Zone Files</title>
<para>
An example master zone file for <hostid>example.org</hostid>
(existing within <filename>/etc/namedb/example.org</filename>)
is as follows:
</para>
<programlisting>$TTL 3600
example.org. IN SOA ns1.example.org. admin.example.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
86400 ) ; Minimum TTL
; DNS Servers
@ IN NS ns1.example.org.
@ IN NS ns2.example.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.example.org.</programlisting>
<para>
Note that every hostname ending in a <quote>.</quote> is an
exact hostname, whereas everything without a trailing
<quote>.</quote> is referenced to the origin. For example,
<literal>www</literal> is translated into <literal>www +
origin</literal>. In our fictitious zone file, our origin
is <hostid>example.org.</hostid>, so
<literal>www</literal> would translate to
<hostid>www.example.org.</hostid>
</para>
<para>
The format of a zone 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>
<variablelist>
<varlistentry>
<term>SOA</term>
<listitem><para>start of zone authority</para></listitem>
</varlistentry>
<varlistentry>
<term>NS</term>
<listitem><para>an authoritative name server</para></listitem>
</varlistentry>
<varlistentry>
<term>A</term>
<listitem><para>A host address</para></listitem>
</varlistentry>
<varlistentry>
<term>CNAME</term>
<listitem><para>the canonical name for an alias</para></listitem>
</varlistentry>
<varlistentry>
<term>MX</term>
<listitem><para>mail exchanger</para></listitem>
</varlistentry>
<varlistentry>
<term>PTR</term>
<listitem><para>a domain name pointer (used in reverse DNS)
</para></listitem>
</varlistentry>
</variablelist>
<programlisting>
example.org. IN SOA ns1.example.org. admin.example.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>
<variablelist>
<varlistentry>
<term><hostid>example.org.</hostid></term>
<listitem><para>the domain name, also the origin for this
zone file.</para></listitem>
</varlistentry>
<varlistentry>
<term><hostid>ns1.example.org.</hostid></term>
<listitem><para>the primary/authoritative name server for this
zone</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>admin.example.org.</literal></term>
<listitem><para>the responsible person for this zone,
email address with @
replaced. (<email>admin@example.org</email> becomes
<literal>admin.example.org</literal>)</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>5</literal></term>
<listitem><para>the serial number of the file. this
must be incremented each time the zone file is modified.
Nowadays, many admins prefer a
<literal>yyyymmddrr</literal> 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 name servers for a zone when it is
updated.</para>
</listitem>
</varlistentry>
</variablelist>
<programlisting>
@ IN NS ns1.example.org.</programlisting>
<para>
This is an <varname>NS</varname> entry. Every name server that is going to reply
authoritatively for the zone must have one of these entries.
The <literal>@</literal> as seen here could have been
<hostid role="domainname">example.org.</hostid>
The <literal>@</literal> 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,
<hostid>ns1.example.org</hostid> would resolve to
<hostid role="ipaddr">3.2.1.2</hostid>. Again,
the origin symbol, <literal>@</literal>, is
used here, thus meaning <hostid>example.org</hostid>
would resolve to <hostid role="ipaddr">3.2.1.30</hostid>.
</para>
<programlisting>
www IN CNAME @</programlisting>
<para>
The canonical name record is usually used for giving aliases
to a machine. In the example, <hostid>www</hostid> is
aliased to the machine addressed to the origin, or
<hostid>example.org</hostid>
(<hostid role="ipaddr">3.2.1.30</hostid>).
<varname>CNAME</varname>s can be used to provide alias
hostnames, or round robin one hostname among multiple
machines.
</para>
<programlisting>
@ IN MX 10 mail.example.org.</programlisting>
<para>
The <varname>MX</varname> record indicates which mail servers are responsible
for handling incoming mail for the zone.
<hostid role="fqdn">mail.example.org</hostid> is the hostname of the mail server,
and 10 being the priority of that mail server.
</para>
<para>
One can have several mail servers, with priorities of 3, 2,
1. A mail server attempting to deliver to <hostid role="domainname">example.org</hostid>
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 <varname>PTR</varname> entries instead of
<varname>A</varname> or <varname>CNAME</varname>.
</para>
<programlisting>$TTL 3600
1.2.3.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
5 ; Serial
10800 ; Refresh
3600 ; Retry
604800 ; Expire
3600 ) ; Minimum
@ IN NS ns1.example.org.
@ IN NS ns2.example.org.
2 IN PTR ns1.example.org.
3 IN PTR ns2.example.org.
10 IN PTR mail.example.org.
30 IN PTR example.org.</programlisting>
<para>
This file gives the proper IP address 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 name server is a name server 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">
<sect2info>
<authorgroup>
<author>
<firstname>Ceri</firstname>
<surname>Davies</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect2info>
<title>Running named in a Sandbox</title>
<indexterm>
<primary>BIND</primary>
<secondary>running in a sandbox</secondary>
</indexterm>
<indexterm>
<primary><command>chroot</command></primary>
</indexterm>
<para>For added security you may want to run &man.named.8; as an
unprivileged user, and configure it to &man.chroot.8; into a
sandbox directory. This makes everything outside of the sandbox
inaccessible to the <application>named</application> daemon. Should
<application>named</application> be compromised, this will help to
reduce the damage that can be caused. By default, FreeBSD has a user
and a group called <groupname>bind</groupname>, intended for this
use.</para>
<note><para>Various people would recommend that instead of configuring
<application>named</application> to <command>chroot</command>, you
should run <application>named</application> inside a &man.jail.8;.
This section does not attempt to cover this situation.</para>
</note>
<para>Since <application>named</application> will not be able to
access anything outside of the sandbox (such as shared
libraries, log sockets, and so on), there are a number of steps
that need to be followed in order to allow
<application>named</application> to function correctly. In the
following checklist, it is assumed that the path to the sandbox
is <filename>/etc/namedb</filename> and that you have made no
prior modifications to the contents of this directory. Perform
the following steps as <username>root</username>.</para>
<itemizedlist>
<listitem>
<para>Create all directories that <application>named</application>
expects to see:</para>
<screen>&prompt.root; <userinput>cd /etc/namedb</userinput>
&prompt.root; <userinput>mkdir -p bin dev etc var/tmp var/run master slave</userinput>
&prompt.root; <userinput>chown bind:bind slave var/*</userinput><co id="chown-slave"></screen>
<calloutlist>
<callout arearefs="chown-slave">
<para><application>named</application> only needs write access to
these directories, so that is all we give it.</para>
</callout>
</calloutlist>
</listitem>
<listitem>
<para>Rearrange and create basic zone and configuration files:</para>
<screen>&prompt.root; <userinput>cp /etc/localtime etc</userinput><co id="localtime">
&prompt.root; <userinput>mv named.conf etc && ln -sf etc/named.conf</userinput>
&prompt.root; <userinput>mv named.root master</userinput>
<!-- I don't like this next bit -->
&prompt.root; <userinput>sh make-localhost && mv localhost.rev localhost-v6.rev master</userinput>
&prompt.root; <userinput>cat > master/named.localhost
$ORIGIN localhost.
$TTL 6h
@ IN SOA localhost. postmaster.localhost. (
1 ; serial
3600 ; refresh
1800 ; retry
604800 ; expiration
3600 ) ; minimum
IN NS localhost.
IN A 127.0.0.1
^D</userinput></screen>
<calloutlist>
<callout arearefs="localtime">
<para>This allows <application>named</application> to log the
correct time to &man.syslogd.8;</para>
</callout>
</calloutlist>
</listitem>
<listitem>
<para>Build a statically linked copy of
<application>named-xfer</application>, and copy it into the sandbox:</para>
<screen>&prompt.root; <userinput>cd /usr/src/lib/libisc && make clean all</userinput>
&prompt.root; <userinput>cd /usr/src/lib/libbind && make clean all</userinput>
&prompt.root; <userinput>cd /usr/src/libexec/named-xfer && make NOSHARED=yes all</userinput>
&prompt.root; <userinput>cp named-xfer /etc/namedb/bin && chmod 555 /etc/namedb/bin/named-xfer</userinput><co id="clean-cruft"></screen>
<calloutlist>
<callout arearefs="clean-cruft">
<para>This step has been reported to fail occasionally. If this
happens to you, then issue the command:</para>
<screen>&prompt.root; <userinput>cd /usr/src && make cleandir && make cleandir</userinput></screen>
<para>This will clean out any <quote>cruft</quote> from your
source tree, and retrying the steps above should then work.</para>
</callout>
</calloutlist>
</listitem>
<listitem>
<para>Make a <devicename>dev/null</devicename> that
<application>named</application> can see and write to:</para>
<screen>&prompt.root; <userinput>cd /etc/namedb/dev && mknod null c 2 2</userinput>
&prompt.root; <userinput>chmod 666 null</userinput></screen>
</listitem>
<listitem>
<para>Symlink <filename> /var/run/ndc</filename> to
<filename>/etc/namedb/var/run/ndc</filename>:</para>
<screen>&prompt.root; <userinput>ln -sf /etc/namedb/var/run/ndc /var/run/ndc</userinput></screen>
<note>
<para>This simply avoids having to specify the
<option>-c</option> option to &man.ndc.8; every time you
run it. Since the contents of /var/run are deleted on boot,
if this is something that you find useful you
may wish to add this command to root's crontab, making use
of the <option>@reboot</option> option. See
&man.crontab.5; for more information regarding
this.</para>
</note>
</listitem>
<listitem>
<para>Configure &man.syslogd.8; to create an extra
<devicename>log</devicename> socket that
<application>named</application> can write to. To do this,
add <literal>-l /etc/namedb/dev/log</literal> to the
<varname>syslogd_flags</varname> variable in
<filename>/etc/rc.conf</filename>.</para>
</listitem>
<listitem>
<para>Arrange to have <application>named</application> start
and <command>chroot</command> itself to the sandbox by
adding the following to
<filename>/etc/rc.conf</filename>:</para>
<programlisting>named_enable="YES"
named_flags="-u bind -g bind -t /etc/namedb /etc/named.conf"</programlisting>
<note>
<para>Note that the configuration file
<replaceable>/etc/named.conf</replaceable> is denoted by a full
pathname <emphasis>relative to the sandbox</emphasis>, i.e. in
the line above, the file referred to is actually
<filename>/etc/namedb/etc/named.conf</filename>.</para>
</note>
</listitem>
</itemizedlist>
<para>The next step is to edit
<filename>/etc/namedb/etc/named.conf</filename> so that
<application>named</application> knows which zones to load and
where to find them on the disk. There follows a commented
example (anything not specifically commented here is no
different from the setup for a DNS server not running in a
sandbox):</para>
<programlisting>options {
directory "/";<co id="directory">
named-xfer "/bin/named-xfer";<co id="named-xfer">
version ""; // Don't reveal BIND version
query-source address * port 53;
};
// ndc control socket
controls {
unix "/var/run/ndc" perm 0600 owner 0 group 0;
};
// Zones follow:
zone "localhost" IN {
type master;
file "master/named.localhost";<co id="master">
allow-transfer { localhost; };
notify no;
};
zone "0.0.127.in-addr.arpa" IN {
type master;
file "master/localhost.rev";
allow-transfer { localhost; };
notify no;
};
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 "master/localhost-v6.rev";
allow-transfer { localhost; };
notify no;
};
zone "." IN {
type hint;
file "master/named.root";
};
zone "private.example.net" in {
type master;
file "master/private.example.net.db";
allow-transfer { 192.168.10.0/24; };
};
zone "10.168.192.in-addr.arpa" in {
type slave;
masters { 192.168.10.2; };
file "slave/192.168.10.db";<co id="slave">
};</programlisting>
<calloutlist>
<callout arearefs="directory">
<para>The
<literal>directory</literal> statement is specified as
<filename>/</filename>, since all files that
<application>named</application> needs are within this
directory (recall that this is equivalent to a
<quote>normal</quote> user's
<filename>/etc/namedb</filename>.</para>
</callout>
<callout arearefs="named-xfer">
<para>Specifies the full path
to the <command>named-xfer</command> binary (from
<application>named</application>'s frame of reference). This
is necessary since <application>named</application> is
compiled to look for <command>named-xfer</command> in
<filename>/usr/libexec</filename> by default.</para>
</callout>
<callout arearefs="master"><para>Specifies the filename (relative
to the <literal>directory</literal> statement above) where
<application>named</application> can find the zonefile for this
zone.</para>
</callout>
<callout arearefs="slave"><para>Specifies the filename
(relative to the <literal>directory</literal> statement above)
where <application>named</application> should write a copy of
the zonefile for this zone after successfully transferring it
from the master server. This is why we needed to change the
ownership of the directory <filename>slave</filename> to
<groupname>bind</groupname> in the setup stages above.</para>
</callout>
</calloutlist>
<para>After completing the steps above, either reboot your
server or restart &man.syslogd.8; and start &man.named.8;, making
sure to use the new options specified in
<varname>syslogd_flags</varname> and
<varname>named_flags</varname>. You should now be running a
sandboxed copy of <application>named</application>!</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="../handbook/eresources.html#ERESOURCES-MAIL">freebsd-security-notifications</ulink>
to stay up to date with the current Internet and FreeBSD security
issues.
</para>
<tip><para>If a problem arises, keeping sources up to date and having a
fresh build of named would not hurt.</para></tip>
</sect2>
<sect2>
<title>Further Reading</title>
<para>
BIND/named manual pages: &man.ndc.8; &man.named.8; &man.named.conf.5;
</para>
<itemizedlist>
<listitem>
<para><ulink
url="http://www.isc.org/products/BIND/">Official ISC Bind
Page</ulink></para>
</listitem>
<listitem>
<para><ulink
url="http://www.nominum.com/resources/faqs/bind-faqs.html">
BIND FAQ</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.oreilly.com/catalog/dns4/">O'Reilly
DNS and BIND 4th Edition</ulink></para>
</listitem>
<listitem>
<para><ulink
url="ftp://ftp.isi.edu/in-notes/rfc1034.txt">RFC1034
- Domain Names - Concepts and Facilities</ulink></para>
</listitem>
<listitem>
<para><ulink
url="ftp://ftp.isi.edu/in-notes/rfc1035.txt">RFC1035
- Domain Names - Implementation and Specification</ulink></para>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="ntp">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Hukins</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>NTP</title>
<indexterm><primary>NTP</primary></indexterm>
<sect2>
<title>Overview</title>
<para>Over time, a computer's clock is prone to drift. As time
passes, the computer's clock becomes less accurate. NTP
(Network Time Protocol) is one way to ensure your clock is
right.</para>
<para>Many Internet services rely on, or greatly benefit from,
computers' clocks being accurate. For example, a Web server
may receive requests to send a file if it has modified since a
certain time. Services such as &man.cron.8; run commands at a
given time. If the clock is inaccurate, these commands may
not run when expected.</para>
<indexterm>
<primary>NTP</primary>
<secondary>ntpd</secondary>
</indexterm>
<para>FreeBSD ships with the &man.ntpd.8; NTP server which can
be used to query other NTP servers to set the clock on your
machine or provide time services to others.</para>
</sect2>
<sect2>
<title>Choosing Appropriate NTP Servers</title>
<indexterm>
<primary>NTP</primary>
<secondary>choosing servers</secondary>
</indexterm>
<para>In order to synchronize your clock, you will need to find
one or more NTP servers to use. Your network administrator or
ISP may have setup an NTP server for this purpose&mdash;check
their documentation to see if this is the case. There is a
<ulink
url="http://www.eecis.udel.edu/~mills/ntp/servers.html">list of
publicly accessible NTP servers</ulink> which you can use to
find an NTP server near to you. Make sure you are aware of
the policy for any servers you choose, and ask for permission
if required.</para>
<para>Choosing several unconnected NTP servers is a good idea in
case one of the servers you are using becomes unreachable or
its clock is unreliable. &man.ntpd.8; uses the responses it
receives from other servers intelligently&mdash;it will favor
unreliable servers less than reliable ones.</para>
</sect2>
<sect2>
<title>Configuring Your Machine</title>
<indexterm>
<primary>NTP</primary>
<secondary>configuration</secondary>
</indexterm>
<sect3>
<title>Basic Configuration</title>
<indexterm><primary>ntpdate</primary></indexterm>
<para>If you only wish to synchronize your clock when the
machine boots up, you can use &man.ntpdate.8;. This may be
appropriate for some desktop machines which are frequently
rebooted and only require infrequent synchronization, but
most machines should run &man.ntpd.8;.</para>
<para>Using &man.ntpdate.8; at boot time is also a good idea
for machines that run &man.ntpd.8;. &man.ntpd.8; changes the
clock gradually, whereas &man.ntpdate.8; sets the clock, no
matter how great the difference between a machine's current
clock setting and the correct time.</para>
<para>To enable &man.ntpdate.8; at boot time, add
<programlisting>ntpdate_enable="YES"</programlisting> to
<filename>/etc/rc.conf</filename>. You will also need to
specify all servers you wish to synchronize with and any
flags to be passed to &man.ntpdate.8; in
<varname>ntpdate_flags</varname>.</para>
</sect3>
<sect3>
<indexterm>
<primary>NTP</primary>
<secondary>ntp.conf</secondary>
</indexterm>
<title>General Configuration</title>
<para>NTP is configured by the
<filename>/etc/ntp.conf</filename> file in the format
described in &man.ntp.conf.5;. Here is a simple
example:</para>
<programlisting>server ntplocal.example.com prefer
server timeserver.example.org
server ntp2a.example.net
driftfile /var/db/ntp.drift</programlisting>
<para>The <literal>server</literal> option specifies which
servers are to be used, with one server listed on each line.
If a server is specified with the <literal>prefer</literal>
argument, as with <hostid
role="fqdn">ntplocal.example.com</hostid>, that server is
preferred over other servers. A response from a preferred
server will be discarded if it differs significantly from
other servers' responses, otherwise it will be used without
any consideration to other responses. The
<literal>prefer</literal> argument is normally used for NTP
servers that are known to be highly accurate, such as those
with special time monitoring hardware.</para>
<para>The <literal>driftfile</literal> option specifies which
file is used to store the system clock's frequency offset.
&man.ntpd.8; uses this to automatically compensate for the
clock's natural drift, allowing it to maintain a reasonably
correct setting even if it is cut off from all external time
sources for a period of time.</para>
<para>The <literal>driftfile</literal> option specifies which
file is used to store information about previous responses
from the NTP servers you are using. This file contains
internal information for NTP. It should not be modified by
any other process.</para>
</sect3>
<sect3>
<title>Controlling Access to Your Server</title>
<para>By default, your NTP server will be accessible to all
hosts on the Internet. The <literal>restrict</literal>
option in &man.ntp.conf.5; allows you to control which
machines can access your server.</para>
<para>If you want to deny all machines from accessing your NTP
server, add the line <programlisting>restrict default ignore</programlisting>
to <filename>/etc/ntp.conf</filename>. If you only want to
allow machines within your own network to synchronize their
clocks with your server, but ensure they are not allowed to
configure the server or used as peers to synchronize
against, add <programlisting>restrict 192.168.1.0 mask 255.255.255.0 notrust nomodify notrap</programlisting>
instead, where <hostid role="ipaddr">192.168.1.0</hostid> is
an IP address on your network and <hostid
role="netmask">255.255.255.0</hostid> is your network's
netmask.</para>
<para><filename>/etc/ntp.conf</filename> can contain multiple
<literal>restrict</literal> options. For more details, see
the <literal>Access Control Support</literal> subsection of
&man.ntp.conf.5;.</para>
</sect3>
</sect2>
<sect2>
<title>Running the NTP Server</title>
<para>To ensure the NTP server is started at boot time, add the
line <programlisting>xntpd_enable="YES"</programlisting> to
<filename>/etc/rc.conf</filename>. If you wish to pass
additional flags to &man.ntpd.8; edit the
<varname>xntpd_flags</varname> parameter in
<filename>/etc/rc.conf</filename>.</para>
<para>To start the server without rebooting your machine, run
<command>ntpd</command> being sure to specify any additional
parameters from <varname>xntpd_flags</varname> in
<filename>/etc/rc.conf</filename>. For example:</para>
<screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen>
</sect2>
<sect2>
<title>Using &man.ntpd.8; with a temporary Internet
connection</title>
<para><command>ntpd</command> does not need a permanent
connection to the Internet to function properly. However, if
you have a temporary connection that is configured to dial out
on demand, it is a good idea to prevent NTP traffic from
triggering a dial out or keeping the connection alive. If you
are using user PPP, you can use <literal>filter</literal>
directives in <filename>/etc/ppp/ppp.conf</filename>. For
example:</para>
<programlisting> set filter dial 0 deny udp src eq 123
# Prevent NTP traffic from initiating dial out
set filter dial 1 permit 0 0
set filter alive 0 deny udp src eq 123
# Prevent incoming NTP traffic from keeping the connection open
set filter alive 1 deny udp dst eq 123
# Prevent outgoing NTP traffic from keeping the connection open
set filter alive 2 permit 0/0 0/0</programlisting>
<para>For more details see the <literal>PACKET
FILTERING</literal> section in &man.ppp.8; and the examples in
<filename>/usr/share/examples/ppp/</filename>.</para>
<note>
<para>Some Internet access providers block low-numbered ports,
preventing NTP from functioning since replies never
reach your machine.</para>
</note>
</sect2>
<sect2>
<title>Further Information</title>
<para>Documentation for the NTP server can be found in
<filename>/usr/share/doc/ntp/</filename> in HTML
format.</para>
</sect2>
</sect1>
<sect1 id="natd">
<sect1info>
<authorgroup>
<author>
<firstname>Chern</firstname>
<surname>Lee</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Network Address Translation</title>
<sect2 id="overview">
<title>Overview</title>
<indexterm>
<primary><application>natd</application></primary>
</indexterm>
<para>FreeBSD's Network Address Translation daemon, commonly known as
&man.natd.8; is a daemon that accepts incoming raw IP packets,
changes the source to the local machine and re-injects these packets
back into the outgoing IP packet stream. natd does this by changing
the source IP address and port such that when data is received back,
it is able to determine the original location of the data and forward
it back to its original requester.</para>
<indexterm><primary>Internet connection sharing</primary></indexterm>
<indexterm><primary>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
increasingly in need of an Internet Connection Sharing solution. The
ability to connect several computers online through one connection and
IP address makes &man.natd.8; a reasonable choice.</para>
<para>Most commonly, a user has a machine connected to a cable or DSL
line with one IP address and wishes to use this one connected computer to
provide Internet access to several more over a LAN.</para>
<para>To do this, the FreeBSD machine on the Internet must act as a
gateway. This gateway machine must have two NICs--one for connecting
to the Internet router, the other connecting to a LAN. All the
machines on the LAN are connected through a hub or switch.</para>
<mediaobject>
<imageobject>
<imagedata fileref="advanced-networking/natd">
</imageobject>
<textobject>
<literallayout class="monospaced"> _______ __________ ________
| | | | | |
| Hub |-----| Client B |-----| Router |----- Internet
|_______| |__________| |________|
|
____|_____
| |
| Client A |
|__________|</literallayout>
</textobject>
<textobject>
<phrase>Network Layout</phrase>
</textobject>
</mediaobject>
<para>A setup like this is commonly used to share an Internet
connection. One of the <acronym>LAN</acronym> machines is
connected to the Internet. The rest of the machines access
the Internet through that <quote>gateway</quote>
machine.</para>
</sect2>
<sect2 id="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 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 address
numbers in the private network space as defined by
<ulink url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink>
and have a default gateway of the natd machine's internal IP address.</para>
<para>For example, client <hostid>a</hostid> and <hostid>b</hostid> behind the LAN have IP addresses
of <hostid role="ipaddr">192.168.0.2</hostid> and
<hostid role="ipaddr">192.168.0.3</hostid>, while the natd
machine's LAN interface has an IP address of
<hostid role="ipaddr">192.168.0.1</hostid>. Client <hostid>a</hostid> and <hostid>b</hostid>'s
default gateway must be set to that of the natd machine,
<hostid role="ipaddr">192.168.0.1</hostid>.
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 IP addresses are
available, yet they must be on one machine. With this,
&man.natd.8; can assign each LAN client its own external IP address.
&man.natd.8; then rewrites outgoing packets from the LAN clients
with the proper external IP address and redirects
all traffic incoming on that particular IP address back to
the specific LAN client. This is also known as static NAT.
For example, the IP addresses <hostid role="ipaddr">128.1.1.1</hostid>,
<hostid role="ipaddr">128.1.1.2</hostid>, and
<hostid role="ipaddr">128.1.1.3</hostid> belong to the natd gateway
machine. <hostid role="ipaddr">128.1.1.1</hostid> can be used
as the natd gateway machine's external IP address, while
<hostid role="ipaddr">128.1.1.2</hostid> and
<hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to LAN
clients A and B.</para>
<para>The -redirect_address syntax is as follows:</para>
<para><option> -redirect_address localIP publicIP</option>
</para>
<informaltable frame="none">
<tgroup cols="2">
<tbody>
<row>
<entry>localIP</entry>
<entry>The internal IP address of the LAN client.</entry>
</row>
<row>
<entry>publicIP</entry>
<entry>The external IP address corresponding to the LAN client.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>In the example, this argument would read:</para>
<para><option> -redirect_address 192.168.0.2 128.1.1.2
-redirect_address 192.168.0.3 128.1.1.3</option></para>
<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 IP addresses 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>
<sect1 id="inetd">
<sect1info>
<authorgroup>
<author>
<firstname>Chern</firstname>
<surname>Lee</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>inetd <quote>Super-Server</quote></title>
<sect2 id="inetd-overview">
<title>Overview</title>
<para>&man.inetd.8; is referred to as the <quote>Internet
Super-Server</quote> because it manages connections for several
daemons. Programs that provide network service are commonly
known as daemons. <application>inetd</application> serves as a
managing server for other daemons. When a connection is
received by <application>inetd</application>, it determines
which daemon the connection is destined for, spawns the
particular daemon and delegates the socket to it. Running one
instance of <application>inetd</application> reduces the overall
system load as compared to running each daemon individually in
stand-alone mode.</para>
<para>Primarily, <application>inetd</application> is used to
spawn other daemons, but several trivial protocols are handled
directly, such as <application>chargen</application>,
<application>auth</application>, and
<application>daytime</application>.</para>
<para>This section will cover the basics in configuring
<application>inetd</application> through its command-line
options and its configuration file,
<filename>/etc/inetd.conf</filename>.</para>
</sect2>
<sect2 id="inetd-settings">
<title>Settings</title>
<para><application>inetd</application> is initialized through
the <filename>/etc/rc.conf</filename> system. The
<literal>inetd_enable</literal> option is set to
<quote>NO</quote> by default, but is often times turned on by
<application>sysinstall</application> with the medium security
profile. Placing:
<programlisting>inetd_enable="YES"</programlisting> or
<programlisting>inetd_enable="NO"</programlisting> into
<filename>/etc/rc.conf</filename> can enable or disable
<application>inetd</application> starting at boot time.</para>
<para>Additionally, different command-line options can be passed
to <application>inetd</application> via the
<literal>inetd_flags</literal> option.</para>
</sect2>
<sect2 id="inetd-cmdline">
<title>Command-Line Options</title>
<para><application>inetd</application> synopsis:</para>
<para><option> inetd [-d] [-l] [-w] [-W] [-c maximum] [-C rate] [-a address | hostname]
[-p filename] [-R rate] [configuration file]</option></para>
<variablelist>
<varlistentry>
<term>-d</term>
<listitem>
<para>Turn on debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-l</term>
<listitem>
<para>Turn on logging of successful connections.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-w</term>
<listitem>
<para>Turn on TCP Wrapping for external services (on by
default).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-W</term>
<listitem>
<para>Turn on TCP Wrapping for internal services which are
built into <application>inetd</application> (on by
default).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c maximum</term>
<listitem>
<para>Specify the default maximum number of simultaneous
invocations of each service; the default is unlimited.
May be overridden on a per-service basis with the
<option>max-child</option> parameter.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-C rate</term>
<listitem>
<para>Specify the default maximum number of times a
service can be invoked from a single IP address in one
minute; the default is unlimited. May be overridden on a
per-service basis with the
<option>max-connections-per-ip-per-minute</option>
parameter.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-R rate</term>
<listitem>
<para>Specify the maximum number of times a service can be
invoked in one minute; the default is 256. A rate of 0
allows an unlimited number of invocations.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-a</term>
<listitem>
<para>Specify one specific IP address to bind to.
Alternatively, a hostname can be specified, in which case
the IPv4 or IPv6 address which corresponds to that
hostname is used. Usually a hostname is specified when
<application>inetd</application> is run inside a
&man.jail.8;, in which case the hostname corresponds to
the &man.jail.8; environment.</para>
<para>When hostname specification is used and both IPv4
and IPv6 bindings are desired, one entry with the
appropriate protocol type for each binding is required for
each service in <filename>/etc/inetd.conf</filename>. For
example, a TCP-based service would need two entries, one
using <quote>tcp4</quote> for the protocol and the other using
<quote>tcp6</quote>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p</term>
<listitem>
<para>Specify an alternate file in which to store the
process ID.</para>
</listitem>
</varlistentry>
</variablelist>
<para>These options can be passed to
<application>inetd</application> using the
<literal>inetd_flags</literal> option in
<filename>/etc/rc.conf</filename>. By default,
<literal>inetd_flags</literal> is set to <quote>-wW</quote>,
which turns on TCP wrapping for
<application>inetd</application>'s internal and external
services. For novice users, these parameters usually do not need
to be modified or even entered in
<filename>/etc/rc.conf</filename>.</para>
<note>
<para>An external service is a daemon outside of
<application>inetd</application>, which is invoked when a
connection is received for it. On the other hand, an internal
service is one that <application>inetd</application> has the
facility of offering within itself.</para>
</note>
</sect2>
<sect2 id="inetd-conf">
<title><filename>inetd.conf</filename></title>
<para>Configuration of <application>inetd</application> is
controlled through the <filename>/etc/inetd.conf</filename>
file.</para>
<para>When a modification is made to
<filename>/etc/inetd.conf</filename>,
<application>inetd</application> can be forced to re-read its
configuration file by sending a HangUP signal to the
<application>inetd</application> process as shown:</para>
<example id="inetd-hangup">
<title>Sending <application>inetd</application> a HangUP Signal</title>
<screen>&prompt.root; <userinput>kill -HUP `cat /var/run/inetd.pid`</userinput></screen>
</example>
<para>Each line of the configuration file specifies an
individual daemon. Comments in the file are preceded by a
<quote>#</quote>. The format of
<filename>/etc/inetd.conf</filename> is as follows:</para>
<programlisting>service-name
socket-type
protocol
{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]
user[:group][/login-class]
server-program
server-program-arguments</programlisting>
<para>An example entry for the <application>ftpd</application> daemon
using IPv4:</para>
<programlisting>ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l</programlisting>
<variablelist>
<varlistentry>
<term>service-name</term>
<listitem>
<para>This is the service name of the particular daemon.
It must correspond to a service listed in
<filename>/etc/services</filename>. This determines which
port <application>inetd</application> must listen to. If
a new service is being created, it must be placed in
<filename>/etc/services</filename>
first.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>socket-type</term>
<listitem>
<para>Either <literal>stream</literal>,
<literal>dgram</literal>, <literal>raw</literal>, or
<literal>seqpacket</literal>. <literal>stream</literal>
must be used for connection-based, TCP daemons, while
<literal>dgram</literal> is used for daemons utilizing the
UDP transport protocol.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>protocol</term>
<listitem>
<para>One of the following:</para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Protocol</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry>tcp, tcp4</entry>
<entry>TCP IPv4</entry>
</row>
<row>
<entry>udp, udp4</entry>
<entry>UDP IPv4</entry>
</row>
<row>
<entry>tcp6</entry>
<entry>TCP IPv6</entry>
</row>
<row>
<entry>udp6</entry>
<entry>UDP IPv6</entry>
</row>
<row>
<entry>tcp46</entry>
<entry>Both TCP IPv4 and v6</entry>
</row>
<row>
<entry>udp46</entry>
<entry>Both UDP IPv4 and v6</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</varlistentry>
<varlistentry>
<term>{wait|nowait}[/max-child[/max-connections-per-ip-per-minute]]</term>
<listitem>
<para><option>wait|nowait</option> indicates whether the
daemon invoked from <application>inetd</application> is
able to handle its own socket or not.
<option>dgram</option> socket types must use the wait
option, while stream socket daemons, which are usually
multi-threaded, should use <option>nowait</option>.
<option>wait</option> usually hands off multiple sockets
to a single daemon, while <option>nowait</option> spawns a
child daemon for each new socket.</para>
<para>The maximum number of child daemons
<application>inetd</application> may spawn can be set using
the <option>max-child</option> option. If a limit of ten
instances of a particular daemon is needed, a
<literal>/10</literal> would be placed after
<option>nowait</option>.</para>
<para>In addition to <option>max-child</option>, another
option limiting the maximum connections from a single
place to a particular daemon can be enabled.
<option>max-connections-per-ip-per-minute</option> does
just this. A value of ten here would limit any particular
IP address connecting to a particular service to ten
attempts per minute. This is useful to prevent
intentional or unintentional resource consumption and
Denial of Service (DoS) attacks to a machine.</para>
<para>In this field, <option>wait</option> or
<option>nowait</option> is mandatory.
<option>max-child</option> and
<option>max-connections-per-ip-per-minute</option> are
optional.</para>
<para>A stream-type multi-threaded daemon without any
<option>max-child</option> or
<option>max-connections-per-ip-per-minute</option> limits
would simply be: <literal>nowait</literal></para>
<para>The same daemon with a maximum limit of ten daemons
would read: <literal>nowait/10</literal></para>
<para>Additionally, the same setup with a limit of twenty
connections per IP address per minute and a maximum
total limit of ten child daemons would read:
<literal>nowait/10/20</literal></para>
<para>These options are all utilized by the default
settings of the <application>fingerd</application> daemon,
as seen here:</para>
<programlisting>finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>user</term>
<listitem>
<para>The user is the username that the particular daemon
should run as. Most commonly, daemons run as the
<username>root</username> user. For security purposes, it is
common to find some servers running as the
<username>daemon</username> user, or the least privileged
<username>nobody</username> user.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>server-program</term>
<listitem>
<para>The full path of the daemon to be executed when a
connection is received. If the daemon is a service
provided by <application>inetd</application> internally,
then <option>internal</option> should be
used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>server-program-arguments</term>
<listitem>
<para>This works in conjunction with
<option>server-program</option> by specifying the
arguments, starting with argv[0], passed to the daemon on
invocation. If <application>mydaemon -d</application> is
the command line, <literal>mydaemon -d</literal> would be
the value of <option>server program arguments</option>.
Again, if the daemon is an internal service, use
<option>internal</option> here.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="inetd-security">
<title>Security</title>
<para>Depending on the security profile chosen at install, many
of <application>inetd</application>'s daemons may be enabled by
default. If there is no apparent need for a particular daemon,
disable it! Place a <quote>#</quote> in front of the daemon in
question, and send a <link linkend="inetd-hangup">hangup signal
to inetd</link>.
Some daemons, such as <application>fingerd</application>, may
not be desired at all because they provide an attacker with too
much information.</para>
<para>Some daemons are not security-conscious and have long, or
non-existent timeouts for connection attempts. This allows an
attacker to slowly send connections to a particular daemon, thus
saturating available resources. It may be a good idea to place
<option>ip-per-minute</option> and <option>max-child</option>
limitations on certain daemons.</para>
<para>By default, TCP wrapping is turned on. Consult the
&man.hosts.access.5; manual page for more information on placing
TCP restrictions on various <application>inetd</application>
invoked daemons.</para>
</sect2>
<sect2 id="inetd-misc">
<title>Miscellaneous</title>
<para><application>daytime</application>,
<application>time</application>,
<application>echo</application>,
<application>discard</application>,
<application>chargen</application>, and
<application>auth</application> are all internally provided
services of <application>inetd</application>.</para>
<para>The <application>auth</application> service provides identity
(ident, identd) network services, and is configurable to a certain
degree.</para>
<para>Consult the &man.inetd.8; manual page for more in-depth
information.</para>
</sect2>
</sect1>
<sect1 id="plip">
<title>Parallel Line IP (PLIP)</title>
<indexterm><primary>PLIP</primary></indexterm>
<indexterm><primary>Parallel Line IP</primary></indexterm>
<para>PLIP lets us run TCP/IP between parallel ports. It is
useful on machines without network cards, or to install on
laptops. In this section, we will discuss:</para>
<itemizedlist>
<listitem>
<para>Creating a parallel (laplink) cable.</para>
</listitem>
<listitem>
<para>Connecting two computers with PLIP.</para>
</listitem>
</itemizedlist>
<sect2 id="create-parallel-cable">
<title>Creating a Parallel Cable</title>
<para>You can purchase a parallel cable at most computer supply
stores. If you cannot do that, or you just want to know how
it is done, the following table shows how to make one out of a normal parallel
printer cable.</para>
<table>
<title>Wiring a parallel cable for networking</title>
<tgroup cols="5">
<thead>
<row>
<entry>A-name</entry>
<entry>A-End</entry>
<entry>B-End</entry>
<entry>Descr.</entry>
<entry>Post/Bit</entry>
</row>
</thead>
<tbody>
<row>
<entry><literallayout>DATA0
-ERROR</literallayout></entry>
<entry><literallayout>2
15</literallayout></entry>
<entry><literallayout>15
2</literallayout></entry>
<entry>Data</entry>
<entry><literallayout>0/0x01
1/0x08</literallayout></entry>
</row>
<row>
<entry><literallayout>DATA1
+SLCT</literallayout></entry>
<entry><literallayout>3
13</literallayout></entry>
<entry><literallayout>13
3</literallayout></entry>
<entry>Data</entry>
<entry><literallayout>0/0x02
1/0x10</literallayout></entry>
</row>
<row>
<entry><literallayout>DATA2
+PE</literallayout></entry>
<entry><literallayout>4
12</literallayout></entry>
<entry><literallayout>12
4</literallayout></entry>
<entry>Data</entry>
<entry><literallayout>0/0x04
1/0x20</literallayout></entry>
</row>
<row>
<entry><literallayout>DATA3
-ACK</literallayout></entry>
<entry><literallayout>5
10</literallayout></entry>
<entry><literallayout>10
5</literallayout></entry>
<entry>Strobe</entry>
<entry><literallayout>0/0x08
1/0x40</literallayout></entry>
</row>
<row>
<entry><literallayout>DATA4
BUSY</literallayout></entry>
<entry><literallayout>6
11</literallayout></entry>
<entry><literallayout>11
6</literallayout></entry>
<entry>Data</entry>
<entry><literallayout>0/0x10
1/0x80</literallayout></entry>
</row>
<row>
<entry>GND</entry>
<entry>18-25</entry>
<entry>18-25</entry>
<entry>GND</entry>
<entry>-</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="plip-setup">
<title>Setting up PLIP</title>
<para>Get a laplink cable.</para>
<para>Confirm that both computers have a kernel with &man.lpt.4; driver
support.</para>
<screen>&prompt.root; <userinput>dmesg | grep lp</userinput>
lpt0 at 0x378-0x37f irq 7 on isa
lpt0: Interrupt-driven
lp0: TCP/IP capable interface</screen>
<para>Plug in the laplink cable into the parallel interface on
both computers.</para>
<para>Configure the network interface parameters for <devicename>lp0</devicename> on both
sites as <username>root</username>. For example, if you want connect
the host <hostid>host1</hostid> with <hostid>host2</hostid>:</para>
<programlisting> host1 &lt;-----&gt; host2
IP Address 10.0.0.1 10.0.0.2</programlisting>
<para>Configure the interface on <hostid>host1</hostid> by doing:</para>
<screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.1 10.0.0.2</userinput></screen>
<para>Configure the interface on host2 by doing:</para>
<screen>&prompt.root; <userinput>ifconfig lp0 10.0.0.2 10.0.0.1</userinput></screen>
<para>You now should have a working connection. Please read the
manual pages &man.lp.4; and &man.lpt.4; for more details.</para>
<para>You should also add both hosts to
<filename>/etc/hosts</filename>:</para>
<programlisting>127.0.0.1 localhost.my.domain localhost
10.0.0.1 host1.my.domain host1
10.0.0.2 host2.my.domain</programlisting>
<para>To confirm the connection works, go to each host and ping
the other. For example, on <hostid>host1</hostid>:</para>
<screen>&prompt.root; <userinput>ifconfig lp0</userinput>
lp0: flags=8851&lt;UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST&gt; mtu 1500
inet 10.0.0.1 --&gt; 10.0.0.2 netmask 0xff000000
&prompt.root; <userinput>netstat -r</userinput>
Routing tables
Internet:
Destination Gateway Flags Refs Use Netif Expire
host2 host1 UH 4 127592 lp0
&prompt.root; <userinput>ping -c 4 host2</userinput>
PING host2 (10.0.0.2): 56 data bytes
64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms
64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms
64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms
64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms
--- host2 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen>
</sect2>
</sect1>
<sect1 id="ipv6">
<sect1info>
<authorgroup>
<author>
<firstname>Aaron</firstname>
<surname>Kaplan</surname>
<contrib>Originally Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Restructured and Added by </contrib>
</author>
</authorgroup>
</sect1info>
<title>IPv6</title>
<para>IPv6 (also know as IPng <quote>IP next generation</quote>) is
the new version of the well known IP protocol (also know as
<acronym>IPv4</acronym>). Like the other current *BSD systems,
FreeBSD includes the <acronym>KAME</acronym> IPv6 reference implementation.
So your FreeBSD system comes with all you will need to experiment with IPv6.
This section focuses on getting IPv6 configured and running.</para>
<para>In the early 1990s, people became aware of the rapidly
diminishing address space of IPv4. Given the expansion rate of the
Internet there were two major concerns:</para>
<itemizedlist>
<listitem>
<para>Running out of addresses. Today this is not so much of a concern
anymore since private address spaces
(<hostid role="ipaddr">10.0.0.0/8</hostid>,
<hostid role="ipaddr">192.168.0.0/24</hostid>,
etc.) and Network Address Translation (<acronym>NAT</acronym>) are
being employed.</para>
</listitem>
<listitem>
<para>Router table entries were getting too large. This is
still a concern today.</para>
</listitem>
</itemizedlist>
<para>IPv6 deals with these and many other issues:</para>
<itemizedlist>
<listitem>
<para>128 bit address space. In other words theoretically there are
340,282,366,920,938,463,463,374,607,431,768,211,456 addresses
available. This means there are approximately
6.67 * 10^27 IPv6 addresses per square meter on our planet.</para>
</listitem>
<listitem>
<para>Routers will only store network aggregation addresses in their routing
tables thus reducing the average space of a routing table to 8192
entries.</para>
</listitem>
</itemizedlist>
<para>There are also lots of other useful features of IPv6 such as:</para>
<itemizedlist>
<listitem>
<para>Address autoconfiguration (RFC2462)</para>
</listitem>
<listitem>
<para>Anycast addresses (<quote>one-out-of many</quote>)</para>
</listitem>
<listitem>
<para>Mandatory multicast addresses</para>
</listitem>
<listitem>
<para>IPsec (IP security)</para>
</listitem>
<listitem>
<para>Simplified header structure</para>
</listitem>
<listitem>
<para>Mobile <acronym>IP</acronym></para>
</listitem>
<listitem>
<para>IPv4-to-IPv6 transition mechanisms</para>
</listitem>
</itemizedlist>
<para>For more information see:</para>
<itemizedlist>
<listitem>
<para>IPv6 overview at <ulink url="http://www.sun.com">Sun.com</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.ipv6.org">IPv6.org</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.kame.net">KAME.net</ulink></para>
</listitem>
<listitem>
<para><ulink url="http://www.6bone.net">6bone.net</ulink></para>
</listitem>
</itemizedlist>
<sect2>
<title>Background on IPv6 Addresses</title>
<para>There are different types of IPv6 addresses: Unicast, Anycast and
Multicast.<para>
<para>Unicast addresses are the well known addresses. A packet sent
to a unicast address arrives exactly at the interface belonging to
the address.</para>
<para>Anycast addresses are syntactically indistinguishable from unicast
addresses but they address a group of interfaces. The packet destined for
an anycast address will arrive at the nearest (in router metric)
interface. Anycast addresses may only be used by routers.</para>
<para>Multicast addresses identify a group of interfaces. A packet destined
for a multicast address will arrive at all interfaces belonging to the
multicast group.</para>
<note><para>The IPv4 broadcast address (usually xxx.xxx.xxx.255) is expressed
by multicast addresses in IPv6.</para></note>
<para>Reserved IPv6 addresses:</para>
<screen>ipv6-address prefixlength(Bits) description Notes
:: 128 Bits unspecified cf. 0.0.0.0 in IPv4 address
::1 128 Bits loopback address cf. 127.0.0.1 in IPv4
::00:xx:xx:xx:xx 96 Bits embedded IPv4 The lower 32 bits are the
address IPv4 address. Also called
<quote>IPv4 compatible IPv6
address</quote>
::ff:xx:xx:xx:xx 96 Bits IPv4 mapped The lower 32 bits are the
IPv6 address IPv4 address. For hosts
which do not support IPv6
fe80:: - feb:: 10 Bits link-local cf. loopback address in
IPv4
fec0:: - fef:: 10 Bits site-local
ff:: 8 Bits multicast
001 (base 2) 3 Bits global unicast All global unicast
addresses are assigned from
this pool. The first 3 Bits
are <quote>001</quote>.</screen>
</sect2>
<sect2>
<title>Reading IPv6 Addresses</title>
<para>The canonical form is represented as: x:x:x:x:x:x:x:x, each
<quote>x</quote> being a 16 Bit hex value. For example
<hostid role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></para>
<para>Often an address will have long substrings of all zeros
therefore each such substring can be abbreviated by <quote>::</quote>.
For example <hostid role="ip6addr">fe80::1</hostid>
corresponds to the canonical form
<hostid role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid></para>
<para>A third form is to write the last 32 Bit part in the
well known (decimal) IPv4 style with dots <quote>.</quote>
as separators. For example
<hostid role="ip6addr">2002::10.0.0.1</hostid>
corresponds to the (hexadecimal) canonical representation
<hostid role="ip6addr">2002:0000:0000:0000:0000:0000:000a:0001</hostid>
which in turn is equivalent to
writing <hostid role="ip6addr">2002::a:1</hostid></para>
<para>By now the reader should be able to understand the following:</para>
<screen>&prompt.root; <userinput>ifconfig</userinput></screen>
<programlisting>rl0: flags=8943&lt;UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST&gt; mtu 1500
inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255
inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1
ether 00:00:21:03:08:e1
media: Ethernet autoselect (100baseTX )
status: active</programlisting>
<para><hostid role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid>
is an auto configured link-local address. It includes the
enscrambled Ethernet MAC as part of the auto configuration.</para>
<para>For further information on the structure of IPv6 addresses
see RFC2373.</para>
</sect2>
<sect2>
<title>Getting Connected</title>
<para>Currently there are four ways to connect to other IPv6 hosts and networks:</para>
<itemizedlist>
<listitem>
<para>Join the experimental 6bone</para>
</listitem>
<listitem>
<para>Getting an IPv6 network from your upstream provider. Talk to your
Internet provider for instructions.</para>
</listitem>
<listitem>
<para>Tunnel via 6-to-4</para>
</listitem>
<listitem>
<para>Use the freenet6 port if you are on a dial-up connection.</para>
</listitem>
</itemizedlist>
<para>Here we will talk on how to connect to the 6bone since it currently seems
to be the most popular way.</para>
<para>First take a look at the 6bone site and find a 6bone connection nearest to
you. Write to the responsible person and with a little bit of luck you
will be given instructions on how to set up your connection. Usually this
involves setting up a GRE (gif) tunnel.</para>
<para>Here is a typical example on setting up a &man.gif.4; tunnel:</para>
<screen>&prompt.root; <userinput>ifconfig gif0 create</userinput>
&prompt.root; <userinput>ifconfig gif0</userinput>
gif0: flags=8010&lt;POINTOPOINT,MULTICAST&gt; mtu 1280
&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>MY_IPv4_ADDR</replaceable> <replaceable>HIS_IPv4_ADDR</replaceable></userinput>
&prompt.root; <userinput>ifconfig gif0 inet6 alias <replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable></userinput></screen>
<para>Replace the capitalized words by the information you received from the
upstream 6bone node.</para>
<para>This establishes the tunnel. Check if the tunnel is working by &man.ping6.8;
'ing ff02::1%gif0. You should receive two ping replies.</para>
<note><para>In case you are intrigued by the address ff02:1%gif0, this is a
multicast address. %gif0 states that the multicast address at network
interface gif0 is to be used. Since we <command>ping</command> a multicast address the
other endpoint of the tunnel should reply as well).</para></note>
<para>By now setting up a route to your 6bone uplink should be rather
straightforward:</para>
<screen>&prompt.root; <userinput>route add -inet6 default -interface gif0</userinput>
&prompt.root; <userinput>ping6 -n <replaceable>MY_UPLINK</replaceable></userinput></screen>
<screen>&prompt.root; <userinput>traceroute6 www.jp.freebsd.org</userinput>
(3ffe:505:2008:1:2a0:24ff:fe57:e561) from 3ffe:8060:100::40:2, 30 hops max, 12 byte packets
1 atnet-meta6 14.147 ms 15.499 ms 24.319 ms
2 6bone-gw2-ATNET-NT.ipv6.tilab.com 103.408 ms 95.072 ms *
3 3ffe:1831:0:ffff::4 138.645 ms 134.437 ms 144.257 ms
4 3ffe:1810:0:6:290:27ff:fe79:7677 282.975 ms 278.666 ms 292.811 ms
5 3ffe:1800:0:ff00::4 400.131 ms 396.324 ms 394.769 ms
6 3ffe:1800:0:3:290:27ff:fe14:cdee 394.712 ms 397.19 ms 394.102 ms</screen>
<para>This output will differ from machine to machine. By now you should be
able to reach the IPv6 site <ulink url="http://www.kame.net">www.kame.net</ulink>
and see the dancing tortoise - that is if you have a IPv6 enabled browser such as
<filename role="package">mozilla</filename>.</para>
</sect2>
<sect2>
<title>DNS in the IPv6 World</title>
<para>There are two new types of DNS records for IPv6:</para>
<itemizedlist>
<listitem>
<para>AAAA records,</para>
</listitem>
<listitem>
<para>A6 records</para>
</listitem>
</itemizedlist>
<para>Using AAAA records is straightforward. Assign your hostname to the new
IPv6 address you just got by adding:</para>
<programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting>
<para>To your primary zone DNS file. In case you do not serve your own
<acronym>DNS</acronym> zones ask your <acronym>DNS</acronym> provider.
Current versions of <application>bind</application> (version 8.3 and 9)
support AAAA records.</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 -->
Reference in a new issue View git blame Copy permalink