path: root/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="network-servers">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>Murray</firstname>
	<surname>Stokely</surname>
	<contrib>Reorganized by </contrib>
      </author>
    </authorgroup>
    <!-- 23 July 2004 -->
  </chapterinfo>

  <title>Network Servers</title>

  <sect1 id="network-servers-synopsis">
    <title>Synopsis</title>

    <para>This chapter will cover some of the more frequently used
      network services on &unix; systems.  We will cover how to
      install, configure, test, and maintain many different types of
      network services.  Example configuration files are included
      throughout this chapter for you to benefit from.</para>

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

    <itemizedlist>

      <listitem>
	<para>How to manage the <application>inetd</application>
	  daemon.</para>
      </listitem>

      <listitem>
	<para>How to set up a network file system.</para>
      </listitem>

      <listitem>
	<para>How to set up a network information server for sharing
	  user accounts.</para>
      </listitem>

      <listitem>
	<para>How to set up automatic network settings using
	  DHCP.</para>
      </listitem>

      <listitem>
	<para>How to set up a domain name server.</para>
      </listitem>

      <listitem>
	<para>How to set up the <application>Apache</application>
	  HTTP Server.</para>
      </listitem>

      <listitem>
	<para>How to set up a File Transfer Protocol (FTP)
	  Server.</para>
      </listitem>

      <listitem>
	<para>How to set up a file and print server for &windows;
	  clients using <application>Samba</application>.</para>
      </listitem>

      <listitem>
	<para>How to synchronize the time and date, and set up a
	  time server, with the NTP protocol.</para>
      </listitem>

      <listitem>
	<para>How to configure the standard logging daemon,
	  <command>syslogd</command>, to accept logs from remote
	  hosts.</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>

      <listitem>
	<para>Know how to install additional third-party
	  software (<xref linkend="ports"/>).</para>
      </listitem>

    </itemizedlist>
  </sect1>

  <sect1 id="network-inetd">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <contrib>Updated by </contrib>
	  <othername>The &os; Documentation Project</othername>
	</author>
      </authorgroup>
    </sect1info>

    <title>The <application>inetd</application>
      <quote>Super-Server</quote></title>

    <sect2 id="network-inetd-overview">
      <title>Overview</title>

      <para>&man.inetd.8; is sometimes referred to as the
	<quote>Internet Super-Server</quote> because it manages
	connections for several services.  When a connection is
	received by <application>inetd</application>, it determines
	which program the connection is destined for, spawns the
	particular process and delegates the socket to it (the program
	is invoked with the service socket as its standard input,
	output and error descriptors).  Running
	<application>inetd</application> for servers that are not
	heavily used can reduce the overall system load, when 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="network-inetd-settings">
      <title>Settings</title>

      <para><application>inetd</application> is initialized through
	the &man.rc.8; system.  The
	<literal>inetd_enable</literal> option is set to
	<literal>NO</literal> by default, but may be turned on
	by <application>sysinstall</application> during installation,
	depending on the configuration chosen by the user.
	Placing:</para>

      <programlisting>inetd_enable="YES"</programlisting>

      <para>or</para>

      <programlisting>inetd_enable="NO"</programlisting>

      <para>into
	<filename>/etc/rc.conf</filename> will enable or disable
	<application>inetd</application> starting at boot time.
	The command:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/inetd rcvar</userinput></screen>

      <para>
	can be run to display the current effective setting.</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="network-inetd-cmdline">
      <title>Command-Line Options</title>

      <para>Like most server daemons, <application>inetd</application>
	has a number of options that it can be passed in order to
	modify its behaviour.  See the &man.inetd.8; manual page for
	the full list of options.</para>

      <para>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
	<literal>-wW -C 60</literal>, which turns on TCP wrapping for
	<application>inetd</application>'s services, and prevents any
	single IP address from requesting any service more than 60
	times in any given minute.</para>

      <para>Although we mention rate-limiting options below, novice
	users may be pleased to note that these parameters usually do
	not need to be modified.  These options may be useful should
	you find that you are receiving an excessive amount of
	connections.  A full list of options can be found in the
	&man.inetd.8; manual.</para>

      <variablelist>
	<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>-s maximum</term>

	  <listitem>
	    <para>Specify the maximum number of times a service can be
	      invoked from a single IP address at any one time; the
	      default is unlimited.  May be overridden on a
	      per-service basis with the
	      <option>max-child-per-ip</option> parameter.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="network-inetd-conf">
      <!-- XXX This section isn't very clear, and could do with some lovin' -->
      <title><filename>inetd.conf</filename></title>

      <para>Configuration of <application>inetd</application> is
	done via the file <filename>/etc/inetd.conf</filename>.</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 running the command:</para>

      <example id="network-inetd-reread">
	<title>Reloading the <application>inetd</application>
	  Configuration File</title>

	<screen>&prompt.root; <userinput>/etc/rc.d/inetd reload</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 each entry in
	<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[/max-child-per-ip]]]
user[:group][/login-class]
server-program
server-program-arguments</programlisting>

      <para>An example entry for the &man.ftpd.8; daemon
	using IPv4 might read:</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 <acronym>UDP</acronym> transport protocol.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>protocol</term>

	  <listitem>
	    <para>One of the following:</para>

	    <informaltable frame="none" pgwide="1">
	      <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[/max-child-per-ip]]]</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
	      <option>wait</option> 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>.  Specifying
	      <literal>/0</literal> allows an unlimited number of
	      children</para>

	    <para>In addition to <option>max-child</option>, two other
	      options which limit the maximum connections from a
	      single place to a particular daemon can be enabled.
	      <option>max-connections-per-ip-per-minute</option>
	      limits the number of connections from any particular IP
	      address per minutes, e.g., a value of ten would limit
	      any particular IP address connecting to a particular
	      service to ten attempts per minute.
	      <option>max-child-per-ip</option> limits the number of
	      children that can be started on behalf on any single IP
	      address at any moment.  These options are useful to
	      prevent intentional or unintentional excessive resource
	      consumption and Denial of Service (DoS) attacks to a
	      machine.</para>

	    <para>In this field, either of <option>wait</option> or
	      <option>nowait</option> is mandatory.
	      <option>max-child</option>,
	      <option>max-connections-per-ip-per-minute</option> and
	      <option>max-child-per-ip</option> are
	      optional.</para>

	    <para>A stream-type multi-threaded daemon without any
	      <option>max-child</option>,
	      <option>max-connections-per-ip-per-minute</option> or
	      <option>max-child-per-ip</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>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 utilized by the default
	      settings of the &man.fingerd.8; daemon,
	      as seen here:</para>

	    <programlisting>finger stream  tcp     nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting>

	    <para>Finally, an example of this field with a maximum of
	      100 children in total, with a maximum of 5 for any one
	      IP address would read:
	      <literal>nowait/100/0/5</literal>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>user</term>

	  <listitem>
	    <para>This 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 <literal>argv[0]</literal>,
	      passed to the daemon on invocation.  If
	      <command>mydaemon -d</command> 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="network-inetd-security">
      <title>Security</title>

      <para>Depending on the choices made at install time, many
	of <application>inetd</application>'s services may be enabled
	by default.  If there is no apparent need for a particular
	daemon, consider disabling it.  Place a <quote>#</quote> in
	front of the daemon in question in
	<filename>/etc/inetd.conf</filename>, and then <link
	  linkend="network-inetd-reread">reload the
	inetd configuration</link>.  Some daemons, such as
	<application>fingerd</application>, may not be desired at all
	because they provide
	information that may be useful to an attacker.</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>max-connections-per-ip-per-minute</option>,
	<option>max-child</option> or
	<option>max-child-per-ip</option> limitations on certain
	daemons if you find that you have too many connections.</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="network-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
	network services, and is
	configurable to a certain degree, whilst the others are simply
	on or off.</para>

      <para>Consult the &man.inetd.8; manual page for more in-depth
	information.</para>
    </sect2>
  </sect1>

  <sect1 id="network-nfs">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Reorganized and enhanced by </contrib>
	</author>
      </authorgroup>
      <authorgroup>
	<author>
	  <firstname>Bill</firstname>
	  <surname>Swingle</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Network File System (NFS)</title>

    <indexterm><primary>NFS</primary></indexterm>
    <para>Among the many different file systems that FreeBSD supports
      is the Network File System, also known as <acronym role="Network
      File System">NFS</acronym>.  <acronym role="Network File
      System">NFS</acronym> allows a system to share directories and
      files with others over a network.  By using <acronym
      role="Network File System">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 set up 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
	  &iomegazip; 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>file server</primary>
	<secondary>UNIX clients</secondary>
      </indexterm>

      <indexterm>
	<primary><application>rpcbind</application></primary>
      </indexterm>
      <indexterm>
	<primary><application>mountd</application></primary>
      </indexterm>
      <indexterm>
	<primary><application>nfsd</application></primary>
      </indexterm>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="3*"/>

	  <thead>
	    <row>
	      <entry>Daemon</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry><application>nfsd</application></entry>
	      <entry>The <acronym>NFS</acronym> daemon which services
		requests from the <acronym>NFS</acronym>
		clients.</entry>
	    </row>
	    <row>
	      <entry><application>mountd</application></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><application>rpcbind</application></entry>
	      <entry> This daemon allows
		<acronym>NFS</acronym> clients to discover which port
		the <acronym>NFS</acronym> server is using.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>The client can also run a daemon, known as
	<application>nfsiod</application>.  The
	<application>nfsiod</application> daemon services the requests
	from the <acronym>NFS</acronym> server.  This is optional, and
	improves performance, but is not required for normal and
	correct operation.  See the &man.nfsiod.8; manual page for
	more information.</para>
    </sect2>

    <sect2 id="network-configuring-nfs">
      <title>Configuring <acronym>NFS</acronym></title>
      <indexterm>
	<primary>NFS</primary>
	<secondary>configuration</secondary>
      </indexterm>

      <para><acronym>NFS</acronym> configuration is a relatively
	straightforward process.  The processes that need to be
	running can all start at boot time with a few modifications to
	your <filename>/etc/rc.conf</filename> file.</para>

      <para>On the <acronym>NFS</acronym> server, make sure that the
	following options are configured in the
	<filename>/etc/rc.conf</filename> file:</para>

      <programlisting>rpcbind_enable="YES"
nfs_server_enable="YES"
mountd_flags="-r"</programlisting>

      <para><application>mountd</application> 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
	file systems <acronym>NFS</acronym> should export (sometimes
	referred to as <quote>share</quote>).  Each line in
	<filename>/etc/exports</filename> specifies a file system to
	be exported and which machines have access to that file
	system.  Along with what machines have access to that file
	system, access options may also be specified.  There are many
	such options that can be used in this file but only a few will
	be mentioned here.  You can easily discover other options by
	reading over the &man.exports.5; manual page.</para>

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

      <indexterm>
	<primary>NFS</primary>
	<secondary>export examples</secondary>
      </indexterm>

      <para>The following examples give an idea of how to export
	file systems, 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 file system
	read-only.  With this flag, the remote system will not be able
	to write any changes to the exported file system.</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 file system.
	The <option>-maproot=root</option> flag allows the
	<username>root</username> user on the remote system to write
	data on the exported file system 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, he will not be able to modify files on
	the exported file system.</para>

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

      <para>In order for a client to access an exported file system,
	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 file system to one host.  A
	remote host can only be specified once per file system, and
	may only have one default entry.  For example, assume that
	<filename>/usr</filename> is a single file system.  The
	following <filename>/etc/exports</filename> would be
	invalid:</para>

      <programlisting># Invalid when /usr is one file system
/usr/src   client
/usr/ports client</programlisting>

      <para>One file system, <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 file system 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
	file systems, 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 file systems:</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>The <application>mountd</application> daemon must be
	forced to recheck the <filename>/etc/exports</filename> file
	whenever it has been modified, so the changes can take effect.
	This can be accomplished either by sending a HUP signal to the
	running daemon:</para>

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

      <para>or by invoking the <command>mountd</command> &man.rc.8;
	script with the appropriate parameter:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/mountd onereload</userinput></screen>

      <para>Please refer to <xref linkend="configtuning-rcd"/> for more
	information about using rc scripts.</para>

      <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>rpcbind</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
	<hostid>server</hostid> and the client's name will be
	<hostid>client</hostid>.  If you only want to temporarily
	mount a remote file system or would rather test the
	configuration, just execute a command like this as
	<username>root</username> on the client:</para>

      <indexterm>
	<primary>NFS</primary>
	<secondary>mounting</secondary>
      </indexterm>
      <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>

      <para>This will mount the <filename>/home</filename> directory
	on the server at <filename>/mnt</filename> on the client.  If
	everything is set up correctly you should be able to enter
	<filename>/mnt</filename> on the client and see all the files
	that are on the server.</para>

      <para>If you want to automatically mount a remote file system
	each time the computer boots, add the file system 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>Locking</title>

      <para>Some applications (e.g., <application>mutt</application>)
	require file locking to operate correctly.  In the case of
	<acronym>NFS</acronym>, <application>rpc.lockd</application>
	can be used for file locking.  To enable it, add the following
	to the <filename>/etc/rc.conf</filename> file on both client
	and server (it is assumed that the <acronym>NFS</acronym>
	client and server are configured already):</para>

      <programlisting>rpc_lockd_enable="YES"
rpc_statd_enable="YES"</programlisting>

      <para>Start the application by using:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/lockd start</userinput>
&prompt.root; <userinput>/etc/rc.d/statd start</userinput></screen>

      <para>If real locking between the <acronym>NFS</acronym> clients
	and <acronym>NFS</acronym> server is not required, it is
	possible to let the <acronym>NFS</acronym> client do locking
	locally by passing <option>-L</option> to &man.mount.nfs.8;.
	Refer to the &man.mount.nfs.8; manual page for further
	details.</para>
    </sect2>

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

      <para><acronym>NFS</acronym> has many practical uses.  Some of
	the more common ones are listed below:</para>

      <indexterm>
	<primary>NFS</primary>
	<secondary>uses</secondary>
      </indexterm>
      <itemizedlist>
	<listitem>
	  <para>Set several machines to share a CDROM or other media
	    among them.  This is cheaper and often a more convenient
	    method to install software on multiple machines.</para>
	</listitem>

	<listitem>
	  <para>On large networks, it might be more convenient to
	    configure a central <acronym>NFS</acronym> server in which
	    to store all the user home directories.  These home
	    directories can then be exported to the network so that
	    users would always have the same home directory,
	    regardless of which workstation they log in to.</para>
	</listitem>

	<listitem>
	  <para>Several machines could have a common
	    <filename>/usr/ports/distfiles</filename> directory.  That
	    way, when you need to install a port on several machines,
	    you can quickly access the source without downloading it
	    on each machine.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="network-amd">
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>Wylie</firstname>
	    <surname>Stilwell</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
	<authorgroup>
	  <author>
	    <firstname>Chern</firstname>
	    <surname>Lee</surname>
	    <contrib>Rewritten by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <title>Automatic Mounts with
	<application>amd</application></title>

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

      <para>&man.amd.8; (the automatic mounter daemon)
	automatically mounts a
	remote file system whenever a file or directory within that
	file system 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 file
	system from an IP address, while <filename>/host</filename>
	is used to mount an export from a remote hostname.</para>

      <para>An access to a file within
	<filename>/host/foobar/usr</filename> would tell
	<application>amd</application> to attempt to mount the
	<filename>/usr</filename> export on the host
	<hostid>foobar</hostid>.</para>

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

	<para>You can view the available mounts of a remote host with
	  the <command>showmount</command> command.  For example, to
	  view the mounts of a host named <hostid>foobar</hostid>, you
	  can use:</para>

	<screen>&prompt.user; <userinput>showmount -e foobar</userinput>
Exports list on foobar:
/usr                               10.10.10.0
/a                                 10.10.10.0
&prompt.user; <userinput>cd /host/foobar/usr</userinput></screen>
      </example>

      <para>As seen in the example, the <command>showmount</command>
	shows <filename>/usr</filename> as an export.  When changing
	directories to <filename>/host/foobar/usr</filename>,
	<application>amd</application> attempts to resolve the
	hostname <hostid>foobar</hostid> and automatically mount the
	desired export.</para>

      <para><application>amd</application> can be started by the
	startup scripts by placing the following lines in
	<filename>/etc/rc.conf</filename>:</para>

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

      <para>Additionally, custom flags can be passed to
	<application>amd</application> from the
	<varname>amd_flags</varname> option.  By default,
	<varname>amd_flags</varname> is set to:</para>

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

      <para>The <filename>/etc/amd.map</filename> file defines the
	default options that exports are mounted with.  The
	<filename>/etc/amd.conf</filename> file defines some of the
	more advanced features of
	<application>amd</application>.</para>

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

    <sect2 id="network-nfs-integration">
      <sect2info>
	<authorgroup>
	  <author>
	    <firstname>John</firstname>
	    <surname>Lind</surname>
	    <contrib>Contributed by </contrib>
	  </author>
	</authorgroup>
      </sect2info>
      <title>Problems Integrating with Other Systems</title>

      <para>Certain Ethernet adapters for ISA PC systems have
	limitations which can lead to serious network problems,
	particularly with NFS.  This difficulty is not specific to
	FreeBSD, but FreeBSD systems are affected by it.</para>

      <para>The problem nearly always occurs when (FreeBSD) PC systems
	are networked with high-performance workstations, such as
	those made by Silicon Graphics, Inc., and Sun Microsystems,
	Inc.  The NFS mount will work fine, and some operations may
	succeed, but suddenly the server will seem to become
	unresponsive to the client, even though requests to and from
	other systems continue to be processed.  This happens to the
	client system, whether the client is the FreeBSD system or the
	workstation.  On many systems, there is no way to shut down
	the client gracefully once this problem has manifested itself.
	The only solution is often to reset the client, because the
	NFS situation cannot be resolved.</para>

      <para>Though the <quote>correct</quote> solution is to get a
	higher performance and capacity Ethernet adapter for the
	FreeBSD system, there is a simple workaround that will allow
	satisfactory operation.  If the FreeBSD system is the
	<emphasis>server</emphasis>, include the option
	<option>-w=1024</option> on the mount from the client.  If the
	FreeBSD system is the <emphasis>client</emphasis>, then mount
	the NFS file system with the option <option>-r=1024</option>.
	These options may be specified using the fourth field of the
	<filename>fstab</filename> entry on the client for automatic
	mounts, or by using the <option>-o</option> parameter of the
	&man.mount.8; 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 <acronym>UDP</acronym> 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
	file system (see &man.exports.5;), and
	<filename>/project</filename> will be the mount point on the
	client for the exported file system.  In all cases, note that
	additional options, such as <option>hard</option> or
	<option>soft</option> and <option>bg</option> may be desirable
	in your application.</para>

      <para>Examples for the FreeBSD system (<hostid>freebox</hostid>)
	as the client in <filename>/etc/fstab</filename> on
	<hostid>freebox</hostid>:</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="network-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>Network Information System (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><acronym role="Network Information System">NIS</acronym>,
	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; like systems
	(&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD,
	etc) support <acronym
	  role="Network Information System">NIS</acronym>.</para>

      <indexterm>
	<primary>yellow pages</primary>
	<see>NIS</see>
      </indexterm>

      <para><acronym role="Network Information System">NIS</acronym>
	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 the &windowsnt; 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>rpcbind</application></primary>
      </indexterm>
      <indexterm>
	<primary><application>portmap</application></primary>
      </indexterm>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	<colspec colwidth="1*"/>
	<colspec colwidth="3*"/>

	  <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 &windowsnt; domain name, the NIS
		domainname does not have anything to do with
		<acronym>DNS</acronym>.</entry>
	    </row>
	    <row>
	      <entry><application>rpcbind</application></entry>

	      <entry>Must be running in order to enable
		<acronym>RPC</acronym> (Remote Procedure Call, a
		network protocol used by NIS).  If
		<application>rpcbind</application> is not running, it
		will be impossible to run an NIS server, or to act as
		an NIS client.</entry>
	    </row>
	    <row>
	      <entry><application>ypbind</application></entry>

	      <entry><quote>Binds</quote> an NIS client to its NIS
		server.  It will take the NIS domainname from the
		system, and using <acronym>RPC</acronym>, connect to
		the server.  <application>ypbind</application> is the
		core of client-server communication in an NIS
		environment; if <application>ypbind</application> dies
		on a client machine, it will not be able to access the
		NIS server.</entry>
	    </row>
	    <row>
	      <entry><application>ypserv</application></entry>
	      <entry>Should only be running on NIS servers; this 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
		<application>ypbind</application> process on the
		client.</entry>
	    </row>
	    <row>
	      <entry><application>rpc.yppasswdd</application></entry>
	      <entry>Another process that should only be running on
		NIS master servers; this 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 &windowsnt; 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>

	  <listitem>
	    <indexterm>
	      <primary>NIS</primary>
	      <secondary>slave server</secondary>
	    </indexterm>

	    <para><emphasis>NIS slave servers</emphasis>.  Similar to
	      the &windowsnt; 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>

	  <listitem>
	    <indexterm>
	      <primary>NIS</primary>
	      <secondary>client</secondary>
	    </indexterm>

	    <para><emphasis>NIS clients</emphasis>.  NIS clients, like
	      most &windowsnt; workstations, authenticate against the
	      NIS server (or the &windowsnt; domain controller in the
	      &windowsnt; workstations 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>

      <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 frame="none" pgwide="1">
	  <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
	    <literal>test-domain</literal>.</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
		<literal>test-domain</literal>
		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="network-nis-server-is-client">section about
	      NIS servers that are also NIS clients</link>, below, for
	      details.</para>
	  </note>

	  <para>After setting up the above entries, 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>.  As a last step, before
	    initializing the NIS maps, start the
	    <application>ypserv</application> daemon manually:</para>

	  <screen>&prompt.root; <userinput>/etc/rc.d/ypserv start</userinput></screen>
	</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 <literal>test-domain</literal> 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>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.  These entries are not
	    mandatory because the master server automatically attempts
	    to push any map changes to its slaves.  However, due to
	    the importance of correct password information on other
	    clients depending on the slave server, it is recommended
	    to specifically force the password map updates frequently.
	    This is especially 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 a 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="network-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 <username>root</username>, 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>To start the NIS client immediately, execute the
	    following commands as the superuser:</para>

	  <screen>&prompt.root; <userinput>/etc/netstart</userinput>
&prompt.root; <userinput>/etc/rc.d/ypbind start</userinput></screen>

	  <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 <quote>securenets</quote> 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>TCP Wrapper</application>
	package.  This allows the administrator to use the
	<application>TCP Wrapper</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>TCP Wrappers</primary></indexterm>
	<para>The use of the <application>TCP Wrapper</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
	<literal>-<replaceable>username</replaceable></literal> 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
	<username>bill</username> 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 &amp;:/:/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="network-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 frame="none" pgwide="1">
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>User Name(s)</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry><username>alpha</username>,
		<username>beta</username></entry>
	      <entry>Normal employees of the IT department</entry>
	    </row>

	    <row>
	      <entry><username>charlie</username>,
		<username>delta</username></entry>
	      <entry>The new apprentices of the IT department</entry>
	    </row>

	    <row>
	      <entry><username>echo</username>,
		<username>foxtrott</username>,
		<username>golf</username>, ...</entry>
	      <entry>Ordinary employees</entry>
	    </row>

	    <row>
	      <entry><username>able</username>,
		<username>baker</username>, ...</entry>
	      <entry>The current interns</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <informaltable frame="none" pgwide="1">
	<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><hostid>war</hostid>,
		<hostid>death</hostid>, <hostid>famine</hostid>,
		<hostid>pollution</hostid></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><hostid>pride</hostid>, <hostid>greed</hostid>,
		<hostid>envy</hostid>, <hostid>wrath</hostid>,
		<hostid>lust</hostid>, <hostid>sloth</hostid></entry>
	      <entry>Less important servers.  All members of the IT
		department are allowed to login onto these
		machines.</entry>
	    </row>
	    <row>
	      <entry><hostid>one</hostid>, <hostid>two</hostid>,
		<hostid>three</hostid>, <hostid>four</hostid>,
		...</entry>
	      <entry>Ordinary workstations.  Only the
		<emphasis>real</emphasis> employees are allowed to use
		these machines.</entry>
	    </row>

	    <row>
	      <entry><hostid>trashcan</hostid></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
	<literal>-<replaceable>user</replaceable></literal> 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
	<hostid>war</hostid>, 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
	<literal>IT_EMP</literal> is imported into
	<hostid>war</hostid>'s password database and only
	these users are allowed to login.</para>

      <para>Unfortunately, this limitation also applies to the
	<literal>~</literal> 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
	<literal>passwd</literal> 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
	  <filename>/sbin/nologin</filename> 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 <literal>IT_INTERN</literal>, add the new
	IT interns to this netgroup and start to change the
	configuration 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 <literal>BIGSRV</literal> to define
	the login restrictions for the important servers, another
	netgroup called <literal>SMALLSRV</literal> for the less
	important servers and a third netgroup called
	<literal>USERBOX</literal> 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 <quote>ALL-CAPS</quote> 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 <username>jsmith</username> 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.  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
	<application>ypserv</application> 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="network-nis-server-is-client">
      <title>NIS Servers That Are Also NIS Clients</title>

      <para> Care must be taken when running
	<application>ypserv</application> 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>Password Formats</title>
      <indexterm>
	<primary>NIS</primary>
	<secondary>password formats</secondary>
      </indexterm>
      <para>One of the most common issues that people run into when
	trying to implement NIS is password format compatibility.  If
	your NIS server is using DES encrypted passwords, it will only
	support clients that are also using DES.  For example, if you
	have &solaris; NIS clients in your network, then you will
	almost certainly need to use DES encrypted passwords.</para>

      <para>To check which format your servers and clients are using,
	look at <filename>/etc/login.conf</filename>.  If the host is
	configured to use DES encrypted passwords, then the
	<literal>default</literal> class will contain an entry like
	this:</para>

      <programlisting>default:\
	:passwd_format=des:\
	:copyright=/etc/COPYRIGHT:\
	[Further entries elided]</programlisting>

      <para>Other possible values for the
	<literal>passwd_format</literal> capability include
	<literal>blf</literal> and <literal>md5</literal> (for
	Blowfish and MD5 encrypted passwords, respectively).</para>

      <para>If you have made changes to
	<filename>/etc/login.conf</filename>, you will also need to
	rebuild the login capability database, which is achieved by
	running the following command as
	<username>root</username>:</para>

      <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>

      <note><para>The format of passwords already in
	<filename>/etc/master.passwd</filename> will not be updated
	until a user changes his password for the first time
	<emphasis>after</emphasis> the login capability database is
	rebuilt.</para></note>

      <para>Next, in order to ensure that passwords are encrypted with
	the format that you have chosen, you should also check that
	the <literal>crypt_default</literal> in
	<filename>/etc/auth.conf</filename> gives precedence to your
	chosen password format.  To do this, place the format that you
	have chosen first in the list.  For example, when using DES
	encrypted passwords, the entry would be:</para>

      <programlisting>crypt_default	=	des blf md5</programlisting>

      <para>Having followed the above steps on each of the &os; based
	NIS servers and clients, you can be sure that they all agree
	on which password format is used within your network.  If you
	have trouble authenticating on an NIS client, this is a pretty
	good place to start looking for possible problems.  Remember:
	if you want to deploy an NIS server for a heterogeneous
	network, you will probably have to use DES on all systems
	because it is the lowest common standard.</para>
    </sect2>
  </sect1>

  <sect1 id="network-dhcp">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Greg</firstname>
	  <surname>Sutter</surname>
	  <contrib>Written by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Automatic Network Configuration (DHCP)</title>

    <sect2>
      <title>What Is DHCP?</title>
      <indexterm>
	<primary>Dynamic Host Configuration Protocol</primary>
	<see>DHCP</see>
      </indexterm>
      <indexterm>
	<primary>Internet Systems 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 OpenBSD <command>dhclient</command>
	taken from OpenBSD&nbsp;3.7.  All information here regarding
	<command>dhclient</command> is for use with either of the ISC
	or OpenBSD DHCP clients.  The DHCP server is the one included
	in the ISC distribution.</para>
    </sect2>

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

      <para>This section describes both the client-side components of
	the ISC and OpenBSD DHCP client 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-dhcp42-server</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>&os; fully integrates the OpenBSD 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.</para> <indexterm>
	  <primary><application>sysinstall</application></primary>
	</indexterm>

	<para>DHCP is supported by
	  <application>sysinstall</application>.  When configuring a
	  network interface within
	  <application>sysinstall</application>, the second question
	  asked is: <quote>Do you want to try DHCP configuration of
	  the 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>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>By default, DHCP configuration on &os; runs in the
	      background, or <firstterm>asynchronously</firstterm>.
	      Other startup scripts continue to run while DHCP
	      completes, speeding up system startup.</para>

	    <para>Background DHCP works well when the DHCP server
	      responds quickly to requests and the DHCP configuration
	      process goes quickly.  However, DHCP may take a long
	      time to complete on some systems.  If network services
	      attempt to run before DHCP has completed, they will
	      fail.  Using DHCP in <firstterm>synchronous</firstterm>
	      mode prevents the problem, pausing startup until DHCP
	      configuration has completed.</para>

	    <para>To connect to a DHCP server in the background while
	      other startup continues (asynchronous mode), use the
	      <quote><literal>DHCP</literal></quote> value in
	      <filename>/etc/rc.conf</filename>:</para>

	    <programlisting>ifconfig_<replaceable>fxp0</replaceable>="DHCP"</programlisting>

	    <para>To pause startup while DHCP completes, use
	      synchronous mode with the
	      <quote><literal>SYNCDHCP</literal></quote> value:</para>

	    <programlisting>ifconfig_<replaceable>fxp0</replaceable>="SYNCDHCP"</programlisting>

	    <note>
	      <para>Replace the <replaceable>fxp0</replaceable> shown
		in these examples with the name of the interface to be
		dynamically configured, as described in
		<xref linkend="config-network-setup"/>.</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 (editing as necessary):</para>

	    <programlisting>dhclient_program="/sbin/dhclient"
dhclient_flags=""</programlisting>
	  </listitem>
	</itemizedlist>

	<indexterm>
	  <primary>DHCP</primary>
	  <secondary>server</secondary>
	</indexterm>
	<para>The DHCP server, <application>dhcpd</application>, is
	  included as part of the <filename
	    role="package">net/isc-dhcp42-server</filename> port in
	  the ports collection.  This port contains the ISC DHCP
	  server 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.<replaceable>interface</replaceable></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/"></ulink>.</para>
    </sect2>

    <sect2 id="network-dhcp-server">
      <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 Systems Consortium) implementation of the DHCP
	  server.</para>

	<para>The server is not provided as part of FreeBSD, and so
	  you will need to install the <filename
	    role="package">net/isc-dhcp42-server</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>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-dhcp42-server</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</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 recognize 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 using a hostname is
	      correct 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 should enable the DHCP server in
	  <filename>/etc/rc.conf</filename>, i.e., by adding:</para>

	<programlisting>dhcpd_enable="YES"
dhcpd_ifaces="dc0"</programlisting>

	<para>Replace the <literal>dc0</literal> interface name with
	  the interface (or interfaces, separated by whitespace)
	  that your DHCP server should listen on for DHCP client
	  requests.</para>

	<para>Then, you can proceed to start the server by issuing
	  the following command:</para>

	<screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd 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
	      &man.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 &man.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 &man.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.  If you require this functionality,
	      then install the <filename
		role="package">net/isc-dhcp42-relay</filename> port.
	      The &man.dhcrelay.8; manual page provided with the
	      port contains more detail.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="network-dns">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Chern</firstname>
	  <surname>Lee</surname>
	  <contrib>Contributed by </contrib>
	</author>

	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	</author>

	<author>
	  <firstname>Daniel</firstname>
	  <surname>Gerzo</surname>
	</author>
      </authorgroup>
    </sect1info>
    <title>Domain Name System (<acronym>DNS</acronym>)</title>

    <sect2>
      <title>Overview</title>
      <indexterm><primary>BIND</primary></indexterm>

      <para>&os; utilizes, by default, a version of BIND (Berkeley
	Internet Name Domain), which is the most common implementation
	of the <acronym>DNS</acronym> protocol.
	<acronym>DNS</acronym> is the protocol through which names are
	mapped to <acronym>IP</acronym> addresses, and vice versa.
	For example, a query for <hostid
	  role="fqdn">www.FreeBSD.org</hostid> will receive a reply
	with the <acronym>IP</acronym> address of The &os; Project's
	web server, whereas, a query for <hostid
	  role="fqdn">ftp.FreeBSD.org</hostid> will return the
	<acronym>IP</acronym> address of the corresponding
	<acronym>FTP</acronym> machine.  Likewise, the opposite can
	happen.  A query for an <acronym>IP</acronym> address can
	resolve its hostname.  It is not necessary to run a name
	server to perform <acronym>DNS</acronym> lookups on a
	system.</para>

      <para>&os; currently comes with <acronym>BIND</acronym>9
	<acronym>DNS</acronym> server software by default.  Our
	installation provides enhanced security features, a new file
	system layout and automated &man.chroot.8;
	configuration.</para>

      <indexterm><primary>DNS</primary></indexterm>
      <para><acronym>DNS</acronym> is coordinated across the Internet
	through a somewhat complex system of authoritative root, Top
	Level Domain (<acronym>TLD</acronym>), and other smaller-scale
	name servers which host and cache individual domain
	information.</para>

      <para>Currently, BIND is maintained by the
	Internet Systems Consortium
	<ulink url="https://www.isc.org/"></ulink>.</para>
    </sect2>

    <sect2>
      <title>Terminology</title>

      <para>To understand this document, some terms related to
	<acronym>DNS</acronym> must be understood.</para>

      <indexterm><primary>resolver</primary></indexterm>
      <indexterm><primary>reverse DNS</primary></indexterm>
      <indexterm><primary>root zone</primary></indexterm>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	  <colspec colwidth="1*"/>
	  <colspec colwidth="3*"/>

	  <thead>
	    <row>
	      <entry>Term</entry>
	      <entry>Definition</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>Forward <acronym>DNS</acronym></entry>
	      <entry>Mapping of hostnames to IP addresses.</entry>
	    </row>

	    <row>
	      <entry>Origin</entry>
	      <entry>Refers to the domain covered in a particular zone
		file.</entry>
	    </row>

	    <row>
	      <entry><application>named</application>, BIND</entry>
	      <entry>Common names for the BIND name server package
		within &os;.</entry>
	    </row>

	    <row>
	      <entry>Resolver</entry>
	      <entry>A system process through which a machine queries
		a name server for zone information.</entry>
	    </row>

	    <row>
	      <entry>Reverse <acronym>DNS</acronym></entry>
	      <entry>Mapping of <acronym>IP</acronym> addresses to
		hostnames.</entry>
	    </row>

	    <row>
	      <entry>Root zone</entry>

	      <entry>The beginning of the Internet zone hierarchy.
		All zones fall under the root zone, similar to how
		all files in a file system fall under the root
		directory.</entry>
	    </row>

	    <row>
	      <entry>Zone</entry>
	      <entry>An individual domain, subdomain, or portion of
		the <acronym>DNS</acronym> administered by the same
		authority.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <indexterm>
	<primary>zones</primary>
	<secondary>examples</secondary>
      </indexterm>

      <para>Examples of zones:</para>

      <itemizedlist>
	<listitem>
	  <para><hostid>.</hostid> is how the root zone is usually
	    referred to in documentation.</para>
	</listitem>

	<listitem>
	  <para><hostid>org.</hostid> is a Top Level Domain
	    (<acronym>TLD</acronym>) under the root zone.</para>
	</listitem>

	<listitem>
	  <para><hostid role="domainname">example.org.</hostid> is a
	    zone under the <hostid>org.</hostid>
	    <acronym>TLD</acronym>.</para>
	</listitem>

	<listitem>
	  <para><hostid>1.168.192.in-addr.arpa</hostid> is a zone
	    referencing all <acronym>IP</acronym> addresses which fall
	    under the <hostid role="ipaddr">192.168.1.*</hostid>
	    <acronym>IP</acronym> address space.</para>
	</listitem>
      </itemizedlist>

      <para>As one can see, the more specific part of a hostname
	appears to its left.  For example, <hostid
	  role="domainname">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 file system: the
	<filename class="directory">/dev</filename> directory falls
	within the root, and so on.</para>
    </sect2>

    <sect2>
      <title>Reasons to Run a Name Server</title>

      <para>Name servers generally come in two forms: authoritative
	name servers, and caching (also known as resolving)
	name servers.</para>

      <para>An authoritative name server is needed when:</para>

      <itemizedlist>
	<listitem>
	  <para>One wants to serve <acronym>DNS</acronym> information
	    to the world, replying authoritatively to queries.</para>
	</listitem>

	<listitem>
	  <para>A domain, such as <hostid
	      role="domainname">example.org</hostid>, is registered
	    and <acronym>IP</acronym> addresses need to be assigned
	    to hostnames under it.</para>
	</listitem>

	<listitem>
	  <para>An <acronym>IP</acronym> address block requires
	    reverse <acronym>DNS</acronym> entries
	    (<acronym>IP</acronym> to hostname).</para>
	</listitem>

	<listitem>
	  <para>A backup or second name server, called a slave, will
	    reply to queries.</para>
	</listitem>
      </itemizedlist>

      <para>A caching name server is needed when:</para>

      <itemizedlist>
	<listitem>
	  <para>A local <acronym>DNS</acronym> server may cache and
	    respond more quickly than querying an outside name
	    server.</para>
	</listitem>
      </itemizedlist>

      <para>When one queries for <hostid
	  role="fqdn">www.FreeBSD.org</hostid>, the resolver usually
	queries the uplink <acronym>ISP</acronym>'s name server, and
	retrieves the reply.  With a local, caching
	<acronym>DNS</acronym> server, the query only has to be made
	once to the outside world by the caching
	<acronym>DNS</acronym> server.  Additional queries will not
	have to go outside the local network, since the information is
	cached
	locally.</para>
    </sect2>

    <sect2>
      <title>How It Works</title>
      <para>In &os;, the BIND daemon is called
	<application>named</application>.</para>

      <informaltable frame="none" pgwide="1">
	<tgroup cols="2">
	  <thead>
	    <row>
	      <entry>File</entry>
	      <entry>Description</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>&man.named.8;</entry>
	      <entry>The BIND daemon.</entry>
	    </row>

	    <row>
	      <entry>&man.rndc.8;</entry>
	      <entry>Name server control utility.</entry>
	    </row>

	    <row>
	      <entry><filename
		  class="directory">/etc/namedb</filename></entry>
	      <entry>Directory where BIND zone information
		resides.</entry>
	    </row>

	    <row>
	      <entry><filename>/etc/namedb/named.conf</filename></entry>
	      <entry>Configuration file of the daemon.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <para>Depending on how a given zone is configured on the server,
	the files related to that zone can be found in the <filename
	  class="directory">master</filename>, <filename
	  class="directory">slave</filename>, or <filename
	  class="directory">dynamic</filename> subdirectories of the
	<filename class="directory">/etc/namedb</filename> directory.
	These files contain the <acronym>DNS</acronym> information
	that will be given out by the name server in response to
	queries.</para>
    </sect2>

    <sect2>
      <title>Starting BIND</title>

      <indexterm>
	<primary>BIND</primary>
	<secondary>starting</secondary>
      </indexterm>

      <para>Since BIND is installed by default, configuring it is
	relatively simple.</para>

      <para>The default <application>named</application> configuration
	is that of a basic resolving name server, running in a
	&man.chroot.8; environment, and restricted to listening on
	the local IPv4 loopback address (127.0.0.1).
	To start the server one time with
	this configuration, use the following command:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/named onestart</userinput></screen>

      <para>To ensure the <application>named</application> daemon is
	started at boot each time, put the following line into the
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>named_enable="YES"</programlisting>

      <para>There are obviously many configuration options for
	<filename>/etc/namedb/named.conf</filename> that are beyond
	the scope of this document.  However, if you are interested in
	the startup options for <application>named</application> on
	&os;, take a look at the
	<literal>named_<replaceable>*</replaceable></literal> flags in
	<filename>/etc/defaults/rc.conf</filename> and consult the
	&man.rc.conf.5; manual page.  The <xref
	  linkend="configtuning-rcd"/> section is also a good
	read.</para>
    </sect2>

    <sect2>
      <title>Configuration Files</title>

      <indexterm>
	<primary>BIND</primary>
	<secondary>configuration files</secondary>
      </indexterm>

      <para>Configuration files for <application>named</application>
	currently reside in <filename
	  class="directory">/etc/namedb</filename> directory and will
	need modification before use unless all that is needed is a
	simple resolver.  This is where most of the configuration will
	be performed.</para>

      <sect3>
	<title><filename>/etc/namedb/named.conf</filename></title>

	<programlisting>// &dollar;FreeBSD&dollar;
//
// Refer to the named.conf(5) and named(8) man pages, and the documentation
// in /usr/share/doc/bind9 for more details.
//
// If you are going to set up an authoritative server, make sure you
// understand the hairy details of how DNS works.  Even with
// simple mistakes, you can break connectivity for affected parties,
// or cause huge amounts of useless Internet traffic.

options {
	// All file and path names are relative to the chroot directory,
	// if any, and should be fully qualified.
	directory	"/etc/namedb/working";
	pid-file	"/var/run/named/pid";
	dump-file	"/var/dump/named_dump.db";
	statistics-file	"/var/stats/named.stats";

// If named is being used only as a local resolver, this is a safe default.
// For named to be accessible to the network, comment this option, specify
// the proper IP address, or delete this option.
	listen-on	{ 127.0.0.1; };

// If you have IPv6 enabled on this system, uncomment this option for
// use as a local resolver.  To give access to the network, specify
// an IPv6 address, or the keyword "any".
//	listen-on-v6	{ ::1; };

// These zones are already covered by the empty zones listed below.
// If you remove the related empty zones below, comment these lines out.
	disable-empty-zone "255.255.255.255.IN-ADDR.ARPA";
	disable-empty-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.0.IP6.ARPA";
	disable-empty-zone "1.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.ARPA";

// 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;
	};
*/

// If the 'forwarders' clause is not empty the default is to 'forward first'
// which will fall back to sending a query from your local server if the name
// servers in 'forwarders' do not have the answer.  Alternatively you can
// force your name server to never initiate queries of its own by enabling the
// following line:
//	forward only;

// If you wish to have forwarding configured automatically based on
// the entries in /etc/resolv.conf, uncomment the following line and
// set named_auto_forward=yes in /etc/rc.conf.  You can also enable
// named_auto_forward_only (the effect of which is described above).
//	include "/etc/namedb/auto_forward.conf";</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
	    <acronym>IP</acronym> address to a name server at your
	    uplink.</para>
	</warning>

	<programlisting>	/*
	   Modern versions of BIND use a random UDP port for each outgoing
	   query by default in order to dramatically reduce the possibility
	   of cache poisoning.  All users are strongly encouraged to utilize
	   this feature, and to configure their firewalls to accommodate it.

	   AS A LAST RESORT in order to get around a restrictive firewall
	   policy you can try enabling the option below.  Use of this option
	   will significantly reduce your ability to withstand cache poisoning
	   attacks, and should be avoided if at all possible.

	   Replace NNNNN in the example with a number between 49160 and 65530.
	*/
	// query-source address * port NNNNN;
};

// If you enable a local name server, don't forget to enter 127.0.0.1
// first in your /etc/resolv.conf so this server will be queried.
// Also, make sure to enable it in /etc/rc.conf.

// The traditional root hints mechanism. Use this, OR the slave zones below.
zone "." { type hint; file "/etc/namedb/named.root"; };

/*	Slaving the following zones from the root name servers has some
	significant advantages:
	1. Faster local resolution for your users
	2. No spurious traffic will be sent from your network to the roots
	3. Greater resilience to any potential root server failure/DDoS

	On the other hand, this method requires more monitoring than the
	hints file to be sure that an unexpected failure mode has not
	incapacitated your server.  Name servers that are serving a lot
	of clients will benefit more from this approach than individual
	hosts.  Use with caution.

	To use this mechanism, uncomment the entries below, and comment
	the hint zone above.

	As documented at http://dns.icann.org/services/axfr/ these zones:
	"." (the root), ARPA, IN-ADDR.ARPA, IP6.ARPA, and ROOT-SERVERS.NET
	are available for AXFR from these servers on IPv4 and IPv6:
	xfr.lax.dns.icann.org, xfr.cjr.dns.icann.org
*/
/*
zone "." {
	type slave;
	file "/etc/namedb/slave/root.slave";
	masters {
		192.5.5.241;	// F.ROOT-SERVERS.NET.
	};
	notify no;
};
zone "arpa" {
	type slave;
	file "/etc/namedb/slave/arpa.slave";
	masters {
		192.5.5.241;	// F.ROOT-SERVERS.NET.
	};
	notify no;
};
*/

/*	Serving the following zones locally will prevent any queries
	for these zones leaving your network and going to the root
	name servers.  This has two significant advantages:
	1. Faster local resolution for your users
	2. No spurious traffic will be sent from your network to the roots
*/
// RFCs 1912 and 5735 (and BCP 32 for localhost)
zone "localhost"	{ type master; file "/etc/namedb/master/localhost-forward.db"; };
zone "127.in-addr.arpa"	{ type master; file "/etc/namedb/master/localhost-reverse.db"; };
zone "255.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// RFC 1912-style zone for IPv6 localhost address
zone "0.ip6.arpa"	{ type master; file "/etc/namedb/master/localhost-reverse.db"; };

// "This" Network (RFCs 1912 and 5735)
zone "0.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// Private Use Networks (RFCs 1918 and 5735)
zone "10.in-addr.arpa"	   { type master; file "/etc/namedb/master/empty.db"; };
zone "16.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "17.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "18.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "19.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "20.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "21.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "22.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "23.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "24.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "25.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "26.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "27.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "28.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "29.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "30.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "31.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "168.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };

// Link-local/APIPA (RFCs 3927 and 5735)
zone "254.169.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };

// IETF protocol assignments (RFCs 5735 and 5736)
zone "0.0.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };

// TEST-NET-[1-3] for Documentation (RFCs 5735 and 5737)
zone "2.0.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "100.51.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "113.0.203.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };

// IPv6 Range for Documentation (RFC 3849)
zone "8.b.d.0.1.0.0.2.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; };

// Domain Names for Documentation and Testing (BCP 32)
zone "test" { type master; file "/etc/namedb/master/empty.db"; };
zone "example" { type master; file "/etc/namedb/master/empty.db"; };
zone "invalid" { type master; file "/etc/namedb/master/empty.db"; };
zone "example.com" { type master; file "/etc/namedb/master/empty.db"; };
zone "example.net" { type master; file "/etc/namedb/master/empty.db"; };
zone "example.org" { type master; file "/etc/namedb/master/empty.db"; };

// Router Benchmark Testing (RFCs 2544 and 5735)
zone "18.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };
zone "19.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; };

// IANA Reserved - Old Class E Space (RFC 5735)
zone "240.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "241.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "242.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "243.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "244.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "245.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "246.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "247.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "248.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "249.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "250.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "251.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "252.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "253.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "254.in-addr.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// IPv6 Unassigned Addresses (RFC 4291)
zone "1.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "3.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "4.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "5.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "6.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "7.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "8.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "9.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "a.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "b.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "c.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "d.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "e.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "0.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "1.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "2.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "3.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "4.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "5.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "6.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "7.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "8.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "9.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "a.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "b.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "0.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "1.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "2.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "3.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "4.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "5.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "6.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "7.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// IPv6 ULA (RFC 4193)
zone "c.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "d.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// IPv6 Link Local (RFC 4291)
zone "8.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "9.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "a.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "b.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// IPv6 Deprecated Site-Local Addresses (RFC 3879)
zone "c.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "d.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "e.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };
zone "f.e.f.ip6.arpa"	{ type master; file "/etc/namedb/master/empty.db"; };

// IP6.INT is Deprecated (RFC 4159)
zone "ip6.int"		{ type master; file "/etc/namedb/master/empty.db"; };

// NB: Do not use the IP addresses below, they are faked, and only
// serve demonstration/documentation purposes!
//
// Example slave zone config entries.  It can be convenient to become
// a slave at least for the zone your own domain is in.  Ask
// your network administrator for the IP address of the responsible
// master name server.
//
// Do not forget to include the reverse lookup zone!
// This is named after the first bytes of the IP address, in reverse
// order, with ".IN-ADDR.ARPA" appended, or ".IP6.ARPA" for IPv6.
//
// Before starting to set up a master zone, make sure you fully
// understand how DNS and BIND work.  There are sometimes
// non-obvious pitfalls.  Setting up a slave zone is usually simpler.
//
// NB: Don't blindly enable the examples below. :-)  Use actual names
// and addresses instead.

/* An example dynamic zone
key "exampleorgkey" {
	algorithm hmac-md5;
	secret "sf87HJqjkqh8ac87a02lla==";
};
zone "example.org" {
	type master;
	allow-update {
		key "exampleorgkey";
	};
	file "/etc/namedb/dynamic/example.org";
};
*/

/* Example of a slave reverse zone
zone "1.168.192.in-addr.arpa" {
	type slave;
	file "/etc/namedb/slave/1.168.192.in-addr.arpa";
	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 "master/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/master/example.org</filename>
	  indicated by the <option>file</option> statement.</para>

	<programlisting>zone "example.org" {
	type slave;
	file "slave/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>
	<indexterm>
	  <primary>BIND</primary>
	  <secondary>zone files</secondary>
	</indexterm>

	<para>An example master zone file for <hostid
	    role="domainname">example.org</hostid> (existing within
	  <filename>/etc/namedb/master/example.org</filename>) is as
	  follows:</para>

	<programlisting>&dollar;TTL 3600        ; 1 hour default TTL
example.org.    IN      SOA      ns1.example.org. admin.example.org. (
                                2006051501      ; Serial
                                10800           ; Refresh
                                3600            ; Retry
                                604800          ; Expire
                                300             ; Negative Response TTL
                        )

; DNS Servers
                IN      NS      ns1.example.org.
                IN      NS      ns2.example.org.

; MX Records
                IN      MX 10   mx.example.org.
                IN      MX 20   mail.example.org.

                IN      A       192.168.1.1

; Machine Names
localhost       IN      A       127.0.0.1
ns1             IN      A       192.168.1.2
ns2             IN      A       192.168.1.3
mx              IN      A       192.168.1.4
mail            IN      A       192.168.1.5

; Aliases
www             IN      CNAME   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 relative to the origin.  For example,
	  <literal>ns1</literal> is translated into
	  <literal>ns1.<replaceable>example.org.</replaceable></literal></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. (
                        2006051501      ; Serial
                        10800           ; Refresh after 3 hours
                        3600            ; Retry after 1 hour
                        604800          ; Expire after 1 week
                        300 )           ; Negative Response TTL</programlisting>

	<variablelist>
	  <varlistentry>
	    <term><hostid
	      role="domainname">example.org.</hostid></term>

	    <listitem>
	      <para>the domain name, also the origin for this
		zone file.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><hostid role="fqdn">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 <quote>@</quote>
		replaced.  (<email>admin@example.org</email> becomes
		<literal>admin.example.org</literal>)</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>2006051501</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.  <literal>2006051501</literal> would mean
		last modified 05/15/2006, the latter
		<literal>01</literal> being the first 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 NS entry.  Every name server that is going to
	  reply authoritatively for the zone must have one of these
	  entries.</para>

	<programlisting>localhost       IN      A       127.0.0.1
ns1             IN      A       192.168.1.2
ns2             IN      A       192.168.1.3
mx              IN      A       192.168.1.4
mail            IN      A       192.168.1.5</programlisting>

	<para>The A record indicates machine names.  As seen above,
	  <hostid role="fqdn">ns1.example.org</hostid> would resolve
	  to <hostid role="ipaddr">192.168.1.2</hostid>.</para>

	<programlisting>                IN      A       192.168.1.1</programlisting>

	<para>This line assigns IP address <hostid
	    role="ipaddr">192.168.1.1</hostid> to the current origin,
	  in this case <hostid
	    role="domainname">example.org</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 <quote>master</quote> machine whose name
	  happens to be the same as the domain name <hostid
	    role="domainname">example.org</hostid> (<hostid
	  role="ipaddr">192.168.1.1</hostid>).  CNAMEs can never be
	  used together with another kind of record
	  for the same hostname.</para>

	<indexterm>
	  <primary>MX record</primary>
	</indexterm>

	<programlisting>               IN MX   10      mail.example.org.</programlisting>

	<para>The MX 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 a mail server, and 10 is the priority of
	  that mail server.</para>

	<para>One can have several mail servers, with priorities of
	  10, 20 and so on.  A mail server attempting to deliver to
	  <hostid role="domainname">example.org</hostid> would first
	  try the highest priority MX (the record with the lowest
	  priority number), then the second highest, etc, until the
	  mail can be properly delivered.</para>

	<para>For in-addr.arpa zone files (reverse DNS), the same
	  format is used, except with PTR entries instead of A or
	  CNAME.</para>

	<programlisting>$TTL 3600

1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. (
                        2006051501      ; Serial
                        10800           ; Refresh
                        3600            ; Retry
                        604800          ; Expire
                        300 )           ; Negative Response TTL

        IN      NS      ns1.example.org.
        IN      NS      ns2.example.org.

1       IN      PTR     example.org.
2       IN      PTR     ns1.example.org.
3       IN      PTR     ns2.example.org.
4       IN      PTR     mx.example.org.
5       IN      PTR     mail.example.org.</programlisting>

	<para>This file gives the proper IP address to hostname
	  mappings for the above fictitious domain.</para>

	<para>It is worth noting that all names on the right side
	  of a PTR record need to be fully qualified (i.e., end in
	  a <quote>.</quote>).</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 whose primary role
	is to resolve recursive queries.  It simply asks queries of
	its own, and remembers the answers for later use.</para>
    </sect2>

    <sect2>
      <title><acronym
	  role="Domain Name Security Extensions">DNSSEC</acronym></title>
      <indexterm>
	<primary>BIND</primary>
	<secondary>DNS security extensions</secondary>
      </indexterm>

      <para>Domain Name System Security Extensions, or <acronym
	  role="Domain Name Security Extensions">DNSSEC</acronym> for
	short, is a suite of specifications to protect resolving name
	servers from forged <acronym>DNS</acronym> data, such as
	spoofed <acronym>DNS</acronym> records.  By using digital
	signatures, a resolver can verify the integrity of the record.
	Note that <acronym
	  role="Domain Name Security Extensions">DNSSEC</acronym> only
	provides integrity via digitally signing the Resource
	Records (<acronym role="Resource Record">RR</acronym>s).  It
	provides neither confidentiality nor protection against false
	end-user assumptions.  This means that it cannot protect
	against people going to <hostid
	  role="domainname">example.net</hostid> instead of <hostid
	  role="domainname">example.com</hostid>.  The only thing
	<acronym>DNSSEC</acronym> does is authenticate that the data
	has not been compromised in transit.  The security of
	<acronym>DNS</acronym> is an important step in securing the
	Internet in general.  For more in-depth details of how
	<acronym>DNSSEC</acronym> works, the relevant
	<acronym>RFC</acronym>s are a good place to start.  See the
	list in <xref linkend="dns-read"/>.</para>

      <para>The following sections will demonstrate how to enable
	<acronym>DNSSEC</acronym> for an authoritative
	<acronym>DNS</acronym> server and a recursive (or caching)
	<acronym>DNS</acronym> server running <acronym>BIND</acronym>
	9.  While all versions of <acronym>BIND</acronym> 9 support
	<acronym>DNSSEC</acronym>, it is necessary to have at least
	version 9.6.2 in order to be able to use the signed root zone
	when validating <acronym>DNS</acronym> queries.  This is
	because earlier versions lack the required algorithms to
	enable validation using the root zone key.  It is strongly
	recommended to use the latest version of
	<acronym>BIND</acronym> 9.7 or later to take advantage of
	automatic key updating for the root key, as well as other
	features to automatically keep zones signed and signatures up
	to date.  Where configurations differ between 9.6.2 and 9.7
	and later, differences will be pointed out.</para>

      <sect3>
	<title>Recursive <acronym>DNS</acronym> Server
	  Configuration</title>

	<para>Enabling <acronym>DNSSEC</acronym> validation of queries
	  performed by a recursive <acronym>DNS</acronym> server
	  requires a few changes to <filename>named.conf</filename>.
	  Before making these changes the root zone key, or trust
	  anchor, must be acquired.  Currently the root zone key is
	  not available in a file format <acronym>BIND</acronym>
	  understands, so it has to be manually converted into the
	  proper format.  The key itself can be obtained by querying
	  the root zone for it using <application>dig</application>.
	  By running</para>

	<screen>&prompt.user; <userinput>dig +multi +noall +answer DNSKEY . &gt; root.dnskey</userinput></screen>

	<para>the key will end up in <filename>root.dnskey</filename>.
	  The contents should look something like this:</para>

	<programlisting>. 93910 IN DNSKEY 257 3 8 (
	AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQ
	bSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh
	/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWA
	JQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXp
	oY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3
	LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGO
	Yl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGc
	LmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=
	) ; key id = 19036
. 93910 IN DNSKEY 256 3 8 (
	AwEAAcaGQEA+OJmOzfzVfoYN249JId7gx+OZMbxy69Hf
	UyuGBbRN0+HuTOpBxxBCkNOL+EJB9qJxt+0FEY6ZUVjE
	g58sRr4ZQ6Iu6b1xTBKgc193zUARk4mmQ/PPGxn7Cn5V
	EGJ/1h6dNaiXuRHwR+7oWh7DnzkIJChcTqlFrXDW3tjt
) ; key id = 34525</programlisting>

	<para>Do not be alarmed if the obtained keys differ from this
	  example.  They might have changed since these instructions
	  were last updated.  This output actually contains two keys.
	  The first key in the listing, with the value 257 after the
	  DNSKEY record type, is the one needed.  This value indicates
	  that this is a Secure Entry Point (<acronym
	    role="Secure Entry Point">SEP</acronym>), commonly known
	  as a Key Signing Key (<acronym
	    role="Key Signing Key">KSK</acronym>).  The second key,
	  with value 256, is a subordinate key, commonly called a Zone
	  Signing Key (<acronym
	    role="Zone Signing Key">ZSK</acronym>).  More on the
	  different key types later in <xref
	    linkend="dns-dnssec-auth"/>.</para>

	<para>Now the key must be verified and formatted so that
	  <acronym>BIND</acronym> can use it.  To verify the key,
	  generate a <acronym role="Delegation Signer">DS</acronym>
	  <acronym role="Resource Record">RR</acronym> set.  Create a
	  file containing these <acronym
	    role="Resource Record">RR</acronym>s with</para>

	<screen>&prompt.user; <userinput>dnssec-dsfromkey -f root-dnskey . &gt; root.ds</userinput></screen>

	<para>These records use SHA-1 and SHA-256 respectively, and
	  should look similar to the following example, where the
	  longer is using SHA-256.</para>

	<programlisting>.  IN DS 19036 8 1
	B256BD09DC8DD59F0E0F0D8541B8328DD986DF6E
. IN DS 19036 8 2 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5</programlisting>

	<para>The SHA-256 <acronym>RR</acronym> can now be compared to
	  the digest in <ulink
	    url="https://data.iana.org/root-anchors/root-anchors.xml">https://data.iana.org/root-anchors/root-anchors.xml</ulink>.
	  To be absolutely sure that the key has not been tampered
	  with the data in the <acronym>XML</acronym> file can be
	  verified using the <acronym>PGP</acronym> signature in
	  <ulink
	    url="https://data.iana.org/root-anchors/root-anchors.asc">https://data.iana.org/root-anchors/root-anchors.asc</ulink>.</para>

	<para>Next, the key must be formatted properly.  This differs
	  a little between <acronym>BIND</acronym> versions 9.6.2 and
	  9.7 and later.  In version 9.7 support was added to
	  automatically track changes to the key and update it as
	  necessary.  This is done using
	  <literal>managed-keys</literal> as seen in the example
	  below.  When using the older version, the key is added using
	  a <literal>trusted-keys</literal> statement and updates must
	  be done manually.  For <acronym>BIND</acronym> 9.6.2 the
	  format should look like:</para>

	<programlisting>trusted-keys {
	"." 257 3 8
	"AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjF
	FVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoX
	bfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaD
	X6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpz
	W5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relS
	Qageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulq
	QxA+Uk1ihz0=";
};</programlisting>

	<para>For 9.7 the format will instead be:</para>

	<programlisting>managed-keys {
	"." initial-key 257 3 8
	"AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjF
	FVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoX
	bfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaD
	X6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpz
	W5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relS
	Qageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulq
	QxA+Uk1ihz0=";
};</programlisting>

	<para>The root key can now be added to
	  <filename>named.conf</filename> either directly or by
	  including a file containing the key.  After these steps,
	  configure <acronym>BIND</acronym> to do
	  <acronym>DNSSEC</acronym> validation on queries by editing
	  <filename>named.conf</filename> and adding the following to
	  the <literal>options</literal> directive:</para>

	<programlisting>dnssec-enable yes;
dnssec-validation yes;</programlisting>

	<para>To verify that it is actually working use
	  <application>dig</application> to make a query for a signed
	  zone using the resolver just configured.  A successful reply
	  will contain the <literal>AD</literal> flag to indicate the
	  data was authenticated.  Running a query such as</para>

	<screen>&prompt.user; <userinput>dig @<replaceable>resolver</replaceable> +dnssec se ds </userinput></screen>

	<para>should return the <acronym>DS</acronym>
	  <acronym>RR</acronym> for the <literal>.se</literal> zone.
	  In the <literal>flags:</literal> section the
	  <literal>AD</literal> flag should be set, as seen
	  in:</para>

	<programlisting>...
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1
...</programlisting>

	<para>The resolver is now capable of authenticating
	  <acronym>DNS</acronym> queries.</para>
      </sect3>

      <sect3 id="dns-dnssec-auth">
	<title>Authoritative <acronym>DNS</acronym> Server
	  Configuration</title>

	<para>In order to get an authoritative name server to serve a
	  <acronym>DNSSEC</acronym> signed zone a little more work is
	  required.  A zone is signed using cryptographic keys which
	  must be generated.  It is possible to use only one key for
	  this.  The preferred method however is to have a strong
	  well-protected Key Signing Key (<acronym
	    role="Key Signing Key">KSK</acronym>) that is
	  not rotated very often and a Zone Signing Key (<acronym
	  role="Zone Signing Key">ZSK</acronym>) that is rotated more
	  frequently.  Information on recommended operational
	  practices can be found in <ulink
	    url="http://tools.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym>
	    4641: <acronym>DNSSEC</acronym> Operational
	    Practices</ulink>.  Practices regarding the root zone can
	  be found in <ulink
	    url="http://www.root-dnssec.org/wp-content/uploads/2010/06/icann-dps-00.txt"><acronym>DNSSEC</acronym>
	    Practice Statement for the Root Zone
	  <acronym>KSK</acronym> operator</ulink> and <ulink
	    url="http://www.root-dnssec.org/wp-content/uploads/2010/06/vrsn-dps-00.txt"><acronym>DNSSEC</acronym>
	    Practice Statement for the Root Zone
	  <acronym>ZSK</acronym> operator</ulink>.  The <acronym
	    role="Key Signing Key">KSK</acronym> is used to build a
	  chain of authority to the data in need of validation and as
	  such is also called a Secure Entry Point (<acronym
	    role="Secure Entry Point">SEP</acronym>) key.  A message
	  digest of this key, called a Delegation Signer (<acronym
	    role="Delegation Signer">DS</acronym>) record, must be
	  published in the parent zone to establish the trust chain.
	  How this is accomplished depends on the parent zone owner.
	  The <acronym
	    role="Zone Signing Key">ZSK</acronym> is used to sign the
	  zone, and only needs to be published there.</para>

	<para>To enable <acronym>DNSSEC</acronym> for the <hostid
	    role="domainname">example.com</hostid> zone depicted in
	  previous examples, the first step is to use
	  <application>dnssec-keygen</application> to generate the
	  <acronym>KSK</acronym> and <acronym>ZSK</acronym> key pair.
	  This key pair can utilize different cryptographic
	  algorithms.  It is recommended to use RSA/SHA256 for the
	  keys and 2048 bits key length should be enough.  To generate
	  the <acronym>KSK</acronym> for <hostid
	    role="domainname">example.com</hostid>, run</para>

	<screen>&prompt.user; <userinput>dnssec-keygen -f KSK -a RSASHA256 -b 2048 -n ZONE example.com</userinput></screen>

	<para>and to generate the <acronym>ZSK</acronym>, run</para>

	<screen>&prompt.user; <userinput>dnssec-keygen -a RSASHA256 -b 2048 -n ZONE example.com</userinput></screen>

	<para><application>dnssec-keygen</application> outputs two
	  files, the public and the private keys in files named
	  similar to <filename>Kexample.com.+005+nnnnn.key</filename>
	  (public) and
	  <filename>Kexample.com.+005+nnnnn.private</filename>
	  (private).  The <literal>nnnnn</literal> part of the file
	  name is a five digit key ID.  Keep track of which key ID
	  belongs to which key.  This is especially important when
	  having more than one key in a zone.  It is
	  also possible to rename the keys.  For each
	  <acronym>KSK</acronym> file do:</para>

	<screen>&prompt.user; <userinput>mv Kexample.com.+005+nnnnn.key Kexample.com.+005+nnnnn.KSK.key</userinput>
&prompt.user; <userinput>mv Kexample.com.+005+nnnnn.private Kexample.com.+005+nnnnn.KSK.private</userinput></screen>

	<para>For the <acronym>ZSK</acronym> files, substitute
	  <literal>KSK</literal> for <literal>ZSK</literal> as
	  necessary.  The files can now be included in the zone file,
	  using the <literal>$include</literal> statement.  It should
	  look something like this:</para>

	<programlisting>$include Kexample.com.+005+nnnnn.KSK.key ; KSK
$include Kexample.com.+005+nnnnn.ZSK.key    ; ZSK</programlisting>

	<para>Finally, sign the zone and tell <acronym>BIND</acronym>
	  to use the signed zone file.  To sign a zone
	  <application>dnssec-signzone</application> is used.  The
	  command to sign the zone <hostid
	    role="domainname">example.com</hostid>, located in
	  <filename>example.com.db</filename> would look similar
	  to</para>

	<screen>&prompt.user; <userinput>dnssec-signzone -o
	example.com -k Kexample.com.+005+nnnnn.KSK example.com.db
	Kexample.com.+005+nnnnn.ZSK.key</userinput></screen>

	<para>The key supplied to the <option>-k</option> argument is
	  the <acronym>KSK</acronym> and the other key file is the
	  <acronym>ZSK</acronym> that should be used in the signing.
	  It is possible to supply more than one
	  <acronym>KSK</acronym> and <acronym>ZSK</acronym>, which
	  will result in the zone being signed with all supplied keys.
	  This can be needed to supply zone data signed using more
	  than one algorithm.  The output of
	  <application>dnssec-signzone</application> is a zone file
	  with all <acronym>RR</acronym>s signed.  This output will
	  end up in a file with the extension
	  <literal>.signed</literal>, such as
	  <filename>example.com.db.signed</filename>.  The <acronym
	    role="Delegation Signer">DS</acronym> records will also be
	  written to a separate file
	  <filename>dsset-example.com</filename>.
	  To use this signed zone just modify the zone directive in
	  <filename>named.conf</filename> to use
	  <filename>example.com.db.signed</filename>.  By default, the
	  signatures are only valid 30 days, meaning that the zone
	  needs to be resigned in about 15 days to be sure that
	  resolvers are not caching records with stale signatures.  It
	  is possible to make a script and a cron job to do this.  See
	  relevant manuals for details.</para>

	<para>Be sure to keep private keys confidential, as with all
	  cryptographic keys.  When changing a key it is best to
	  include the new key into the zone, while still signing with
	  the old one, and then move over to using the new key to
	  sign.  After these steps are done the old key can be removed
	  from the zone.  Failure to do this might render the
	  <acronym>DNS</acronym> data unavailable for a time, until
	  the new key has propagated through the
	  <acronym>DNS</acronym> hierarchy.  For more information on
	  key rollovers and other <acronym>DNSSEC</acronym>
	  operational issues, see <ulink
	    url="http://www.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym>
	    4641: <acronym>DNSSEC</acronym> Operational
	    practices</ulink>.</para>
      </sect3>

      <sect3>
	<title>Automation Using <acronym>BIND</acronym> 9.7 or
	  Later</title>

	<para>Beginning with <acronym>BIND</acronym> version 9.7 a new
	  feature called <emphasis>Smart Signing</emphasis> was
	  introduced.  This feature aims to make the key management
	  and signing process simpler by automating parts of the task.
	  By putting the keys into a directory called a <emphasis>key
	  repository</emphasis>, and using the new option
	  <literal>auto-dnssec</literal>, it is possible to create a
	  dynamic zone which will be resigned as needed.  To update
	  this zone use <application>nsupdate</application> with the
	  new option <option>-l</option>.
	  <application>rndc</application> has also grown the ability
	  to sign zones with keys in the key repository, using the
	  option <option>sign</option>.  To tell
	  <acronym>BIND</acronym> to use this automatic signing and
	  zone updating for <hostid
	    role="domainname">example.com</hostid>, add the following
	  to <filename>named.conf</filename>:</para>

	<programlisting>zone example.com {
	type master;
	key-directory "/etc/named/keys";
	update-policy local;
	auto-dnssec maintain;
	file "/etc/named/dynamic/example.com.zone";
};</programlisting>

	<para>After making these changes, generate keys for the zone
	  as explained in <xref linkend="dns-dnssec-auth"/>, put those
	  keys in the key repository given as the argument to the
	  <literal>key-directory</literal> in the zone configuration
	  and the zone will be signed automatically.  Updates to a
	  zone configured this way must be done using
	  <application>nsupdate</application>, which will take care of
	  re-signing the zone with the new data added.  For further
	  details, see <xref linkend="dns-read"/> and the
	  <acronym>BIND</acronym> documentation.</para>
      </sect3>
    </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>While &os; automatically drops
	<application>named</application> into a &man.chroot.8;
	environment; there are several other security mechanisms in
	place which could help to lure off possible
	<acronym>DNS</acronym> service attacks.</para>

      <para>It is always good idea to read <ulink
	  url="http://www.cert.org/">CERT</ulink>'s security
	advisories and to subscribe to the &a.security-notifications;
	to stay up to date with the current Internet and &os; security
	issues.</para>

      <tip>
	<para>If a problem arises, keeping sources up to date and
	  having a fresh build of <application>named</application>
	  may help.</para>
      </tip>
    </sect2>

    <sect2 id="dns-read">
      <title>Further Reading</title>

      <para>BIND/<application>named</application> manual pages:
	&man.rndc.8; &man.named.8; &man.named.conf.5; &man.nsupdate.8;
	&man.dnssec-signzone.8; &man.dnssec-keygen.8;</para>

      <itemizedlist>
	<listitem>
	  <para><ulink
	      url="https://www.isc.org/software/bind">Official ISC
	      BIND Page</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="https://www.isc.org/software/guild">Official ISC
	      BIND Forum</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://www.oreilly.com/catalog/dns5/">O'Reilly
	      DNS and BIND 5th Edition</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://www.root-dnssec.org/documentation/">Root
	      <acronym>DNSSEC</acronym></ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html"><acronym>DNSSEC</acronym>
	      Trust Anchor Publication for the Root
	      Zone</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc1034">RFC1034
	      - Domain Names - Concepts and Facilities</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc1035">RFC1035
	      - Domain Names - Implementation and
	      Specification</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc4033">RFC4033
	      - DNS Security Introduction and
	      Requirements</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc4034">RFC4034
	      - Resource Records for the DNS Security
	      Extensions</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc4035">RFC4035
	      - Protocol Modifications for the DNS Security
	      Extensions</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc4641">RFC4641
	      - DNSSEC Operational Practices</ulink></para>
	</listitem>

	<listitem>
	  <para><ulink
	      url="http://tools.ietf.org/html/rfc5011">RFC 5011
	      - Automated Updates of DNS Security
	      (<acronym>DNSSEC</acronym>
	      Trust Anchors</ulink></para>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="network-apache">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Murray</firstname>
	  <surname>Stokely</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Apache HTTP Server</title>

    <indexterm><primary>web servers</primary>
      <secondary>setting up</secondary></indexterm>
    <indexterm><primary>Apache</primary></indexterm>

    <sect2>
      <title>Overview</title>

      <para>&os; is used to run some of the busiest web sites in the
	world.  The majority of web servers on the Internet are using
	the <application>Apache HTTP Server</application>.
	<application>Apache</application> software packages should be
	included on your FreeBSD installation media.  If you did not
	install <application>Apache</application> when you first
	installed FreeBSD, then you can install it from the <filename
	  role="package">www/apache22</filename> port.</para>

      <para>Once <application>Apache</application> has been installed
	successfully, it must be configured.</para>

      <note><para>This section covers version 2.2.X of the
	<application>Apache HTTP Server</application> as that is the
	most widely used version for &os;.  For more detailed
	information beyond the scope of this document about
	<application>Apache</application>&nbsp;2.X, please see <ulink
	  url="http://httpd.apache.org/"></ulink>.</para></note>

    </sect2>

    <sect2>
      <title>Configuration</title>

      <indexterm><primary>Apache</primary>
	<secondary>configuration file</secondary></indexterm>

      <para>The main <application>Apache HTTP Server</application>
	configuration file is installed as
	<filename>/usr/local/etc/apache22/httpd.conf</filename> on
	&os;.  This file is a typical &unix; text configuration file
	with comment lines beginning with the <literal>#</literal>
	character.  A comprehensive description of all possible
	configuration options is outside the scope of this book, so
	only the most frequently modified directives will be described
	here.</para>

      <variablelist>
	<varlistentry>
	  <term><literal>ServerRoot "/usr/local"</literal></term>

	  <listitem>
	    <para>This specifies the default directory hierarchy for
	      the <application>Apache</application> installation.
	      Binaries are stored in the <filename
		class="directory">bin</filename> and
	      <filename
		class="directory">sbin</filename> subdirectories
	      of the server root, and configuration files are stored
	      in <filename
		class="directory">etc/apache</filename>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>ServerAdmin you@your.address</literal></term>

	  <listitem>
	    <para>The address to which problems with the server should
	      be emailed.  This address appears on some
	      server-generated pages, such as error documents.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>ServerName www.example.com</literal></term>

	  <listitem>
	    <para><literal>ServerName</literal> allows you to set a
	      host name which is sent back to clients for your server
	      if it is different than the one that the host is
	      configured with (i.e., use <hostid>www</hostid> instead
	      of the host's real name).</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><literal>DocumentRoot
	    "/usr/local/www/apache22/data"</literal></term>

	  <listitem>
	    <para><literal>DocumentRoot</literal>: The directory out
	      of which you will serve your documents.  By default, all
	      requests are taken from this directory, but symbolic
	      links and aliases may be used to point to other
	      locations.</para>
	  </listitem>
	</varlistentry>
      </variablelist>

      <para>It is always a good idea to make backup copies of your
	<application>Apache</application> configuration file before
	making changes.  Once you are satisfied with your initial
	configuration you are ready to start running
	<application>Apache</application>.</para>
    </sect2>

    <sect2>
      <title>Running <application>Apache</application></title>

      <indexterm><primary>Apache</primary>
	<secondary>starting or stopping</secondary></indexterm>

      <para>The <filename role="package">www/apache22</filename> port
	installs an &man.rc.8; script to aid in starting, stopping,
	and restarting <application>Apache</application>, which can be
	found in the <filename
	  class="directory">/usr/local/etc/rc.d/</filename>
	directory.</para>

      <para>To launch <application>Apache</application> at system
	startup, add the following line to
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>apache22_enable="YES"</programlisting>

      <para>If <application>Apache</application> should be started
	with non-default options, the following line may be added to
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>apache22_flags=""</programlisting>

      <para>The <application>Apache</application> configuration can be
	tested for errors before starting the <command>httpd</command>
	daemon for the first time, or after making subsequent
	configuration changes while <command>httpd</command> is
	running.  This can be done by the &man.rc.8; script directly,
	or by the &man.service.8; utility by issuing one of the
	following commands:</para>

      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/apache22 configtest</userinput></screen>
      <screen>&prompt.root; <userinput>service apache22 configtest</userinput></screen>

      <note>
	<para>It is important to note that the
	  <literal>configtest</literal> is not an &man.rc.8; standard,
	  and should not be expected to work for all &man.rc.8;
	  startup scripts.</para>
      </note>

      <para>If <application>Apache</application> does not report
	configuration errors, the
	<application>Apache</application>&nbsp;<command>httpd</command>
	can be started with the same &man.rc.8; and &man.service.8;
	mechanisms:</para>

      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/apache22 start</userinput></screen>
      <screen>&prompt.root; <userinput>service apache22 start</userinput></screen>

      <para>The <command>httpd</command> service can be tested by
	entering <literal>http://<hostid
	  role="fqdn"><replaceable>localhost</replaceable></hostid></literal>
	in a web browser, replacing
	<replaceable>localhost</replaceable> with the fully-qualified
	domain name of the machine running <command>httpd</command>,
	if it is not the local machine.  The default web page that is
	displayed is
	<filename>/usr/local/www/apache22/data/index.html</filename>.</para>

    </sect2>

    <sect2>
      <title>Virtual Hosting</title>

      <para><application>Apache</application> supports two different
	types of Virtual Hosting.  The first method is Name-based
	Virtual Hosting.  Name-based virtual hosting uses the clients
	HTTP/1.1 headers to figure out the hostname.  This allows many
	different domains to share the same IP address.</para>

      <para>To setup <application>Apache</application> to use
	Name-based Virtual Hosting add an entry like the following to
	your <filename>httpd.conf</filename>:</para>

      <programlisting>NameVirtualHost *</programlisting>

      <para>If your webserver was named <hostid
	  role="fqdn">www.domain.tld</hostid> and you wanted to setup
	a virtual domain for <hostid
	  role="fqdn">www.someotherdomain.tld</hostid> then you would
	add the following entries to
	<filename>httpd.conf</filename>:</para>

      <screen>&lt;VirtualHost *&gt;
ServerName www.domain.tld
DocumentRoot /www/domain.tld
&lt;/VirtualHost&gt;

&lt;VirtualHost *&gt;
ServerName www.someotherdomain.tld
DocumentRoot /www/someotherdomain.tld
&lt;/VirtualHost&gt;</screen>

      <para>Replace the addresses with the addresses you want to use
	and the path to the documents with what you are using.</para>

      <para>For more information about setting up virtual hosts,
	please consult the official <application>Apache</application>
	documentation at: <ulink
	  url="http://httpd.apache.org/docs/vhosts/"></ulink>.</para>
    </sect2>

    <sect2>
      <title>Apache Modules</title>

      <indexterm><primary>Apache</primary>
	<secondary>modules</secondary></indexterm>

      <para>There are many different <application>Apache</application>
	modules available to add functionality to the basic server.
	The FreeBSD Ports Collection provides an easy way to install
	<application>Apache</application> together with some of the
	more popular add-on modules.</para>

      <sect3>
	<title><application>mod_ssl</application></title>

	<indexterm><primary>web servers</primary>
	  <secondary>secure</secondary></indexterm>
	<indexterm><primary>SSL</primary></indexterm>
	<indexterm><primary>cryptography</primary></indexterm>

	<para>The <application>mod_ssl</application> module uses the
	  OpenSSL library to provide strong cryptography via the
	  Secure Sockets Layer (SSL v2/v3) and Transport Layer
	  Security (TLS v1) protocols.  This module provides
	  everything necessary to request a signed certificate from
	  a trusted certificate signing authority so that you can run
	  a secure web server on &os;.</para>

	<para>The <application>mod_ssl</application> module is built
	  by default, but can be enabled by specifying
	  <literal>-DWITH_SSL</literal> at compile time.</para>
      </sect3>

      <sect3>
	<title>Language Bindings</title>

	<para>There are Apache modules for most major scripting
	  languages.  These modules typically make it possible to
	  write <application>Apache</application> modules entirely in
	  a scripting language.  They are also often used as a
	  persistent interpreter embedded into the server that avoids
	  the overhead of starting an external interpreter and the
	  startup-time penalty for dynamic websites, as described in
	  the next section.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>Dynamic Websites</title>

      <indexterm><primary>web servers</primary>
	<secondary>dynamic</secondary></indexterm>

      <para>In the last decade, more businesses have turned to the
	Internet in order to enhance their revenue and increase
	exposure.  This has also increased the need for interactive
	web content.  While some companies, such as &microsoft;,
	have introduced solutions into their proprietary products,
	the open source community answered the call.  Modern options
	for dynamic web content include Django, Ruby on Rails,
	<application>mod_perl2</application>, and
	<application>mod_php</application>.</para>

      <sect3>
	<title>Django</title>

	<indexterm><primary>Python</primary></indexterm>
	<indexterm><primary>Django</primary></indexterm>

	<para>Django is a BSD licensed framework designed to allow
	  developers to write high performance, elegant web
	  applications quickly.  It provides an object-relational
	  mapper so that data types are developed as Python objects,
	  and a rich dynamic database-access API is provided for those
	  objects without the developer ever having to write SQL.  It
	  also provides an extensible template system so that the
	  logic of the application is separated from the HTML
	  presentation.</para>

	<para>Django depends on <application>mod_python</application>,
	  <application>Apache</application>, and an SQL database
	  engine of your choice.  The FreeBSD Port will install all of
	  these pre-requisites for you with the appropriate
	  flags.</para>

	<example id="network-www-django-install">
	  <title>Installing Django with
	    <application>Apache2</application>,
	    <application>mod_python3</application>, and
	    <application>PostgreSQL</application></title>

	  <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen>
	</example>

	<para>Once Django and these pre-requisites are installed, you
	  will need to create a Django project directory and then
	  configure Apache to use the embedded Python interpreter to
	  call your application for specific URLs on your site.</para>

	<example id="network-www-django-apache-config">
	  <title>Apache Configuration for Django/mod_python</title>

	  <para>You will need to add a line to the apache
	    <filename>httpd.conf</filename> file to configure Apache
	    to pass requests for certain URLs to your web
	    application:</para>

	  <screen>&lt;Location "/"&gt;
    SetHandler python-program
    PythonPath "['/dir/to/your/django/packages/'] + sys.path"
    PythonHandler django.core.handlers.modpython
    SetEnv DJANGO_SETTINGS_MODULE mysite.settings
    PythonAutoReload On
    PythonDebug On
&lt;/Location&gt;</screen>
	</example>
      </sect3>

      <sect3>
	<title>Ruby on Rails</title>

	<indexterm><primary>Ruby on Rails</primary></indexterm>

	<para>Ruby on Rails is another open source web framework that
	  provides a full development stack and is optimized to make
	  web developers more productive and capable of writing
	  powerful applications quickly.  It can be installed easily
	  from the ports system.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen>
      </sect3>

      <sect3>
	<title><application>mod_perl2</application></title>

	<indexterm>
	  <primary>mod_perl2</primary>
	  <secondary>Perl</secondary>
	</indexterm>

	<para>The <application>Apache</application>/Perl integration
	  project brings together the full power of the Perl
	  programming language and the
	  <application>Apache HTTP Server</application>.  With the
	  <application>mod_perl2</application> module it is possible
	  to write <application>Apache</application> modules entirely
	  in Perl.  In addition, the persistent interpreter embedded
	  in the server avoids the overhead of starting an external
	  interpreter and the penalty of Perl start-up time.</para>

	<para><application>mod_perl2</application> is available in the
	  <filename role="package">www/mod_perl2</filename>
	  port.</para>
      </sect3>

      <sect3>
	<sect3info>
	  <authorgroup>
	    <author>
	      <firstname>Tom</firstname>
	      <surname>Rhodes</surname>
	      <contrib>Written by </contrib>
	    </author>
	  </authorgroup>
	</sect3info>
	<title><application>mod_php</application></title>

	<indexterm>
	  <primary>mod_php</primary>
	  <secondary>PHP</secondary>
	</indexterm>

	<para><acronym>PHP</acronym>, also known as <quote>PHP:
	    Hypertext Preprocessor</quote> is a general-purpose
	  scripting language that is especially suited for Web
	  development.  Capable of being embedded into
	  <acronym>HTML</acronym> its syntax draws upon C, &java;,
	  and Perl with the intention of allowing web developers to
	  write dynamically generated webpages quickly.</para>

	<para>To gain support for <acronym>PHP</acronym>5 for the
	  <application>Apache</application> web server, begin by
	  installing the
	  <filename role="package">lang/php5</filename>
	  port.</para>

	<para>If the <filename role="package">lang/php5</filename>
	  port is being installed for the first time, available
	  <literal>OPTIONS</literal> will be displayed automatically.
	  If a menu is not displayed, i.e., because the <filename
	  role="package">lang/php5</filename> port has been installed
	  some time in the past, it is always possible to bring the
	  options dialog up again by running:</para>

	<screen>&prompt.root; <userinput>make config</userinput></screen>

	<para>in the port directory.</para>

	<para>In the options dialog, check the
	  <literal>APACHE</literal> option to build
	  <application>mod_php5</application> as a loadable module for
	  the <application>Apache</application> web server.</para>

	<note>
	  <para>A lot of sites are still using <acronym>PHP</acronym>4
	    for various reasons (i.e., compatibility issues or already
	    deployed web applications).  If the
	    <application>mod_php4</application> is needed instead of
	    <application>mod_php5</application>, then please use the
	    <filename role="package">lang/php4</filename> port.  The
	    <filename role="package">lang/php4</filename> port
	    supports many of the configuration and build-time options
	    of the <filename role="package">lang/php5</filename>
	    port.</para>
	</note>

	<para>This will install and configure the modules required
	  to support dynamic <acronym>PHP</acronym> applications.
	  Check to ensure the following sections have been added to
	  <filename>/usr/local/etc/apache22/httpd.conf</filename>:</para>

	<programlisting>LoadModule php5_module        libexec/apache/libphp5.so</programlisting>

	<programlisting>AddModule mod_php5.c
    &lt;IfModule mod_php5.c&gt;
        DirectoryIndex index.php index.html
    &lt;/IfModule&gt;
    &lt;IfModule mod_php5.c&gt;
        AddType application/x-httpd-php .php
        AddType application/x-httpd-php-source .phps
    &lt;/IfModule&gt;</programlisting>

	<para>Once completed, a simple call to the
	  <command>apachectl</command> command for a graceful
	  restart is needed to load the <acronym>PHP</acronym>
	  module:</para>

	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>

	<para>For future upgrades of <acronym>PHP</acronym>, the
	  <command>make config</command> command will not be required;
	  the selected <literal>OPTIONS</literal> are saved
	  automatically by the &os; Ports framework.</para>

	<para>The <acronym>PHP</acronym> support in &os; is extremely
	  modular so the base install is very limited.  It is very
	  easy to add support using the <filename
	    role="package">lang/php5-extensions</filename> port.
	  This port provides a menu driven interface to
	  <acronym>PHP</acronym> extension installation.
	  Alternatively, individual extensions can be installed using
	  the appropriate port.</para>

	<para>For instance, to add support for the
	  <application>MySQL</application> database server to
	  <acronym>PHP</acronym>5, simply install the port
	  <filename>databases/php5-mysql</filename>.</para>

	<para>After installing an extension, the
	  <application>Apache</application> server must be reloaded to
	  pick up the new configuration changes:</para>

	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="network-ftp">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Murray</firstname>
	  <surname>Stokely</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>File Transfer Protocol (FTP)</title>

    <indexterm><primary>FTP servers</primary></indexterm>

    <sect2>
      <title>Overview</title>

      <para>The File Transfer Protocol (FTP) provides users with a
	simple way to transfer files to and from an <acronym
	role="File Transfer Protocol">FTP</acronym> server.  &os;
	includes <acronym role="File Transfer Protocol">FTP</acronym>
	server software, <application>ftpd</application>, in the base
	system.  This makes setting up and administering an <acronym
	role="File Transfer Protocol">FTP</acronym> server on FreeBSD
	very straightforward.</para>
    </sect2>

    <sect2>
      <title>Configuration</title>

      <para>The most important configuration step is deciding which
	accounts will be allowed access to the FTP server.  A normal
	FreeBSD system has a number of system accounts used for
	various daemons, but unknown users should not be allowed to
	log in with these accounts.  The
	<filename>/etc/ftpusers</filename> file is a list of users
	disallowed any FTP access.  By default, it includes the
	aforementioned system accounts, but it is possible to add
	specific users here that should not be allowed access to
	FTP.</para>

      <para>You may want to restrict the access of some users without
	preventing them completely from using FTP.  This can be
	accomplished with the <filename>/etc/ftpchroot</filename>
	file.  This file lists users and groups subject to FTP access
	restrictions.  The &man.ftpchroot.5; manual page has all of
	the details so it will not be described in detail here.</para>

      <indexterm>
	<primary>FTP</primary>
	<secondary>anonymous</secondary>
      </indexterm>

      <para>If you would like to enable anonymous FTP access to your
	server, then you must create a user named
	<username>ftp</username> on your &os; system.  Users will then
	be able to log on to your FTP server with a username of
	<username>ftp</username> or <username>anonymous</username> and
	with any password (by convention an email address for the user
	should be used as the password).  The FTP server will call
	&man.chroot.2; when an anonymous user logs in, to restrict
	access to only the home directory of the
	<username>ftp</username> user.</para>

      <para>There are two text files that specify welcome messages to
	be displayed to FTP clients.  The contents of the file
	<filename>/etc/ftpwelcome</filename> will be displayed to
	users before they reach the login prompt.  After a successful
	login, the contents of the file
	<filename>/etc/ftpmotd</filename> will be displayed.  Note
	that the path to this file is relative to the login
	environment, so the file <filename>~ftp/etc/ftpmotd</filename>
	would be displayed for anonymous users.</para>

      <para>Once the FTP server has been configured properly, it must
	be enabled in <filename>/etc/inetd.conf</filename>.  All that
	is required here is to remove the comment symbol
	<quote>#</quote> from in front of the existing
	<application>ftpd</application> line :</para>

      <programlisting>ftp	stream	tcp	nowait	root	/usr/libexec/ftpd	ftpd -l</programlisting>

      <para>As explained in <xref linkend="network-inetd-reread"/>,
	the <application>inetd</application> configuration must be
	reloaded after this configuration file is changed.  Please
	refer to <xref linkend="network-inetd-settings"/> for details
	on enabling <application>inetd</application> on your
	system.</para>

      <para>Alternatively, <application>ftpd</application> can also be
	started as a stand-alone server.  In this case, it is
	sufficient to set the appropriate variable in
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>ftpd_enable="YES"</programlisting>

      <para>After setting the above variable, the stand-alone server
	will be started at the next reboot, or it can be started
	manually by executing the following command as
	<username>root</username>:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/ftpd start</userinput></screen>

      <para>You can now log on to your FTP server by typing:</para>

      <screen>&prompt.user; <userinput>ftp localhost</userinput></screen>

    </sect2>

    <sect2>
      <title>Maintaining</title>

      <indexterm><primary>syslog</primary></indexterm>
      <indexterm><primary>log files</primary>
	<secondary>FTP</secondary></indexterm>

      <para>The <application>ftpd</application> daemon uses
	&man.syslog.3; to log messages.  By default, the system log
	daemon will put messages related to FTP in the
	<filename>/var/log/xferlog</filename> file.  The location of
	the FTP log can be modified by changing the following line in
	<filename>/etc/syslog.conf</filename>:</para>

      <programlisting>ftp.info      /var/log/xferlog</programlisting>

      <indexterm>
	<primary>FTP</primary>
	<secondary>anonymous</secondary>
      </indexterm>

      <para>Be aware of the potential problems involved with running
	an anonymous FTP server.  In particular, you should think
	twice about allowing anonymous users to upload files.  You may
	find that your FTP site becomes a forum for the trade of
	unlicensed commercial software or worse.  If you do need to
	allow anonymous FTP uploads, then you should set up the
	permissions so that these files can not be read by other
	anonymous users until they have been reviewed.</para>

    </sect2>
  </sect1>

  <sect1 id="network-samba">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Murray</firstname>
	  <surname>Stokely</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>File and Print Services for &microsoft.windows; Clients
      (Samba)</title>

    <indexterm><primary>Samba server</primary></indexterm>
    <indexterm><primary>Microsoft Windows</primary></indexterm>
    <indexterm>
      <primary>file server</primary>
      <secondary>Windows clients</secondary>
    </indexterm>
    <indexterm>
      <primary>print server</primary>
      <secondary>Windows clients</secondary>
    </indexterm>

    <sect2>
      <title>Overview</title>

      <para><application>Samba</application> is a popular open source
	software package that provides file and print services for
	&microsoft.windows; clients.  Such clients can connect to and
	use FreeBSD filespace as if it was a local disk drive, or
	FreeBSD printers as if they were local printers.</para>

      <para><application>Samba</application> software packages should
	be included on your FreeBSD installation media.  If you did
	not install <application>Samba</application> when you first
	installed FreeBSD, then you can install it from the <filename
	role="package">net/samba34</filename> port or package.</para>

<!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. -->

    </sect2>

    <sect2>
      <title>Configuration</title>

      <para>A default <application>Samba</application> configuration
	file is installed as
	<filename>/usr/local/share/examples/samba34/smb.conf.default</filename>.
	This file must be copied to
	<filename>/usr/local/etc/smb.conf</filename> and customized
	before <application>Samba</application> can be used.</para>

      <para>The <filename>smb.conf</filename> file contains runtime
	configuration information for
	<application>Samba</application>, such as definitions of the
	printers and <quote>file system shares</quote> that you would
	like to share with &windows; clients.  The
	<application>Samba</application> package includes a web based
	tool called <application>swat</application> which provides a
	simple way of configuring the <filename>smb.conf</filename>
	file.</para>

      <sect3>
	<title>Using the Samba Web Administration Tool (SWAT)</title>

	<para>The Samba Web Administration Tool (SWAT) runs as a
	  daemon from <application>inetd</application>.  Therefore,
	  the following line in <filename>/etc/inetd.conf</filename>
	  should be uncommented before <application>swat</application>
	  can be used to configure
	  <application>Samba</application>:</para>

	<programlisting>swat   stream  tcp     nowait/400      root    /usr/local/sbin/swat    swat</programlisting>
	<para>As explained in <xref linkend="network-inetd-reread"/>,
	  the <application>inetd</application> configuration must be
	  reloaded after this configuration file is changed.</para>

	<para>Once <application>swat</application> has been enabled in
	  <filename>inetd.conf</filename>, you can use a browser to
	  connect to <ulink url="http://localhost:901"></ulink>.  You
	  will first have to log on with the system
	  <username>root</username> account.</para>

<!-- XXX screenshots go here, loader is creating them -->

	<para>Once you have successfully logged on to the main
	  <application>Samba</application> configuration page, you can
	  browse the system documentation, or begin by clicking on the
	  <guimenu>Globals</guimenu> tab.  The
	  <guimenu>Globals</guimenu> section corresponds to the
	  variables that are set in the <literal>[global]</literal>
	  section of
	  <filename>/usr/local/etc/smb.conf</filename>.</para>
      </sect3>

      <sect3>
	<title>Global Settings</title>

	<para>Whether you are using <application>swat</application> or
	  editing <filename>/usr/local/etc/smb.conf</filename>
	  directly, the first directives you are likely to encounter
	  when configuring <application>Samba</application>
	  are:</para>

	<variablelist>
	  <varlistentry>
	    <term><literal>workgroup</literal></term>

	    <listitem>
	      <para>NT Domain-Name or Workgroup-Name for the computers
		that will be accessing this server.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>netbios name</literal></term>

	    <listitem>
	      <para>This sets the NetBIOS name by which a
		<application>Samba</application> server is known.
		By default it is the same as the first component of
		the host's DNS name.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>server string</literal></term>

	    <listitem>
	      <para>This sets the string that will be displayed with
		the <command>net view</command> command and some other
		networking tools that seek to display descriptive text
		about the server.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>

      <sect3>
	<title>Security Settings</title>

	<para>Two of the most important settings in
	  <filename>/usr/local/etc/smb.conf</filename> are the
	  security model chosen, and the backend password format for
	  client users.  The following directives control these
	  options:</para>

	<variablelist>
	  <varlistentry>
	    <term><literal>security</literal></term>

	    <listitem>
	      <para>The two most common options here are
		<literal>security = share</literal> and
		<literal>security = user</literal>.  If your clients
		use usernames that are the same as their usernames on
		your &os; machine then you will want to use user level
		security.  This is the default security policy and it
		requires clients to first log on before they can
		access shared resources.</para>

	      <para>In share level security, client do not need to log
		onto the server with a valid username and password
		before attempting to connect to a shared resource.
		This was the default security model for older versions
		of <application>Samba</application>.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><literal>passdb backend</literal></term>

	    <listitem>
	      <indexterm><primary>NIS+</primary></indexterm>
	      <indexterm><primary>LDAP</primary></indexterm>
	      <indexterm><primary>SQL database</primary></indexterm>

	      <para><application>Samba</application> has several
		different backend authentication models.  You can
		authenticate clients with LDAP, NIS+, a SQL database,
		or a modified password file.  The default
		authentication method is <literal>smbpasswd</literal>,
		and that is all that will be covered here.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<para>Assuming that the default <literal>smbpasswd</literal>
	  backend is used, the
	  <filename>/usr/local/etc/samba/smbpasswd</filename> file
	  must be created to allow <application>Samba</application> to
	  authenticate clients.  If you would like to give
	  your &unix; user accounts access from &windows; clients, use
	  the following command:</para>

	<screen>&prompt.root; <userinput>smbpasswd -a username</userinput></screen>
	<note>
	  <para>The recommended backend is now
	    <literal>tdbsam</literal>, and the following command
	    should be used to add user accounts:</para>

	  <screen>&prompt.root; <userinput><command>pdbedit <option>-a</option> <option>-u</option> <replaceable>username</replaceable></command></userinput></screen>
	</note>

	<para>Please see the
	  <ulink
	    url="http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/">Official
	    Samba HOWTO</ulink>
	  for additional information about configuration
	  options.  With the basics outlined here, you should have
	  everything you need to start running
	  <application>Samba</application>.</para>
      </sect3>

    </sect2>
    <sect2>
      <title>Starting <application>Samba</application></title>

      <para>The <filename role="package">net/samba34</filename> port
	adds a new startup script, which can be used to control
	<application>Samba</application>.  To enable this script, so
	that it can be used for example to start, stop or restart
	<application>Samba</application>, add the following line to
	the <filename>/etc/rc.conf</filename> file:</para>

      <programlisting>samba_enable="YES"</programlisting>

      <para>Or, for fine grain control:</para>

      <programlisting>nmbd_enable="YES"</programlisting>
      <programlisting>smbd_enable="YES"</programlisting>

      <note>
	<para>This will also configure
	  <application>Samba</application> to automatically start at
	  system boot time.</para>
      </note>

      <para>It is possible then to start
	<application>Samba</application> at any time by typing:</para>

      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba start</userinput>
Starting SAMBA: removing stale tdbs :
Starting nmbd.
Starting smbd.</screen>

      <para>Please refer to <xref linkend="configtuning-rcd"/> for more
	information about using rc scripts.</para>

      <para><application>Samba</application> actually consists of
	three separate daemons.  You should see that both the
	<application>nmbd</application> and
	<application>smbd</application> daemons are started by the
	<filename>samba</filename> script.  If you enabled winbind
	name resolution services in <filename>smb.conf</filename>,
	then you will also see that the
	<application>winbindd</application> daemon is started.</para>

      <para>You can stop <application>Samba</application> at any time
	by typing :</para>

      <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba stop</userinput></screen>

      <para><application>Samba</application> is a complex software
	suite with functionality that allows broad integration with
	&microsoft.windows; networks.  For more information about
	functionality beyond the basic installation described here,
	please see <ulink url="http://www.samba.org"></ulink>.</para>
    </sect2>

  </sect1>

  <sect1 id="network-ntp">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Hukins</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>
    <title>Clock Synchronization with NTP</title>

    <indexterm><primary>NTP</primary></indexterm>

    <sect2>
      <title>Overview</title>

      <para>Over time, a computer's clock is prone to drift.  The
	Network Time Protocol (NTP) is one way to ensure your clock
	stays accurate.</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 been modified
	since a certain time.  In a local area network environment, it
	is essential that computers sharing files from the same file
	server have synchronized clocks so that file timestamps stay
	consistent.  Services such as &man.cron.8; also rely on
	an accurate system clock to run commands at the specified
	times.</para>

      <indexterm>
	<primary>NTP</primary>
	<secondary>ntpd</secondary>
      </indexterm>
      <para>FreeBSD ships with the &man.ntpd.8; <acronym
	  role="Network Time Protocol">NTP</acronym> server which can
	be used to query other <acronym
	  role="Network Time Protocol">NTP</acronym> 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 <acronym role="Network Time
	Protocol">NTP</acronym> servers to use.  Your network
	administrator or ISP may have set up an NTP server for this
	purpose&mdash;check their documentation to see if this is the
	case.  There is an <ulink
	url="http://support.ntp.org/bin/view/Servers/WebHome">online
	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;.  The &man.ntpd.8;
	  program 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
	  <literal>ntpdate_enable="YES"</literal> 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>
	<title>General Configuration</title>

	<indexterm>
	  <primary>NTP</primary>
	  <secondary>ntp.conf</secondary>
	</indexterm>

	<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.
	  The &man.ntpd.8; program 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 <filename>/etc/ntp.conf</filename> 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 following line to
	  <filename>/etc/ntp.conf</filename>:</para>

	<programlisting>restrict default ignore</programlisting>

	<note>
	  <para>This will also prevent access from your server to
	    any servers listed in your local configuration.  If you
	    need to synchronise your NTP server with an external NTP
	    server you should allow the specific server.  See the
	    &man.ntp.conf.5; manual for more information.</para>
	</note>

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

	<programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>

	<para>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 <literal>ntpd_enable="YES"</literal> to
	<filename>/etc/rc.conf</filename>.  If you wish to pass
	additional flags to &man.ntpd.8;, edit the
	<varname>ntpd_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>ntpd_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 <application>ntpd</application> with a Temporary
	Internet Connection</title>

      <para>The &man.ntpd.8; program 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="network-syslogd">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Tom</firstname>
	  <surname>Rhodes</surname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </sect1info>

    <title>Remote Host Logging with <command>syslogd</command></title>

    <para>Interacting with system logs is a crucial aspect of both
      security and system administration.  Monitoring the log files of
      multiple hosts can get very unwieldy when these hosts are
      distributed across medium or large networks, or when they are
      parts of various different types of networks.  In these cases,
      configuring remote logging may make the whole process a lot more
      comfortable.</para>

    <para>Centralized logging to a specific logging host can reduce
      some of the administrative burden of log file administration.
      Log file aggregation, merging and rotation can be configured in
      one location, using the native tools of &os;, such as
      &man.syslogd.8; and &man.newsyslog.8;.  In the following example
      configuration, host <hostid>A</hostid>, named <hostid
	role="fqdn">logserv.example.com</hostid>, will collect
      logging information for the local network.  Host
      <hostid>B</hostid>, named <hostid
	role="fqdn">logclient.example.com</hostid> will pass
      logging information to the server system.  In live
      configurations, both hosts require proper forward and reverse
      <acronym>DNS</acronym> or entries in
      <filename>/etc/hosts</filename>.  Otherwise, data will be
      rejected by the server.</para>

    <sect2>
      <title>Log Server Configuration</title>

      <para>Log servers are machines configured to accept logging
	information from remote hosts.  In most cases this is to ease
	configuration, in other cases it may just be a better
	administration move.  Regardless of reason, there are a few
	requirements before continuing.</para>

      <para>A properly configured logging server has met the following
	minimal requirements:</para>

      <itemizedlist>
	<listitem>
	  <para>The firewall ruleset allows for <acronym>UDP</acronym>
	    to be passed on port 514 on both the client and
	    server;</para>
	</listitem>

	<listitem>
	  <para>syslogd has been configured to accept remote messages
	    from client machines;</para>
	</listitem>

	<listitem>
	  <para>The syslogd server and all client machines must have
	    valid entries for both forward and reverse
	    <acronym>DNS</acronym>, or be properly configured in
	    <filename>/etc/hosts</filename>.</para>
	</listitem>
      </itemizedlist>

      <para>To configure the log server, the client must be listed
	in <filename>/etc/syslog.conf</filename>, and the logging
	facility must be specified:</para>

      <programlisting>+logclient.example.com
*.*     /var/log/logclient.log</programlisting>

      <note>
	<para>More information on various supported and available
	  <emphasis>facilities</emphasis> may be found in the
	  &man.syslog.conf.5; manual page.</para>
      </note>

      <para>Once added, all <literal>facility</literal> messages will
	be logged to the file specified previously,
	<filename>/var/log/logclient.log</filename>.</para>

      <para>The server machine must also have the following listing
	placed inside <filename>/etc/rc.conf</filename>:</para>

      <programlisting>syslogd_enable="YES"
syslogd_flags="-a logclient.example.com -v -v"</programlisting>

      <para>The first option will enable the
	<command>syslogd</command> daemon on boot up, and the second
	option allows data from the specified client to be accepted on
	this server.  The latter part, using <option>-v -v</option>,
	will increase the verbosity of logged messages.  This is
	extremely useful for tweaking facilities as administrators are
	able to see what type of messages are being logged under which
	facility.</para>

      <para>Multiple <option>-a</option> options may be specified to
	allow logging from multiple clients.  <acronym>IP</acronym>
	addresses and whole netblocks may also be specified, see the
	&man.syslog.3; manual page for a full list of possible
	options.</para>

      <para>Finally, the log file should be created.  The method used
	does not matter, but &man.touch.1; works great for situations
	such as this:</para>

      <screen>&prompt.root; <userinput>touch <filename>/var/log/logclient.log</filename></userinput></screen>

      <para>At this point, the <command>syslogd</command> daemon
	should be restarted and verified:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput>
&prompt.root; <userinput>pgrep syslog</userinput></screen>

      <para>If a <acronym>PID</acronym> is returned, the server has
	been restarted successfully, and client configuration may
	begin.  If the server has not restarted, consult the
	<filename>/var/log/messages</filename> log for any
	output.</para>
    </sect2>

    <sect2>
      <title>Log Client Configuration</title>

      <para>A logging client is a machine which sends log information
	to a logging server in addition to keeping local
	copies.</para>

      <para>Similar to log servers, clients must also meet a few
	minimum requirements:</para>

      <itemizedlist>
	<listitem>
	  <para>&man.syslogd.8; must be configured to send messages of
	    specific types to a log server, which must accept
	    them;</para>
	</listitem>

	<listitem>
	  <para>The firewall must allow <acronym>UDP</acronym> packets
	    through on port 514;</para>
	</listitem>

	<listitem>
	  <para>Both forward and reverse <acronym>DNS</acronym> must
	    be configured or have proper entries in the
	    <filename>/etc/hosts</filename>.</para>
	</listitem>
      </itemizedlist>

      <para>Client configuration is a bit more relaxed when compared
	to that of the servers.  The client machine must have the
	following listing placed inside
	<filename>/etc/rc.conf</filename>:</para>

      <programlisting>syslogd_enable="YES"
syslogd_flags="-s -v -v"</programlisting>

      <para>As before, these entries will enable the
	<command>syslogd</command> daemon on boot up, and increases
	the verbosity of logged messages.  The <option>-s</option>
	option prevents logs from being accepted by this client from
	other hosts.</para>

      <para>Facilities describe the system part for which a message
	is generated.  For an example, <acronym>ftp</acronym> and
	<acronym>ipfw</acronym> are both facilities.  When log
	messages are generated for those two services, they will
	normally include those two utilities in any log messages.
	Facilities are accompanied with a priority or level, which
	is used to mark how important a log message is.  The most
	common will be the <literal>warning</literal> and
	<literal>info</literal>.  Please refer to the &man.syslog.3;
	manual page for a full list of available facilities and
	priorities.</para>

      <para>The logging server must be defined in the client's
	<filename>/etc/syslog.conf</filename>.  In this instance,
	the <literal>@</literal> symbol is used to send logging
	data to a remote server and would look similar to the
	following entry:</para>

      <programlisting>*.*		@logserv.example.com</programlisting>

      <para>Once added, <command>syslogd</command> must be restarted
	for the changes to take effect:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput></screen>

      <para>To test that log messages are being sent across the
	network, use &man.logger.1; on the client to send a message to
	<command>syslogd</command>:</para>

      <screen>&prompt.root; <userinput>logger "<replaceable>Test message from logclient</replaceable>"</userinput></screen>

      <para>This message should now exist both in
	<filename>/var/log/messages</filename> on the client, and
	<filename>/var/log/logclient.log</filename> on the
	log server.</para>
    </sect2>

    <sect2>
      <title>Debugging Log Servers</title>

      <para>In certain cases, debugging may be required if messages
	are not being received on the log server.  There are several
	reasons this may occur; however, the most common two are
	network connection issues and <acronym>DNS</acronym> issues.
	To test these cases, ensure both hosts are able to reach one
	another using the hostname specified in
	<filename>/etc/rc.conf</filename>.  If this appears to be
	working properly, an alternation to the
	<literal>syslogd_flags</literal> option in
	<filename>/etc/rc.conf</filename> will be required.</para>

      <para>In the following example,
	<filename>/var/log/logclient.log</filename> is empty, and the
	<filename>/var/log/messages</filename> files indicate no
	reason for the failure.  To increase debugging output, change
	the <literal>syslogd_flags</literal> option to look like the
	following example, and issue a restart:</para>

      <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting>

      <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput></screen>

      <para>Debugging data similar to the following will flash on the
	screen immediately after the restart:</para>

      <screen>logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart
syslogd: restarted
logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel
Logging to FILE /var/log/messages
syslogd: kernel boot file is /boot/kernel/kernel
cvthname(192.168.1.10)
validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com;
rejected in rule 0 due to name mismatch.</screen>

      <para>It appears obvious the messages are being rejected due
	to a name mismatch.  After reviewing the configuration bit
	by bit, it appears a typo in the following
	<filename>/etc/rc.conf</filename> line has an issue:</para>

      <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting>

      <para>The line should contain <literal>logclient</literal>, not
	<literal>logclien</literal>.  After the proper alterations
	are made, a restart is issued with expected results:</para>

      <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput>
logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart
syslogd: restarted
logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel
syslogd: kernel boot file is /boot/kernel/kernel
logmsg: pri 166, flags 17, from logserv.example.com,
msg Dec 10 20:55:02 &lt;syslog.err&gt; logserv.example.com syslogd: exiting on signal 2
cvthname(192.168.1.10)
validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com;
accepted in rule 0.
logmsg: pri 15, flags 0, from logclient.example.com, msg Dec 11 02:01:28 trhodes: Test message 2
Logging to FILE /var/log/logclient.log
Logging to FILE /var/log/messages</screen>

      <para>At this point, the messages are being properly received
	and placed in the correct file.</para>
    </sect2>

    <sect2>
      <title>Security Considerations</title>

      <para>As with any network service, security requirements should
	be considered before implementing this configuration.  At
	times, log files may contain sensitive data about services
	enabled on the local host, user accounts, and configuration
	data.  Network data sent from the client to the server will
	not be encrypted nor password protected.  If a need for
	encryption exists, it might be possible to use
	<filename role="package">security/stunnel</filename>, which
	will transmit data over an encrypted tunnel.</para>

      <para>Local security is also an issue.  Log files are not
	encrypted during use or after log rotation.  Local users may
	access these files to gain additional insight on system
	configuration.  In those cases, setting proper permissions
	on these files will be critical.  The &man.newsyslog.8;
	utility supports setting permissions on newly created and
	rotated log files.  Setting log files to mode
	<literal>600</literal> should prevent any unwanted snooping
	by local users.</para>
    </sect2>
  </sect1>
</chapter>