Attachment 182399 Details for Bug 219142 – Diff file for the section "28.5. Lightweight Directory Access Protocol (LDAP)" of the handbook

[patch] Diff file for the section "28.5. Lightweight Directory Access Protocol (LDAP)" of the handbook

28-5_LDAP.diff (text/plain), 247.22 KB, created by Rocky Hotas on 2017-05-08 10:38:38 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Rocky Hotas

Created: 2017-05-08 10:38:38 UTC

Size: 247.22 KB

patch

obsolete

>Index: network-servers/chapter.xml
>===================================================================
>--- network-servers/chapter.xml	(revision 50234)
>+++ network-servers/chapter.xml	(working copy)
>@@ -1,5788 +1,6211 @@
> <?xml version="1.0" encoding="iso-8859-1"?>
> 
> <chapter xmlns="http://docbook.org/ns/docbook"
>   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
>   xml:id="network-servers">
>   
> 
>   <title>Network Servers</title>
> 
>   <sect1 xml:id="network-servers-synopsis">
>     <title>Synopsis</title>
> 
>     <para>This chapter covers some of the more frequently used network
>       services on &unix; systems.  This includes installing,
>       configuring, testing, and maintaining many different types of
>       network services.  Example configuration files are included
>       throughout this chapter for reference.</para>
> 
>     <para>By the end of this chapter, readers will know:</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para>How to manage the <application>inetd</application>
> 	  daemon.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up the Network File System
> 	  (<acronym>NFS</acronym>).</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up the Network Information Server
> 	  (<acronym>NIS</acronym>) for centralizing and sharing
> 	  user accounts.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set &os; up to act as an <acronym>LDAP</acronym>
> 	  server or client</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up automatic network settings using
> 	  <acronym>DHCP</acronym>.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up a Domain Name Server
> 	  (<acronym>DNS</acronym>).</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up the <application>Apache</application>
> 	  <acronym>HTTP</acronym> Server.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up a File Transfer Protocol
> 	  (<acronym>FTP</acronym>) 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 using the Network Time Protocol
> 	  (<acronym>NTP</acronym>).</para>
>       </listitem>
> 
>       <listitem>
> 	<para>How to set up <acronym>iSCSI</acronym>.</para>
>       </listitem>
>     </itemizedlist>
> 
>     <para>This chapter assumes a basic knowledge of:</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para><filename>/etc/rc</filename> scripts.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Network terminology.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Installation of additional third-party
> 	  software (<xref linkend="ports"/>).</para>
>       </listitem>
>     </itemizedlist>
>   </sect1>
> 
>   <sect1 xml:id="network-inetd">
>     <title>The <application>inetd</application>
>       Super-Server</title>
> 
>     
> 
>     <para>The &man.inetd.8; daemon is sometimes referred to as a
>       Super-Server because it manages connections for many services.
>       Instead of starting multiple applications, only the
>       <application>inetd</application> service needs to be started.
>       When a connection is received for a service that is managed by
>       <application>inetd</application>, it determines which program
>       the connection is destined for, spawns a process for that
>       program, and delegates the program a socket.  Using
>       <application>inetd</application> for services that are not
>       heavily used can reduce 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
>       internally, such as <application>chargen</application>,
>       <application>auth</application>,
>       <application>time</application>,
>       <application>echo</application>,
>       <application>discard</application>, and
>       <application>daytime</application>.</para>
> 
>     <para>This section covers the basics of configuring
>       <application>inetd</application>.</para>
> 
>     <sect2 xml:id="network-inetd-conf">
>       <title>Configuration File</title>
> 
>       <para>Configuration of <application>inetd</application> is
> 	done by editing <filename>/etc/inetd.conf</filename>.  Each
> 	line of this configuration file represents an application
> 	which can be started by <application>inetd</application>.  By
> 	default, every line starts with a comment
> 	(<literal>#</literal>), meaning that
> 	<application>inetd</application> is not listening for any
> 	applications.  To configure <application>inetd</application>
> 	to listen for an application's connections, remove the
> 	<literal>#</literal> at the beginning of the line for that
> 	application.</para>
> 
>       <para>After saving your edits, configure
> 	<application>inetd</application> to start at system boot by
> 	editing <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>inetd_enable="YES"</programlisting>
> 
>       <para>To start  <application>inetd</application> now, so that it
> 	listens for the service you configured, type:</para>
> 
>       <screen>&prompt.root; <userinput>service inetd start</userinput></screen>
> 
>       <para>Once <application>inetd</application> is started, it needs
> 	to be notified whenever a modification is made to
> 	<filename>/etc/inetd.conf</filename>:</para>
> 
>       <example xml:id="network-inetd-reread">
> 	<title>Reloading the <application>inetd</application>
> 	  Configuration File</title>
> 
> 	<screen>&prompt.root; <userinput>service inetd reload</userinput></screen>
>       </example>
> 
>       <para>Typically, the default entry for an application does not
> 	need to be edited beyond removing the <literal>#</literal>.
> 	In some situations, it may be appropriate to edit the default
> 	entry.</para>
> 
>       <para>As an example, this is the default entry for &man.ftpd.8;
> 	over IPv4:</para>
> 
>       <programlisting>ftp     stream  tcp     nowait  root    /usr/libexec/ftpd       ftpd -l</programlisting>
> 
>       <para>The seven columns in an entry are 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>where:</para>
> 
>       <variablelist>
> 	<varlistentry>
> 	  <term>service-name</term>
> 
> 	  <listitem>
> 	    <para>The service name of the daemon to start.  It must
> 	      correspond to a service listed in
> 	      <filename>/etc/services</filename>.  This determines
> 	      which port <application>inetd</application> listens on
> 	      for incoming connections to that service.  When using a
> 	      custom service, it must first be added to
> 	      <filename>/etc/services</filename>.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>socket-type</term>
> 
> 	  <listitem>
> 	    <para>Either <literal>stream</literal>,
> 	      <literal>dgram</literal>, <literal>raw</literal>, or
> 	      <literal>seqpacket</literal>.  Use
> 	      <literal>stream</literal> for TCP connections and
> 	      <literal>dgram</literal> for
> 	      <acronym>UDP</acronym> services.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>protocol</term>
> 
> 	  <listitem>
> 	    <para>Use one of the following protocol names:</para>
> 
> 	    <informaltable frame="none" pgwide="1">
> 	      <tgroup cols="2">
> 		<thead>
> 		  <row>
> 		    <entry>Protocol Name</entry>
> 		    <entry>Explanation</entry>
> 		  </row>
> 		</thead>
> 
> 		<tbody>
> 		  <row>
> 		    <entry>tcp or tcp4</entry>
> 		    <entry>TCP IPv4</entry>
> 		  </row>
> 
> 		  <row>
> 		    <entry>udp or udp4</entry>
> 		    <entry><acronym>UDP</acronym> IPv4</entry>
> 		  </row>
> 
> 		  <row>
> 		    <entry>tcp6</entry>
> 		    <entry>TCP IPv6</entry>
> 		  </row>
> 
> 		  <row>
> 		    <entry>udp6</entry>
> 		    <entry><acronym>UDP</acronym> IPv6</entry>
> 		  </row>
> 
> 		  <row>
> 		    <entry>tcp46</entry>
> 		    <entry>Both TCP IPv4 and IPv6</entry>
> 		  </row>
> 
> 		  <row>
> 		    <entry>udp46</entry>
> 		    <entry>Both <acronym>UDP</acronym> IPv4 and
> 		      IPv6</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>In this field, <option>wait</option> or
> 	      <option>nowait</option> must be specified.
> 	      <option>max-child</option>,
> 	      <option>max-connections-per-ip-per-minute</option> and
> 	      <option>max-child-per-ip</option> are optional.</para>
> 
> 	    <para><option>wait|nowait</option> indicates whether or
> 	      not the service is able to handle its own socket.
> 	      <option>dgram</option> socket types must use
> 	      <option>wait</option> while
> 	      <option>stream</option> 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 is set by
> 	      <option>max-child</option>.  For example, to limit ten
> 	      instances of the daemon, place a <literal>/10</literal>
> 	      after <option>nowait</option>.  Specifying
> 	      <literal>/0</literal> allows an unlimited number of
> 	      children.</para>
> 
> 	    <para><option>max-connections-per-ip-per-minute</option>
> 	      limits the number of connections from any particular
> 	      <acronym>IP</acronym> address per minute.  Once the
> 	      limit  is reached, further connections from this IP
> 	      address will be dropped until the end of the minute.
> 	      For example, a value of <literal>/10</literal> would
> 	      limit any particular <acronym>IP</acronym> address to
> 	      ten connection attempts per minute.
> 	      <option>max-child-per-ip</option> limits the number of
> 	      child processes that can be started on behalf on any
> 	      single <acronym>IP</acronym> address at any moment.
> 	      These options can limit excessive resource consumption
> 	      and help to prevent Denial of Service attacks.</para>
> 
> 	    <para>An example can be seen in the default settings for
> 	      &man.fingerd.8;:</para>
> 
> 	    <programlisting>finger stream  tcp     nowait/3/10 nobody /usr/libexec/fingerd fingerd -k -s</programlisting>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>user</term>
> 
> 	  <listitem>
> 	    <para>The username the daemon
> 	      will run as.  Daemons typically run as
> 	      <systemitem class="username">root</systemitem>,
> 	      <systemitem class="username">daemon</systemitem>, or
> 	      <systemitem class="username">nobody</systemitem>.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>server-program</term>
> 
> 	  <listitem>
> 	    <para>The full path to the daemon.  If the daemon is a
> 	      service provided by <application>inetd</application>
> 	      internally, use <option>internal</option>.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>server-program-arguments</term>
> 
> 	  <listitem>
> 	    <para>Used to specify any command arguments to be passed
> 	      to the daemon on invocation.  If the daemon is an
> 	      internal service, use
> 	      <option>internal</option>.</para>
> 	  </listitem>
> 	</varlistentry>
>       </variablelist>
>     </sect2>
> 
>     <sect2 xml:id="network-inetd-cmdline">
>       <title>Command-Line Options</title>
> 
>       <para>Like most server daemons, <application>inetd</application>
> 	has a number of options that can be used to modify its
> 	behavior.  By default, <application>inetd</application> is
> 	started with <literal>-wW -C 60</literal>.  These options
> 	enable TCP wrappers for all services, including internal
> 	services, and prevent any <acronym>IP</acronym> address from
> 	requesting any service more than 60 times per minute.</para>
> 
>       <para>To change the default options which are passed to
> 	<application>inetd</application>, add an entry for
> 	<literal>inetd_flags</literal> in
> 	<filename>/etc/rc.conf</filename>.  If
> 	<application>inetd</application> is already running, restart
> 	it with <command>service inetd restart</command>.</para>
> 
>       <para>The available rate limiting options are:</para>
> 
>       <variablelist>
> 	<varlistentry>
> 	  <term>-c maximum</term>
> 
> 	  <listitem>
> 	    <para>Specify the default maximum number of simultaneous
> 	      invocations of each service, where the default is
> 	      unlimited.  May be overridden on a per-service basis by
> 	      using <option>max-child</option> in
> 	      <filename>/etc/inetd.conf</filename>.</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
> 	      <acronym>IP</acronym> address per minute.  May be
> 	      overridden on a per-service basis by using
> 	      <option>max-connections-per-ip-per-minute</option> in
> 	      <filename>/etc/inetd.conf</filename>.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>-R rate</term>
> 
> 	  <listitem>
> 	    <para>Specify the maximum number of times a service can be
> 	      invoked in one minute, where the default is
> 	      <literal>256</literal>.  A rate of <literal>0</literal>
> 	      allows an unlimited number.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term>-s maximum</term>
> 
> 	  <listitem>
> 	    <para>Specify the maximum number of times a service can be
> 	      invoked from a single <acronym>IP</acronym> address at
> 	      any one time, where the default is unlimited.  May be
> 	      overridden on a per-service basis by using
> 	      <option>max-child-per-ip</option> in
> 	      <filename>/etc/inetd.conf</filename>.</para>
> 	  </listitem>
> 	</varlistentry>
>       </variablelist>
> 
>       <para>Additional options are available.  Refer to &man.inetd.8;
> 	for the full list of options.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-inetd-security">
>       <title>Security Considerations</title>
> 
>       <para>Many of the daemons which can be managed by
> 	<application>inetd</application> are not security-conscious.
> 	Some daemons, such as <application>fingerd</application>, can
> 	provide information that may be useful to an attacker.  Only
> 	enable the services which are needed and monitor the system
> 	for excessive connection attempts.
> 	<literal>max-connections-per-ip-per-minute</literal>,
> 	<literal>max-child</literal> and
> 	<literal>max-child-per-ip</literal> can be used to limit such
> 	attacks.</para>
> 
>       <para>By default, TCP wrappers is enabled.  Consult
> 	&man.hosts.access.5; for more information on placing TCP
> 	restrictions on various
> 	<application>inetd</application> invoked daemons.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-nfs">
>     <info>
>       <title>Network File System (NFS)</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Tom</firstname>
> 	    <surname>Rhodes</surname>
> 	  </personname>
> 	  <contrib>Reorganized and enhanced by </contrib>
> 	</author>
>       </authorgroup>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Bill</firstname>
> 	    <surname>Swingle</surname>
> 	  </personname>
> 	  <contrib>Written by </contrib>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm><primary>NFS</primary></indexterm>
>     <para>&os; supports the Network File System
>       (<acronym>NFS</acronym>), which allows a server to share
>       directories and files with clients over a network.  With
>       <acronym>NFS</acronym>, users and programs can access files on
>       remote systems as if they were stored locally.</para>
> 
>     <para><acronym>NFS</acronym> has many practical uses.  Some of
>       the more common uses include:</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para>Data that would otherwise be duplicated on each client
> 	  can be kept in a single location and accessed by clients
> 	  on the network.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Several clients may need access to the
> 	  <filename>/usr/ports/distfiles</filename> directory.
> 	  Sharing that directory allows for quick access to the
> 	  source files without having to download them to each
> 	  client.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>On large networks, it is often more convenient to
> 	  configure a central <acronym>NFS</acronym> server on which
> 	  all user home directories are stored.  Users can log into
> 	  a client anywhere on the network and have access to their
> 	  home directories.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Administration of <acronym>NFS</acronym> exports is
> 	  simplified.  For example, there is only one file system
> 	  where security or backup policies must be set.</para>
>       </listitem>
> 
>       <listitem>
> 	<para>Removable media storage devices can be used by other
> 	  machines on the network.  This reduces the number of devices
> 	  throughout the network and provides a centralized location
> 	  to manage their security.  It is often more convenient to
> 	  install software on multiple machines from a centralized
> 	  installation media.</para>
>       </listitem>
>     </itemizedlist>
> 
>     <para><acronym>NFS</acronym> consists of 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>These daemons must be running on the server:</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 <acronym>NFS</acronym> clients.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><application>mountd</application></entry>
> 	      <entry>The <acronym>NFS</acronym> mount daemon which
> 		carries out requests received from
> 		<application>nfsd</application>.</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>Running &man.nfsiod.8; on the client can improve
> 	performance, but is not required.</para>
> 
>       <sect2 xml:id="network-configuring-nfs">
> 	<title>Configuring the Server</title>
> 
> 	<indexterm>
> 	  <primary>NFS</primary>
> 	  <secondary>configuration</secondary>
> 	</indexterm>
> 
>       <para>The file systems which the <acronym>NFS</acronym> server
> 	will share are specified in <filename>/etc/exports</filename>.
> 	Each line in this file specifies a file system to be exported,
> 	which clients have access to that file system, and any access
> 	options.  When adding entries to this file, each exported file
> 	system, its properties, and allowed hosts must occur on a
> 	single line.  If no clients are listed in the entry, then any
> 	client on the network can mount that file system.</para>
> 
>       <indexterm>
> 	<primary>NFS</primary>
> 	<secondary>export examples</secondary>
>       </indexterm>
> 
>       <para>The following <filename>/etc/exports</filename> entries
> 	demonstrate how to export file systems.  The examples can be
> 	modified to match the file systems and client names on the
> 	reader's network.  There are many options that can be used in
> 	this file, but only a few will be mentioned here.  See
> 	&man.exports.5; for the full list of options.</para>
> 
>       <para>This example shows how to export
> 	<filename>/cdrom</filename> to three hosts named
> 	<replaceable>alpha</replaceable>,
> 	<replaceable>bravo</replaceable>, and
> 	<replaceable>charlie</replaceable>:</para>
> 
>       <programlisting>/cdrom -ro <replaceable>alpha</replaceable> <replaceable>bravo</replaceable> <replaceable>charlie</replaceable></programlisting>
> 
>       <para>The <literal>-ro</literal> flag makes the file system
> 	read-only, preventing clients from making any changes to the
> 	exported file system.  This example assumes that the host
> 	names are either in <acronym>DNS</acronym> or in
> 	<filename>/etc/hosts</filename>.  Refer to &man.hosts.5; if
> 	the network does not have a <acronym>DNS</acronym>
> 	server.</para>
> 
>       <para>The next example exports <filename>/home</filename> to
> 	three clients by <acronym>IP</acronym> address.  This can be
> 	useful for networks without <acronym>DNS</acronym> or
> 	<filename>/etc/hosts</filename> entries.  The
> 	<literal>-alldirs</literal> flag allows subdirectories to be
> 	mount points.  In other words, it will not automatically mount
> 	the subdirectories, but will permit the client to mount the
> 	directories that are required as needed.</para>
> 
>       <programlisting>/usr/home  -alldirs  10.0.0.2 10.0.0.3 10.0.0.4</programlisting>
> 
>       <para>This next example exports <filename>/a</filename> so that
> 	two clients from different domains may access that file
> 	system.  The <option>-maproot=root</option> allows <systemitem
> 	  class="username">root</systemitem> on the remote system to
> 	write data on the exported file system as <systemitem
> 	  class="username">root</systemitem>.  If
> 	<literal>-maproot=root</literal> is not specified, the
> 	client's <systemitem class="username">root</systemitem> user
> 	will be mapped to the server's <systemitem
> 	  class="username">nobody</systemitem> account and will be
> 	subject to the access limitations defined for <systemitem
> 	  class="username">nobody</systemitem>.</para>
> 
>       <programlisting>/a  -maproot=root  host.example.com box.example.org</programlisting>
> 
>       <para>A client can only be specified once per file system.  For
> 	example, if <filename>/usr</filename> is a single file system,
> 	these entries would be invalid as both entries specify the
> 	same host:</para>
> 
>       <programlisting># Invalid when /usr is one file system
> /usr/src   client
> /usr/ports client</programlisting>
> 
>       <para>The correct format for this situation is to use one
> 	entry:</para>
> 
>       <programlisting>/usr/src /usr/ports  client</programlisting>
> 
>       <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>To enable the processes required by the
> 	<acronym>NFS</acronym> server at boot time, add these options
> 	to <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>rpcbind_enable="YES"
> nfs_server_enable="YES"
> mountd_flags="-r"</programlisting>
> 
>       <para>The server can be started now by running this
> 	command:</para>
> 
>       <screen>&prompt.root; <userinput>service nfsd start</userinput></screen>
> 
>       <para>Whenever the <acronym>NFS</acronym> server is started,
> 	<application>mountd</application> also starts automatically.
> 	However, <application>mountd</application> only reads
> 	<filename>/etc/exports</filename> when it is started.  To make
> 	subsequent <filename>/etc/exports</filename> edits take effect
> 	immediately, force <application>mountd</application> to reread
> 	it:</para>
> 
>       <screen>&prompt.root; <userinput>service mountd reload</userinput></screen>
>     </sect2>
> 
>     <sect2>
>       <title>Configuring the Client</title>
> 
>       <para>To enable <acronym>NFS</acronym> clients, set this option
> 	in each client's <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>nfs_client_enable="YES"</programlisting>
> 
>       <para>Then, run this command on each <acronym>NFS</acronym>
> 	client:</para>
> 
>       <screen>&prompt.root; <userinput>service nfsclient start</userinput></screen>
> 
>       <para>The client now has everything it needs to mount a remote
> 	file system.  In these examples, the server's name is
> 	<systemitem>server</systemitem> and the client's name is
> 	<systemitem>client</systemitem>.  To mount
> 	<filename>/home</filename> on
> 	<systemitem>server</systemitem> to the
> 	<filename>/mnt</filename> mount point on
> 	<systemitem>client</systemitem>:</para>
> 
>       <indexterm>
> 	<primary>NFS</primary>
> 	<secondary>mounting</secondary>
>       </indexterm>
>       <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen>
> 
>       <para>The files and directories in
> 	<filename>/home</filename> will now be available on
> 	<systemitem>client</systemitem>, in the
> 	<filename>/mnt</filename> directory.</para>
> 
>       <para>To mount a remote file system each time the client boots,
> 	add it to <filename>/etc/fstab</filename>:</para>
> 
>       <programlisting>server:/home	/mnt	nfs	rw	0	0</programlisting>
> 
>       <para>Refer to &man.fstab.5; for a description of all available
> 	options.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Locking</title>
> 
>       <para>Some applications require file locking to operate
> 	correctly.  To enable locking, add these lines to
> 	<filename>/etc/rc.conf</filename> on both the client and
> 	server:</para>
> 
>       <programlisting>rpc_lockd_enable="YES"
> rpc_statd_enable="YES"</programlisting>
> 
>       <para>Then start the applications:</para>
> 
>       <screen>&prompt.root; <userinput>service lockd start</userinput>
> &prompt.root; <userinput>service statd start</userinput></screen>
> 
>       <para>If locking is not required on the server, the
> 	<acronym>NFS</acronym> client can be configured to lock
> 	locally by including <option>-L</option> when running
> 	<application>mount</application>.  Refer to &man.mount.nfs.8;
> 	for further details.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-amd">
>       <info>
> 	<title>Automating Mounts with &man.amd.8;</title>
> 
> 	<authorgroup>
> 	  <author>
> 	    <personname>
> 	      <firstname>Wylie</firstname>
> 	      <surname>Stilwell</surname>
> 	    </personname>
> 	    <contrib>Contributed by </contrib>
> 	  </author>
> 	</authorgroup>
> 
> 	<authorgroup>
> 	  <author>
> 	    <personname>
> 	      <firstname>Chern</firstname>
> 	      <surname>Lee</surname>
> 	    </personname>
> 	    <contrib>Rewritten by </contrib>
> 	  </author>
> 	</authorgroup>
>       </info>
> 
>       <indexterm><primary>amd</primary></indexterm>
>       <indexterm>
> 	<primary>automatic mounter daemon</primary>
>       </indexterm>
> 
>       <para>The automatic mounter daemon,
> 	<application>amd</application>, automatically mounts a remote
> 	file system whenever a file or directory within that file
> 	system is accessed.  File systems that are inactive for a
> 	period of time will be automatically unmounted by
> 	<application>amd</application>.</para>
> 
>       <para>This daemon provides an alternative to modifying
> 	<filename>/etc/fstab</filename> to list every client.  It
> 	operates by attaching itself as an  <acronym>NFS</acronym>
> 	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 <acronym>IP</acronym> address while
> 	<filename>/host</filename> is used to mount an export from a
> 	remote hostname.  For instance, an attempt to access a file
> 	within <filename>/host/foobar/usr</filename> would tell
> 	<application>amd</application> to mount the
> 	<filename>/usr</filename> export on the host
> 	<systemitem>foobar</systemitem>.</para>
> 
>       <example>
> 	<title>Mounting an Export with
> 	  <application>amd</application></title>
> 
> 	<para>In this example, <command>showmount -e</command> shows
> 	  the exported file systems that can be mounted from the
> 	  <acronym>NFS</acronym> server,
> 	  <systemitem>foobar</systemitem>:</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>The output from <command>showmount</command> shows
> 	<filename>/usr</filename> as an export.  When changing
> 	directories to <filename>/host/foobar/usr</filename>,
> 	<application>amd</application> intercepts the request and
> 	attempts to resolve the hostname
> 	<systemitem>foobar</systemitem>.  If successful,
> 	<application>amd</application> automatically mounts the
> 	desired export.</para>
> 
>       <para>To enable <application>amd</application> at boot time, add
> 	this line to <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>amd_enable="YES"</programlisting>
> 
>       <para>To start <application>amd</application> now:</para>
> 
>       <screen>&prompt.root; <userinput>service amd start</userinput></screen>
> 
>       <para>Custom flags can be passed to
> 	<application>amd</application> from the
> 	<varname>amd_flags</varname> environment variable.  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 default options with which exports are mounted are
> 	defined in <filename>/etc/amd.map</filename>.  Some of the
> 	more advanced features of <application>amd</application> are
> 	defined in <filename>/etc/amd.conf</filename>.</para>
> 
>       <para>Consult &man.amd.8; and &man.amd.conf.5; for more
> 	information.</para>
>     </sect2>
> 
>     <sect2 xml:id="network-autofs">
>       <title>Automating Mounts with &man.autofs.5;</title>
> 
>       <note>
> 	<para>The &man.autofs.5; automount facility is supported
> 	  starting with &os;&nbsp;10.1-RELEASE.  To use the
> 	  automounter functionality in older versions of &os;, use
> 	  &man.amd.8; instead.  This chapter only describes the
> 	  &man.autofs.5; automounter.</para>
>       </note>
> 
> 
>       <indexterm><primary>autofs</primary></indexterm>
>       <indexterm>
> 	<primary>automounter subsystem</primary>
>       </indexterm>
> 
>       <para>The &man.autofs.5; facility is a common name for several
> 	components that, together, allow for automatic mounting of
> 	remote and local filesystems whenever a file or directory
> 	within that file system is accessed.  It consists of the
> 	kernel component, &man.autofs.5;, and several userspace
> 	applications: &man.automount.8;, &man.automountd.8; and
> 	&man.autounmountd.8;.  It serves as an alternative for
> 	&man.amd.8; from previous &os; releases.  Amd is still
> 	provided for backward compatibility purposes, as the two use
> 	different map format; the one used by autofs is the same as
> 	with other SVR4 automounters, such as the ones in Solaris,
> 	MacOS X, and Linux.</para>
> 
>       <para>The &man.autofs.5; virtual filesystem is mounted on
> 	specified mountpoints by &man.automount.8;, usually invoked
> 	during boot.</para>
> 
>       <para>Whenever a process attempts to access file within the
> 	&man.autofs.5; mountpoint, the kernel will notify
> 	&man.automountd.8; daemon and pause the triggering process.
> 	The &man.automountd.8; daemon will handle kernel requests by
> 	finding the proper map and mounting the filesystem according
> 	to it, then signal the kernel to release blocked process.  The
> 	&man.autounmountd.8; daemon automatically unmounts automounted
> 	filesystems after some time, unless they are still being
> 	used.</para>
> 
>       <para>The primary autofs configuration file is
> 	<filename>/etc/auto_master</filename>.  It assigns individual
> 	maps to top-level mounts.  For an explanation of
> 	<filename>auto_master</filename> and the map syntax, refer to
> 	&man.auto.master.5;.</para>
> 
>       <para>There is a special automounter map mounted on
> 	<filename>/net</filename>.  When a file is accessed within
> 	this directory, &man.autofs.5; looks up the corresponding
> 	remote mount and automatically mounts it.  For instance, an
> 	attempt to access a file within
> 	<filename>/net/foobar/usr</filename> would tell
> 	&man.automountd.8; to mount the <filename
> 	  >/usr</filename> export from the host
> 	<systemitem class="fqdomainname">foobar</systemitem>.</para>
> 
>       <example>
> 	<title>Mounting an Export with &man.autofs.5;</title>
> 
> 	<para>In this example, <command>showmount -e</command> shows
> 	  the exported file systems that can be mounted from the
> 	  <acronym>NFS</acronym> server,
> 	  <systemitem class="fqdomainname">foobar</systemitem>:</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 /net/foobar/usr</userinput></screen>
>       </example>
> 
>       <para>The output from <command>showmount</command> shows
> 	<filename>/usr</filename> as an export.
> 	When changing directories to <filename
> 	  >/host/foobar/usr</filename>,
> 	&man.automountd.8; intercepts the request and attempts to
> 	resolve the hostname <systemitem
> 	  class="fqdomainname">foobar</systemitem>.  If successful,
> 	&man.automountd.8; automatically mounts the source
> 	export.</para>
> 
>       <para>To enable &man.autofs.5; at boot time, add this line to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>autofs_enable="YES"</programlisting>
> 
>       <para>Then &man.autofs.5; can be started by running:</para>
> 
>       <screen>&prompt.root; <userinput>service automount start</userinput>
> &prompt.root; <userinput>service automountd start</userinput>
> &prompt.root; <userinput>service autounmountd start</userinput></screen>
> 
>       <para>The &man.autofs.5; map format is the same as in other
>-	operating systems.  Information about this format from other
>-	 sources can be useful, like the <link
>-	  xlink:href="http://web.archive.org/web/20160813071113/http://images.apple.com/business/docs/Autofs.pdf">Mac
>+	operating systems, it might be desirable to consult
>+	information from other operating systems, such as the <link
>+	  xlink:href="http://images.apple.com/business/docs/Autofs.pdf">Mac
> 	  OS X document</link>.</para>
> 
>       <para>Consult the &man.automount.8;, &man.automountd.8;,
> 	&man.autounmountd.8;, and &man.auto.master.5; manual pages for
> 	more information.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-nis">
>     
>     <title>Network Information System
>       (<acronym>NIS</acronym>)</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>
>     <indexterm>
>       <primary>yellow pages</primary>
>       <see>NIS</see>
>     </indexterm>
> 
>     <para>Network Information System (<acronym>NIS</acronym>) is
>       designed to centralize administration of &unix;-like systems
>       such as &solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, and
>       &os;.  <acronym>NIS</acronym> was originally known as Yellow
>       Pages but the name was changed due to trademark issues.   This
>       is the reason why <acronym>NIS</acronym> commands begin with
>       <literal>yp</literal>.</para>
> 
>     <indexterm>
>       <primary>NIS</primary>
>       <secondary>domains</secondary>
>       </indexterm>
> 
>     <para><acronym>NIS</acronym> is a Remote Procedure Call
>       (<acronym>RPC</acronym>)-based client/server system that allows
>       a group of machines within an <acronym>NIS</acronym> domain to
>       share a common set of configuration files.  This permits a
>       system administrator to set up <acronym>NIS</acronym> client
>       systems with only minimal configuration data and to add, remove,
>       or modify configuration data from a single location.</para>
> 
>     <para>&os; uses version 2 of the <acronym>NIS</acronym>
>       protocol.</para>
> 
>     <sect2>
>       <title><acronym>NIS</acronym> Terms and Processes</title>
> 
>       <para>Table 28.1 summarizes the terms and important processes
> 	used by <acronym>NIS</acronym>:</para>
> 
>       <indexterm>
> 	<primary><application>rpcbind</application></primary>
>       </indexterm>
>       <indexterm>
> 	<primary><application>portmap</application></primary>
>       </indexterm>
> 
>       <table frame="none" pgwide="1">
> 	<title><acronym>NIS</acronym> Terminology</title>
> 
> 	<tgroup cols="2">
> 	  <colspec colwidth="1*"/>
> 	  <colspec colwidth="3*"/>
> 
> 	  <thead>
> 	    <row>
> 	      <entry>Term</entry>
> 	      <entry>Description</entry>
> 	    </row>
> 	  </thead>
> 
> 	  <tbody>
> 	    <row>
> 	      <entry><acronym>NIS</acronym> domain name</entry>
> 
> 	      <entry><acronym>NIS</acronym> servers and clients share
> 		an <acronym>NIS</acronym> domain name.  Typically,
> 		this name does not have anything to do with
> 		<acronym>DNS</acronym>.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry>&man.rpcbind.8;</entry>
> 
> 	      <entry>This service enables <acronym>RPC</acronym> and
> 		must be running in order to run an
> 		<acronym>NIS</acronym> server or act as an
> 		<acronym>NIS</acronym> client.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry>&man.ypbind.8;</entry>
> 	      <entry>This service binds an <acronym>NIS</acronym>
> 		client to its <acronym>NIS</acronym> server.  It will
> 		take the <acronym>NIS</acronym> domain name and use
> 		<acronym>RPC</acronym> to connect to the server.  It
> 		is the core of client/server communication in an
> 		<acronym>NIS</acronym> environment.  If this service
> 		is not running on a client machine, it will not be
> 		able to access the <acronym>NIS</acronym>
> 		server.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry>&man.ypserv.8;</entry>
> 	      <entry>This is the process for the
> 		<acronym>NIS</acronym> server.  If this service stops
> 		running, the server will no longer be able to respond
> 		to <acronym>NIS</acronym> requests so hopefully, there
> 		is a slave server to take over.  Some non-&os; clients
> 		will not try to reconnect using a slave server and the
> 		<application>ypbind</application> process may need to
> 		be restarted on these
> 		clients.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry>&man.rpc.yppasswdd.8;</entry>
> 	      <entry>This process only runs on
> 		<acronym>NIS</acronym> master servers.  This daemon
> 		allows <acronym>NIS</acronym> clients to change their
> 		<acronym>NIS</acronym> passwords.  If this daemon is
> 		not running, users will have to login to the
> 		<acronym>NIS</acronym> master server and change their
> 		passwords there.</entry>
> 	    </row>
> 	  </tbody>
> 	</tgroup>
>       </table>
>       
>     </sect2>
> 
>     <sect2>
>       <title>Machine Types</title>
> 
>       <indexterm><primary>NIS</primary>
> 	<secondary>master server</secondary>
>       </indexterm>
>       <indexterm><primary>NIS</primary>
> 	<secondary>slave server</secondary>
>       </indexterm>
>       <indexterm><primary>NIS</primary>
> 	<secondary>client</secondary>
>       </indexterm>
> 
>       <para>There are three types of hosts in an
> 	<acronym>NIS</acronym> environment:</para>
> 
>       <itemizedlist>
> 	<listitem>
> 	  <para><acronym>NIS</acronym> master server</para>
> 
> 	  <para>This server acts as a central repository for host
> 	    configuration information and maintains the
> 	    authoritative copy of the files used by all of the
> 	    <acronym>NIS</acronym> clients.  The
> 	    <filename>passwd</filename>, <filename>group</filename>,
> 	    and other various files used by <acronym>NIS</acronym>
> 	    clients are stored on the master server.  While it is
> 	    possible for one machine to be an <acronym>NIS</acronym>
> 	    master server for more than one <acronym>NIS</acronym>
> 	    domain, this type of configuration will not be covered in
> 	    this chapter as it assumes a relatively small-scale
> 	    <acronym>NIS</acronym> environment.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><acronym>NIS</acronym> slave servers</para>
> 
> 	  <para><acronym>NIS</acronym> slave servers maintain copies
> 	    of the <acronym>NIS</acronym> master's data files in
> 	    order to provide redundancy.  Slave servers also help to
> 	    balance the load of the master server as
> 	    <acronym>NIS</acronym> clients always attach to the
> 	    <acronym>NIS</acronym> server which responds
> 	    first.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><acronym>NIS</acronym> clients</para>
> 
> 	  <para><acronym>NIS</acronym> clients authenticate
> 	    against the <acronym>NIS</acronym> server during log
> 	    on.</para>
> 	</listitem>
>       </itemizedlist>
> 
>       <para>Information in many files can be shared using
> 	<acronym>NIS</acronym>.  The
> 	<filename>master.passwd</filename>,
> 	<filename>group</filename>, and <filename>hosts</filename>
> 	files are commonly shared via <acronym>NIS</acronym>.
> 	Whenever a process on a client needs information that would
> 	normally be found in these files locally, it makes a query to
> 	the <acronym>NIS</acronym> server that it is bound to
> 	instead.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Planning Considerations</title>
> 
>       <para>This section describes a sample <acronym>NIS</acronym>
> 	environment which consists of 15 &os; machines with 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 a user is added to the lab, the process must
> 	be repeated on all 15 machines.</para>
> 
>       <para>The configuration of the lab will be as follows:</para>
> 
>       <informaltable frame="none" pgwide="1">
> 	<tgroup cols="3">
> 	  <thead>
> 	    <row>
> 	      <entry>Machine name</entry>
> 	      <entry><acronym>IP</acronym> address</entry>
> 	      <entry>Machine role</entry>
> 	    </row>
> 	  </thead>
> 
> 	  <tbody>
> 	    <row>
> 	      <entry><systemitem>ellington</systemitem></entry>
> 	      <entry><systemitem
> 		  class="ipaddress">10.0.0.2</systemitem></entry>
> 	      <entry><acronym>NIS</acronym> master</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>coltrane</systemitem></entry>
> 	      <entry><systemitem
> 		  class="ipaddress">10.0.0.3</systemitem></entry>
> 	      <entry><acronym>NIS</acronym> slave</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>basie</systemitem></entry>
> 	      <entry><systemitem
> 		  class="ipaddress">10.0.0.4</systemitem></entry>
> 	      <entry>Faculty workstation</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>bird</systemitem></entry>
> 	      <entry><systemitem
> 		  class="ipaddress">10.0.0.5</systemitem></entry>
> 	      <entry>Client machine</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>cli[1-11]</systemitem></entry>
> 	      <entry>
> 		<systemitem
> 		  class="ipaddress">10.0.0.[6-17]</systemitem></entry>
> 	      <entry>Other client machines</entry>
> 	    </row>
> 	  </tbody>
> 	</tgroup>
>       </informaltable>
> 
>       <para>If this is the first time an <acronym>NIS</acronym>
> 	scheme is being developed, it should be thoroughly planned
> 	ahead of time.  Regardless of network size, several decisions
> 	need to be made as part of the planning process.</para>
> 
>       <sect3>
> 	<title>Choosing a <acronym>NIS</acronym> Domain Name</title>
> 
> 	<indexterm>
> 	  <primary>NIS</primary>
> 	  <secondary>domain name</secondary>
> 	</indexterm>
> 	<para>When a client broadcasts its requests for info, it
> 	  includes the name of the <acronym>NIS</acronym> 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 <acronym>NIS</acronym> domain name as the name for a
> 	  group of hosts.</para>
> 
> 	<para>Some organizations choose to use their Internet domain
> 	  name for their <acronym>NIS</acronym> domain name.  This is
> 	  not recommended as it can cause confusion when trying to
> 	  debug network problems.  The <acronym>NIS</acronym> domain
> 	  name should be unique within the 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> <acronym>NIS</acronym> domain.  This
> 	  example will use the domain name
> 	  <literal>test-domain</literal>.</para>
> 
> 	<para>However, some non-&os; operating systems require the
> 	  <acronym>NIS</acronym> domain name to be the same as the
> 	  Internet domain name.  If one or more machines on the
> 	  network have this restriction, the Internet domain name
> 	  <emphasis>must</emphasis> be used as the
> 	  <acronym>NIS</acronym> domain name.</para>
>       </sect3>
> 
>       <sect3>
> 	<title>Physical Server Requirements</title>
> 
> 	<para>There are several things to keep in mind when choosing a
> 	  machine to use as a <acronym>NIS</acronym> server.  Since
> 	  <acronym>NIS</acronym> clients depend upon the availability
> 	  of the server, choose a machine that is not rebooted
> 	  frequently.  The <acronym>NIS</acronym> server should
> 	  ideally be a stand alone machine whose sole purpose is to be
> 	  an <acronym>NIS</acronym> server.  If the network is not
> 	  heavily used, it is acceptable to put the
> 	  <acronym>NIS</acronym> server on a machine running other
> 	  services.  However, if the <acronym>NIS</acronym> server
> 	  becomes unavailable, it will adversely affect all
> 	  <acronym>NIS</acronym> clients.</para>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Configuring the <acronym>NIS</acronym> Master
> 	Server</title>
> 
>       <para>The canonical copies of all <acronym>NIS</acronym> files
> 	are stored on the master server.  The databases used to store
> 	the information are called <acronym>NIS</acronym> maps.  In
> 	&os;, these maps are stored in
> 	<filename>/var/yp/[domainname]</filename> where
> 	<filename>[domainname]</filename> is the name of the
> 	<acronym>NIS</acronym> domain.  Since multiple domains are
> 	supported, it is possible to have several directories, one for
> 	each domain.  Each domain will have its own independent set of
> 	maps.</para>
> 
>       <para><acronym>NIS</acronym> master and slave servers handle all
> 	<acronym>NIS</acronym> requests through &man.ypserv.8;.  This
> 	daemon is responsible for receiving incoming requests from
> 	<acronym>NIS</acronym> 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>
> 
>       <indexterm><primary>NIS</primary>
> 	<secondary>server configuration</secondary>
>       </indexterm>
>       <para>Setting up a master <acronym>NIS</acronym> server can be
> 	relatively straight forward, depending on environmental needs.
> 	Since &os; provides built-in <acronym>NIS</acronym> support,
> 	it only needs to be enabled by adding the following lines to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>nisdomainname="test-domain"	<co xml:id="network-nis-co-domainname" />
> nis_server_enable="YES"		<co xml:id="network-nis-co-server" />
> nis_yppasswdd_enable="YES"	<co xml:id="network-nis-co-yppasswdd" /></programlisting>
> 
>       <calloutlist>
> 	<callout arearefs="network-nis-co-domainname">
> 	  <para>This line sets the <acronym>NIS</acronym> domain name
> 	    to <literal>test-domain</literal>.</para>
> 	</callout>
> 
> 	<callout arearefs="network-nis-co-server">
> 	  <para>This automates the start up of the
> 	    <acronym>NIS</acronym> server processes when the system
> 	    boots.</para>
> 	</callout>
> 
> 	<callout arearefs="network-nis-co-yppasswdd">
> 	  <para>This enables the &man.rpc.yppasswdd.8; daemon so that
> 	    users can change their <acronym>NIS</acronym> password
> 	    from a client machine.</para>
> 	</callout>
>       </calloutlist>
> 
>       <para>Care must be taken in a multi-server domain where the
> 	server machines are also <acronym>NIS</acronym> 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>A server that is also a client can be forced to bind to a
> 	particular server by adding these additional lines to
> 	<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>After saving the edits, type
> 	<command>/etc/netstart</command> to restart the network and
> 	apply the values defined in <filename>/etc/rc.conf</filename>.
> 	Before initializing the <acronym>NIS</acronym> maps, start
> 	&man.ypserv.8;:</para>
> 
>       <screen>&prompt.root; <userinput>service ypserv start</userinput></screen>
> 
>       <sect3>
> 	<title>Initializing the <acronym>NIS</acronym> Maps</title>
> 
> 	<indexterm>
> 	  <primary>NIS</primary>
> 	  <secondary>maps</secondary>
> 	</indexterm>
> 	<para><acronym>NIS</acronym> maps are generated from the
> 	  configuration files in <filename>/etc</filename> on the
> 	  <acronym>NIS</acronym> master, with one exception:
> 	  <filename>/etc/master.passwd</filename>.  This is to prevent
> 	  the propagation of passwords to all the servers in the
> 	  <acronym>NIS</acronym> domain.  Therefore, before the
> 	  <acronym>NIS</acronym> maps are initialized, configure the
> 	  primary password files:</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>It is advisable to remove all entries for system
> 	  accounts as well as any user accounts that do not need to be
> 	  propagated to the <acronym>NIS</acronym> clients, such as
> 	  the <systemitem class="username">root</systemitem> and any
> 	  other administrative accounts.</para>
> 
> 	<note>
> 	  <para>Ensure that the
> 	    <filename>/var/yp/master.passwd</filename> is neither
> 	    group or world readable by setting its permissions to
> 	    <literal>600</literal>.</para>
> 	</note>
> 
> 	<para>After completing this task, initialize the
> 	  <acronym>NIS</acronym> maps.  &os; includes the
> 	  &man.ypinit.8; script to do this.  When generating maps
> 	  for the master server, include <option>-m</option> and
> 	  specify the <acronym>NIS</acronym> domain name:</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 not, 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>This will create <filename>/var/yp/Makefile</filename>
> 	  from <filename>/var/yp/Makefile.dist</filename>.  By
> 	  default, this file assumes that the environment has a
> 	  single <acronym>NIS</acronym> server with only &os; clients.
> 	  Since <literal>test-domain</literal> has a slave server,
> 	  edit this line in <filename>/var/yp/Makefile</filename> so
> 	  that it begins with a  comment
> 	  (<literal>#</literal>):</para>
> 
> 	<programlisting>NOPUSH = "True"</programlisting>
>       </sect3>
> 
>       <sect3>
> 	<title>Adding New Users</title>
> 
> 	<para>Every time a new user is created, the user account must
> 	  be added to the master <acronym>NIS</acronym> server and the
> 	  <acronym>NIS</acronym> maps rebuilt.  Until this occurs, the
> 	  new user will not be able to login anywhere except on the
> 	  <acronym>NIS</acronym> master.  For example, to add the new
> 	  user <systemitem class="username">jsmith</systemitem> to the
> 	  <literal>test-domain</literal> domain, run these commands on
> 	  the master server:</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>The user could also be added using <command>adduser
> 	    jsmith</command> instead of <command>pw useradd
> 	    smith</command>.</para>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Setting up a <acronym>NIS</acronym> Slave Server</title>
> 
>       <indexterm>
> 	<primary>NIS</primary>
> 	<secondary>slave server</secondary>
>       </indexterm>
>       <para>To set up an <acronym>NIS</acronym> slave server, log on
> 	to the slave server and edit <filename>/etc/rc.conf</filename>
> 	as for the master server.  Do not generate any
> 	<acronym>NIS</acronym> maps, as these already exist on the
> 	master server.  When running <command>ypinit</command> on the
> 	slave server, use <option>-s</option> (for slave) instead of
> 	<option>-m</option> (for master).  This option requires the
> 	name of the <acronym>NIS</acronym> master in addition to the
> 	domain name, as  seen in this example:</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 not, 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.
> Remember to update map ypservers on ellington.</screen>
> 
>       <para>This will generate a directory on the slave server called
> 	<filename>/var/yp/test-domain</filename> which contains copies
> 	of the <acronym>NIS</acronym> master server's maps.  Adding
> 	these <filename>/etc/crontab</filename> entries on each slave
> 	server will force the slaves to sync their maps with the maps
> 	on the master server:</para>
> 
>       <programlisting>20      *       *       *       *       root   /usr/libexec/ypxfr passwd.byname
> 21      *       *       *       *       root   /usr/libexec/ypxfr passwd.byuid</programlisting>
> 
>       <para>These entries are not mandatory because the master server
> 	automatically attempts to push any map changes to its slaves.
> 	However, since clients may depend upon the slave server to
> 	provide correct password information, it is recommended to
> 	force frequent password map updates.  This is especially
> 	important on busy networks where map updates might not always
> 	complete.</para>
> 
>       <para>To finish the configuration, run
> 	<command>/etc/netstart</command> on the slave server in order
> 	to start the <acronym>NIS</acronym> services.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Setting Up an <acronym>NIS</acronym> Client</title>
> 
>       <para>An <acronym>NIS</acronym> client binds to an
> 	<acronym>NIS</acronym> server using &man.ypbind.8;.  This
> 	daemon broadcasts RPC requests on the local network.  These
> 	requests specify the domain name configured on the client.  If
> 	an <acronym>NIS</acronym> server in the same domain receives
> 	one of the broadcasts, it will respond to
> 	<application>ypbind</application>, which will record the
> 	server's address.  If there are several servers available,
> 	the client will use the address of the first server to respond
> 	and will direct all of its <acronym>NIS</acronym> requests to
> 	that server.  The client will automatically
> 	<application>ping</application> the server on a regular basis
> 	to make sure it is still available.  If it fails to receive a
> 	reply within a reasonable amount of time,
> 	<application>ypbind</application> will mark the domain as
> 	unbound and begin broadcasting again in the hopes of locating
> 	another server.</para>
> 
>       <indexterm><primary>NIS</primary>
> 	<secondary>client configuration</secondary>
>       </indexterm>
> 
>       <para>To configure a &os; machine to be an
> 	<acronym>NIS</acronym> client:</para>
> 
>       <procedure>
> 	<step>
> 	  <para>Edit <filename>/etc/rc.conf</filename> and add the
> 	    following lines in order to set the
> 	    <acronym>NIS</acronym> domain name and start
> 	    &man.ypbind.8; during network startup:</para>
> 
> 	  <programlisting>nisdomainname="test-domain"
> nis_client_enable="YES"</programlisting>
> 	</step>
> 
> 	<step>
> 	  <para>To import all possible password entries from the
> 	    <acronym>NIS</acronym> server, use
> 	    <command>vipw</command> to remove all user accounts
> 	    except one from <filename>/etc/master.passwd</filename>.
> 	    When removing the accounts, keep in mind that at least one
> 	    local account should remain and this account should be a
> 	    member of <systemitem
> 	      class="groupname">wheel</systemitem>.  If there is a
> 	    problem with <acronym>NIS</acronym>, this local account
> 	    can be used to log in remotely, become the superuser, and
> 	    fix the problem.  Before saving the edits, add the
> 	    following line to the end of the file:</para>
> 
> 	  <programlisting>+:::::::::</programlisting>
> 
> 	  <para>This line configures the client to provide anyone with
> 	    a valid account in the <acronym>NIS</acronym> server's
> 	    password maps an account on the client.  There are many
> 	    ways to configure the <acronym>NIS</acronym> client by
> 	    modifying this line.  One method is described in <xref
> 	      linkend="network-netgroups"/>.  For more detailed
> 	    reading, refer to the book
> 	    <literal>Managing NFS and NIS</literal>, published by
> 	    O'Reilly Media.</para>
> 	</step>
> 
> 	<step>
> 	  <para>To import all possible group entries from the
> 	    <acronym>NIS</acronym> server, add this line to
> 	    <filename>/etc/group</filename>:</para>
> 
> 	  <programlisting>+:*::</programlisting>
> 	</step>
>       </procedure>
> 
>       <para>To start the <acronym>NIS</acronym> client immediately,
> 	execute the following commands as the superuser:</para>
> 
>       <screen>&prompt.root; <userinput>/etc/netstart</userinput>
> &prompt.root; <userinput>service ypbind start</userinput></screen>
> 
>       <para>After completing these steps, running
> 	<command>ypcat passwd</command> on the client should show
> 	the server's <filename>passwd</filename> map.</para>
>     </sect2>
> 
>     <sect2>
>       <title><acronym>NIS</acronym> Security</title>
> 
>       <para>Since <acronym>RPC</acronym> is a broadcast-based service,
> 	any system running <application>ypbind</application> within
> 	the same domain can retrieve the contents of the
> 	<acronym>NIS</acronym> maps.  To prevent 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.  By default, this information is
> 	stored in <filename>/var/yp/securenets</filename>, unless
> 	&man.ypserv.8; is started with <option>-p</option> and an
> 	alternate path.  This file contains entries that consist of a
> 	network specification and a network mask separated by white
> 	space.  Lines starting with <literal>#</literal> are
> 	considered to be comments.  A sample
> 	<filename>securenets</filename> might look like this:</para>
> 
>       <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>securenets</filename> does not exist,
> 	<command>ypserv</command> will allow connections from any
> 	host.</para>
> 
>       <para><xref linkend="tcpwrappers"/> is an alternate mechanism
> 	for providing access control instead of
> 	<filename>securenets</filename>.  While either access control
> 	mechanism adds some security, they are both vulnerable to
> 	<quote><acronym>IP</acronym> spoofing</quote> attacks.  All
> 	<acronym>NIS</acronym>-related traffic should be blocked at
> 	the firewall.</para>
> 
>       <para>Servers using <filename>securenets</filename>
> 	may fail to serve legitimate <acronym>NIS</acronym> clients
> 	with archaic TCP/IP implementations.  Some of these
> 	implementations set all host bits to zero when doing
> 	broadcasts 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 these client
> 	systems or the abandonment of
> 	<filename>securenets</filename>.</para>
> 
>       <indexterm><primary>TCP Wrapper</primary></indexterm>
>       <para>The use of <application>TCP Wrapper</application>
> 	increases the latency of the <acronym>NIS</acronym> server.
> 	The additional delay may be long enough to cause timeouts in
> 	client programs, especially in busy networks with slow
> 	<acronym>NIS</acronym> servers.  If one or more clients suffer
> 	from latency, convert those clients into
> 	<acronym>NIS</acronym> slave servers and force them to bind to
> 	themselves.</para>
> 
>       <sect3>
> 	<title>Barring Some Users</title>
> 
> 	<para>In this example, the <systemitem>basie</systemitem>
> 	  system is a faculty workstation within the
> 	  <acronym>NIS</acronym> domain.  The
> 	  <filename>passwd</filename> map on the master
> 	  <acronym>NIS</acronym> server contains accounts for both
> 	  faculty and students.  This section demonstrates how to
> 	  allow faculty logins on this system while refusing student
> 	  logins.</para>
> 
> 	<para>To prevent specified users from logging on to a system,
> 	  even if they are present in the <acronym>NIS</acronym>
> 	  database, use <command>vipw</command> to add
> 	  <literal>-<replaceable>username</replaceable></literal> with
> 	  the correct number of colons towards the end of
> 	  <filename>/etc/master.passwd</filename> on the client,
> 	  where <replaceable>username</replaceable> is the username of
> 	  a user to bar from logging in.  The line with the blocked
> 	  user must be before the <literal>+</literal> line that
> 	  allows <acronym>NIS</acronym> users.  In this example,
> 	  <systemitem class="username">bill</systemitem> is barred
> 	  from logging on to <systemitem>basie</systemitem>:</para>
> 
> 	<screen>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>
>       </sect3>
>     </sect2>
> 
>     <sect2 xml:id="network-netgroups">
>       
> 
>       <title>Using Netgroups</title>
> 
>       <indexterm><primary>netgroups</primary></indexterm>
> 
>       <para>Barring specified users from logging on to individual
> 	systems becomes unscaleable on larger networks and quickly
> 	loses the main benefit of <acronym>NIS</acronym>:
> 	<emphasis>centralized</emphasis> administration.</para>
> 
>       <para>Netgroups were developed to handle large, complex networks
> 	with hundreds of users and machines.  Their use is comparable
> 	to &unix; groups, where the main difference is the lack of a
> 	numeric ID and the ability to define a netgroup by including
> 	both user accounts and other netgroups.</para>
> 
>       <para>To expand on the example used in this chapter, the
> 	<acronym>NIS</acronym> domain will be extended to add the
> 	users and systems shown in Tables 28.2 and 28.3:</para>
> 
>       <table frame="none" pgwide="1">
> 	<title>Additional Users</title>
> 
> 	<tgroup cols="2">
> 	  <thead>
> 	    <row>
> 	      <entry>User Name(s)</entry>
> 	      <entry>Description</entry>
> 	    </row>
> 	  </thead>
> 
> 	  <tbody>
> 	    <row>
> 	      <entry><systemitem class="username">alpha</systemitem>,
> 		<systemitem class="username">beta</systemitem></entry>
> 	      <entry>IT department employees</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem
> 		  class="username">charlie</systemitem>, <systemitem
> 		  class="username">delta</systemitem></entry>
> 	      <entry>IT department apprentices</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem class="username">echo</systemitem>,
> 		<systemitem class="username">foxtrott</systemitem>,
> 		<systemitem class="username">golf</systemitem>,
> 		...</entry>
> 	      <entry>employees</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem class="username">able</systemitem>,
> 		<systemitem class="username">baker</systemitem>,
> 		...</entry>
> 	      <entry>interns</entry>
> 	    </row>
> 	  </tbody>
> 	</tgroup>
>       </table>
> 
>       <table frame="none" pgwide="1">
> 	<title>Additional Systems</title>
> 
> 	<tgroup cols="2">
> 	  <thead>
> 	    <row>
> 	      <entry>Machine Name(s)</entry>
> 	      <entry>Description</entry>
> 	    </row>
> 	  </thead>
> 
> 	  <tbody>
> 	    <row>
> 	      
> 	      <entry><systemitem>war</systemitem>,
> 		<systemitem>death</systemitem>,
> 		<systemitem>famine</systemitem>,
> 		<systemitem>pollution</systemitem></entry>
> 	      <entry>Only IT employees are allowed to log onto these
> 		servers.</entry>
> 	    </row>
> 
> 	    <row>
> 	      
> 	      <entry><systemitem>pride</systemitem>,
> 		<systemitem>greed</systemitem>,
> 		<systemitem>envy</systemitem>,
> 		<systemitem>wrath</systemitem>,
> 		<systemitem>lust</systemitem>,
> 		<systemitem>sloth</systemitem></entry>
> 	      <entry>All members of the IT department are allowed to
> 		login onto these servers.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>one</systemitem>,
> 		<systemitem>two</systemitem>,
> 		<systemitem>three</systemitem>,
> 		<systemitem>four</systemitem>,
> 		...</entry>
> 	      <entry>Ordinary workstations used by
> 		employees.</entry>
> 	    </row>
> 
> 	    <row>
> 	      <entry><systemitem>trashcan</systemitem></entry>
> 	      <entry>A very old machine without any critical data.
> 		Even interns are allowed to use this system.</entry>
> 	    </row>
> 	  </tbody>
> 	</tgroup>
>       </table>
> 
>       <para>When using netgroups to configure this scenario, each user
> 	is assigned to one or more netgroups and logins are then
> 	allowed or forbidden for all members of the netgroup.  When
> 	adding a new machine, login restrictions must be defined for
> 	all netgroups.  When a new user is added, the account must be
> 	added to one or more netgroups.  If the
> 	<acronym>NIS</acronym> setup is planned carefully, only one
> 	central configuration file needs modification to grant or deny
> 	access to machines.</para>
> 
>       <para>The first step is the initialization of the
> 	<acronym>NIS</acronym> <literal>netgroup</literal> map.  In
> 	&os;, this map is not created by default.  On the
> 	<acronym>NIS</acronym> master server, use an editor to create
> 	a map named <filename>/var/yp/netgroup</filename>.</para>
> 
>       <para>This example creates four netgroups to represent IT
> 	employees, IT apprentices, 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>Each entry configures a netgroup.  The first column in an
> 	entry is the name of the netgroup.  Each set of brackets
> 	represents  either a group of one or more users or the name of
> 	another netgroup.  When specifying a user, the three
> 	comma-delimited fields inside each group represent:</para>
> 
>       <orderedlist>
> 	<listitem>
> 	  <para>The name of the host(s) where the other fields
> 	    representing the user are valid.  If a hostname is not
> 	    specified, the entry is valid on all hosts.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para>The name of the account that belongs to this
> 	    netgroup.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para>The <acronym>NIS</acronym> domain for the account.
> 	    Accounts may be imported from other <acronym>NIS</acronym>
> 	    domains into a netgroup.</para>
> 	</listitem>
>       </orderedlist>
> 
>       <para>If a group contains multiple users, separate each user
> 	with  whitespace.  Additionally, each field may contain
> 	wildcards.  See &man.netgroup.5; for details.</para>
> 
>       <indexterm><primary>netgroups</primary></indexterm>
>       <para>Netgroup names longer than 8 characters should not be
> 	used.  The names are case sensitive and using capital letters
> 	for netgroup names is an easy way to distinguish between user,
> 	machine and netgroup names.</para>
> 
>       <para>Some non-&os; <acronym>NIS</acronym> clients cannot
> 	handle netgroups containing more than 15 entries.  This
> 	limit may be circumvented by creating several sub-netgroups
> 	with 15 users or fewer and a real netgroup consisting of the
> 	sub-netgroups, as seen in this example:</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>Repeat this process if more than 225 (15 times 15) users
> 	exist within a single netgroup.</para>
> 
>       <para>To activate and distribute the new
> 	<acronym>NIS</acronym> map:</para>
> 
>       <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput>
> ellington&prompt.root; <userinput>make</userinput></screen>
> 
>       <para>This will generate the three <acronym>NIS</acronym> maps
> 	<filename>netgroup</filename>,
> 	<filename>netgroup.byhost</filename> and
> 	<filename>netgroup.byuser</filename>.  Use the map key option
> 	of &man.ypcat.1; to check if the new <acronym>NIS</acronym>
> 	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 only produces output if host-specific netgroups were
> 	created.  The third command is used to get the list of
> 	netgroups for a user.</para>
> 
>       <para>To configure a client, use &man.vipw.8; to specify the
> 	name  of the netgroup.  For example, on the server named
> 	<systemitem>war</systemitem>,  replace this line:</para>
> 
>       <programlisting>+:::::::::</programlisting>
> 
>       <para>with</para>
> 
>       <programlisting>+@IT_EMP:::::::::</programlisting>
> 
>       <para>This specifies that only the users defined in the netgroup
> 	<literal>IT_EMP</literal> will be imported into this system's
> 	password database and only those users are allowed to login to
> 	this system.</para>
> 
>       <para>This configuration also applies to the
> 	<literal>~</literal> function of the shell and all routines
> 	which convert 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 the message
> 	<errorname>No such user</errorname>.  To fix this, import all
> 	user entries without allowing them to login into the servers.
> 	This can be achieved by adding an extra line:</para>
> 
>       <programlisting>+:::::::::/sbin/nologin</programlisting>
> 
>       <para>This line configures the client to import all entries but
> 	to replace the shell in those entries with
> 	<filename>/sbin/nologin</filename>.</para>
> 
>       
>       <para>Make sure that extra line is placed
> 	<emphasis>after</emphasis>
> 	<literal>+@IT_EMP:::::::::</literal>.  Otherwise, all user
> 	accounts imported from <acronym>NIS</acronym> will have
> 	<filename>/sbin/nologin</filename> as their login
> 	shell and no one will be able to login to the system.</para>
> 
>       <para>To configure the less important servers, replace the old
> 	<literal>+:::::::::</literal> on the servers with these
> 	lines:</para>
> 
>       <programlisting>+@IT_EMP:::::::::
> +@IT_APP:::::::::
> +:::::::::/sbin/nologin</programlisting>
> 
>       <para>The corresponding lines for the workstations
> 	would be:</para>
> 
>       <programlisting>+@IT_EMP:::::::::
> +@USERS:::::::::
> +:::::::::/sbin/nologin</programlisting>
> 
>       <para>NIS supports the creation of netgroups from other
> 	netgroups which can be useful if the policy regarding user
> 	access changes.  One possibility is the creation of role-based
> 	netgroups.  For example, one might 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
> 	workstations.  Each of these netgroups contains the netgroups
> 	that are allowed to login onto these machines.  The new
> 	entries for the <acronym>NIS</acronym>
> 	<literal>netgroup</literal> map would 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 when it is possible to define groups of
> 	machines with identical restrictions.  Unfortunately, this is
> 	the exception and not the rule.  Most of the time, the ability
> 	to define login restrictions on a per-machine basis is
> 	required.</para>
> 
>       <para>Machine-specific netgroup definitions are another
> 	possibility to deal with the policy changes.  In this
> 	scenario, the <filename>/etc/master.passwd</filename> of each
> 	system contains two lines starting with <quote>+</quote>.
> 	The first line adds a netgroup with the accounts allowed to
> 	login onto this machine and the second line adds all other
> 	accounts with <filename>/sbin/nologin</filename> as shell.  It
> 	is recommended to use the <quote>ALL-CAPS</quote> version of
> 	the hostname as the name of the netgroup:</para>
> 
>       <programlisting>+@<replaceable>BOXNAME</replaceable>:::::::::
> +:::::::::/sbin/nologin</programlisting>
> 
>       <para>Once this task is completed on all the machines, there is
> 	no longer a need to modify the local versions of
> 	<filename>/etc/master.passwd</filename> ever again.  All
> 	further changes can be handled by modifying the
> 	<acronym>NIS</acronym> map.  Here is an example of a possible
> 	<literal>netgroup</literal> map for this scenario:</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>It may not always be advisable
> 	to use machine-based netgroups.  When deploying a couple of
> 	dozen or hundreds of systems,
> 	role-based netgroups instead of machine-based netgroups may be
> 	used to keep the size of the <acronym>NIS</acronym> map within
> 	reasonable limits.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Password Formats</title>
> 
>       <indexterm>
> 	<primary>NIS</primary>
> 	  <secondary>password formats</secondary>
>       </indexterm>
>       <para><acronym>NIS</acronym> requires that all hosts within an
> 	<acronym>NIS</acronym> domain use the same format for
> 	encrypting passwords.  If users have trouble authenticating on
> 	an <acronym>NIS</acronym> client, it may be due to a differing
> 	password format.  In a heterogeneous network, the format must
> 	be supported by all operating systems, where
> 	<acronym>DES</acronym> is the lowest common standard.</para>
> 
>       <para>To check which format a server or client is using, look
> 	at this section of
> 	<filename>/etc/login.conf</filename>:</para>
> 
>       <programlisting>default:\
> 	:passwd_format=des:\
> 	:copyright=/etc/COPYRIGHT:\
> 	[Further entries elided]</programlisting>
> 
>       <para>In this example, the system is using the
> 	<acronym>DES</acronym> format.  Other possible values are
> 	<literal>blf</literal> for Blowfish and <literal>md5</literal>
> 	for MD5 encrypted passwords.</para>
> 
>       <para>If the format on a host needs to be edited to match the
> 	one  being used in the <acronym>NIS</acronym> domain, the
> 	login capability database must be rebuilt after saving the
> 	change:</para>
> 
>       <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
> 
>       <note>
> 	<para>The format of passwords for existing user accounts will
> 	  not be updated until each user changes their password
> 	  <emphasis>after</emphasis> the login capability database is
> 	  rebuilt.</para>
>       </note>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-ldap">
>     <info>
>       <title>Lightweight Directory Access Protocol
> 	(<acronym>LDAP</acronym>)</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
>+	    <firstname>Rocky</firstname>
>+	    <surname>Hotas</surname>
>+	  </personname>
>+	  <contrib>Updated and restructured by </contrib>
>+	</author>
>+      </authorgroup>
>+
>+      <authorgroup>
>+	<author>
>+	  <personname>
> 	    <firstname>Tom</firstname>
> 	    <surname>Rhodes</surname>
> 	  </personname>
>-	  <contrib>Written by </contrib>
>+	  <contrib>Originally contributed by </contrib>
> 	</author>
>       </authorgroup>
>+
>     </info>
> 
>     <indexterm><primary>LDAP</primary></indexterm>
> 
>     <para>The Lightweight Directory Access Protocol
>       (<acronym>LDAP</acronym>) is an application layer protocol used
>       to access, modify, and authenticate objects using a distributed
>       directory information service.  Think of it as a phone or record
>       book which stores several levels of hierarchical, homogeneous
>       information.  It is used in Active Directory and
>       <application>OpenLDAP</application> networks and allows users to
>       access to several levels of internal information utilizing a
>       single account.  For example, email authentication, pulling
>       employee contact information, and internal website
>       authentication might all make use of a single user account in
>       the <acronym>LDAP</acronym> server's record base.</para>
> 
>     <para>This section provides a quick start guide for configuring an
>       <acronym>LDAP</acronym> server on a &os; system.  It assumes
>       that the administrator already has a design plan which includes
>       the type of information to store, what that information will be
>       used for, which users should have access to that information,
>       and how to secure this information from unauthorized
>       access.</para>
> 
>     <sect2>
>       <title><acronym>LDAP</acronym> Terminology and Structure</title>
> 
>       <para><acronym>LDAP</acronym> uses several terms which should be
> 	understood before starting the configuration.  All directory
> 	entries consist of a group of
> 	<firstterm>attributes</firstterm>.  Each of these attribute
> 	sets contains a unique identifier known as a
> 	<firstterm>Distinguished Name</firstterm>
> 	(<acronym>DN</acronym>) which is normally built from several
> 	other attributes such as the common or
> 	<firstterm>Relative Distinguished Name</firstterm>
> 	(<acronym>RDN</acronym>).  Similar to how directories have
> 	absolute and relative paths, consider a <acronym>DN</acronym>
> 	as an absolute path and the <acronym>RDN</acronym> as the
> 	relative path.</para>
> 
>       <para>An example <acronym>LDAP</acronym> entry looks like the
> 	following.  This example searches for the entry for the
> 	specified user account (<literal>uid</literal>),
> 	organizational unit (<literal>ou</literal>), and organization
> 	(<literal>o</literal>):</para>
> 
>       <screen>&prompt.user; <userinput>ldapsearch -xb "uid=<replaceable>trhodes</replaceable>,ou=<replaceable>users</replaceable>,o=<replaceable>example.com</replaceable>"</userinput>
> # extended LDIF
> #
> # LDAPv3
> # base &lt;uid=trhodes,ou=users,o=example.com&gt; with scope subtree
> # filter: (objectclass=*)
> # requesting: ALL
> #
> 
> # trhodes, users, example.com
> dn: uid=trhodes,ou=users,o=example.com
> mail: trhodes@example.com
> cn: Tom Rhodes
> uid: trhodes
> telephoneNumber: (123) 456-7890
> 
> # search result
> search: 2
> result: 0 Success
> 
> # numResponses: 2
> # numEntries: 1</screen>
> 
>       <para>This example entry shows the values for the
> 	<literal>dn</literal>, <literal>mail</literal>,
> 	<literal>cn</literal>, <literal>uid</literal>, and
> 	<literal>telephoneNumber</literal> attributes.  The
> 	<acronym>cn</acronym> attribute is the
> 	<acronym>RDN</acronym>.</para>
> 
>       <para>More information about <acronym>LDAP</acronym> and its
> 	terminology can be found at <uri
>-	  xlink:href="http://www.openldap.org/doc/admin24/intro.html">http://www.openldap.org/doc/admin24/intro.html</uri>.</para>
>+	  xlink:href="http://www.openldap.org/doc/admin24/intro.html"
>+	  >http://www.openldap.org/doc/admin24/intro.html</uri>
>+	.</para>
>     </sect2>
> 
>     <sect2 xml:id="ldap-config">
>       <title>Configuring an <acronym>LDAP</acronym> Server</title>
> 
>       <indexterm><primary>LDAP Server</primary></indexterm>
> 
>       <para>&os; does not provide a built-in <acronym>LDAP</acronym>
> 	server.  Begin the configuration by installing the <package
>-	  role="port">net/openldap24-server</package> package or port.
>-	Since the port has many configurable options, it is
>-	recommended that the default options are reviewed to see if
>-	the package is sufficient, and to instead compile the port if
>-	any options should be changed.  In most cases, the defaults
>-	are fine.  However, if SQL support is needed, this option must
>-	be enabled and the port compiled using the instructions in
>-	<xref linkend="ports-using"/>.</para>
>+	  role="port">net/openldap24-server</package> package or
>+	port.  Be sure to run all the commands listed from now on
>+	being <systemitem class="username">root</systemitem>.  This
>+
>+	<screen>&prompt.root; <userinput>pkg install openldap24-server</userinput></screen>
>+
>+	installs the needed <emphasis>package</emphasis>, which is a
>+	particular kind of <emphasis>port</emphasis>:
>+	the one with all options set to default.
>+	In most cases, the defaults are fine and so the package is
>+	too.  But if for example SQL support is needed,
>+	the relative option must be enabled and the port compiled
>+	using the instructions in <xref linkend="ports-using"/>.
>+	There are many other configurable options, so it is
>+	recommended that the defaults are reviewed to see if
>+	the <emphasis>package</emphasis> is sufficient, and to
>+	instead compile the <emphasis>port</emphasis> if
>+	any options should be changed.</para>
> 
>-      <para>Next, create the directories to hold the data and to store
>-	the certificates:</para>
>+      <para>If the directories to store the data and certificates do
>+	not exist already, create them:</para>
> 
>       <screen>&prompt.root; <userinput>mkdir /var/db/openldap-data</userinput>
> &prompt.root; <userinput>mkdir /usr/local/etc/openldap/private</userinput></screen>
> 
>-      <para>Copy over the database configuration file:</para>
>+      <para>The database configuration file is</para>
>+
>+      <screen>/usr/local/etc/openldap/DB_CONFIG.example</screen>
>+
>+      <para>If this file is not present after the installation of
>+	<package role="port">net/openldap24-server</package>, it is
>+	available for download <link
>+	  xlink:href="http://wpollock.com/AUnixNet/LDAP/lister.php?file=DB_CONFIG.example&amp;linenums&amp;dl">
>+	  here</link> (this is not the only suitable copy of this
>+	file on the internet: other identical ones can be found
>+	through a search engine, if this link is not available).
>+	Further information about this file and its parameters can
>+	be found in the <link xlink:href=
>+	  "http://www.openldap.org/faq/data/cache/1072.html">
>+	  OpenLDAP FAQs</link>.</para>
>+
>+      <para>Once downloaded, use the database configuration file in
>+	an appropriate directory:</para>
> 
>       <screen>&prompt.root; <userinput>cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG</userinput></screen>
> 
>-      <para>The next phase is to configure the certificate authority.
>-	The following commands must be executed from
>-	<filename>/usr/local/etc/openldap/private</filename>.  This is
>-	important as the file permissions need to be restrictive and
>-	users should not have access to these files.  To create the
>-	certificate authority, start with this command and follow the
>-	prompts:</para>
>+      <para>When dealing with a brand new configuration, being not
>+	in a big company or infrastructure who can buy or own
>+	several Certificate Authorities, the cheapest and easiest
>+	thing to do is to create a free, brand new Certificate
>+	Authority.  It is a self-signed certificate, which will be
>+	the root, invisibile certificate that will be use to sign
>+	all the other ones.  Further information about this
>+	procedure can be found in &man.openssl.1;, <link xlink:href=
>+	  "https://www.freebsd.org/cgi/man.cgi?query=req&amp;manpath=FreeBSD+11.0-RELEASE+and+Ports">
>+	  req(1)</link>	and in the <link xlink:href=
>+	  "http://www.openldap.org/doc/admin24/tls.html">OpenLDAP
>+	  2.4 Administrator's Guide</link>.  The following commands
>+	must be executed from
>+	<filename>/usr/local/etc/openldap/private</filename>.  This
>+	is important as the file permissions need to be restrictive
>+	and users should not have access to these files.  Here,
>+	&man.openssl.1; will be used to create the Certificate
>+	Authority, with the syntax shown below.</para>
>+
>+      <para>Several questions must be answered to and
>+	&man.openssl.1; will gather specific information to embed in
>+	the certificate.  As regards the OpenLDAP server
>+	installation, <emphasis>all but one</emphasis> of these
>+	questions are irrelevant.  The only important question is
>+	the one about the <literal>Common Name</literal>.  All the
>+	other answers may even be arbitrarily chosen or left empty.
>+	Instead,</para>
>+
>+      <important>
>+	<para>The <literal>Common Name</literal> should be
>+	  <emphasis>carefully</emphasis> chosen: for the Certificate
>+	  Authority, it should be a name that will be never used
>+	  again.</para>
>+      </important>
>+
>+      <para>In this example, <literal>CAdomain.example</literal>
>+	will be used. Another <literal>Common Name</literal> can be
>+	freely, arbitrarily chosen: the only important issue is that
>+	all the next certificates, that will be created and
>+	<emphasis>signed</emphasis> with this one, must have a
>+	different <literal>Common Name</literal>.</para>
> 
>       <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -x509 -keyout ca.key -out ../ca.crt</userinput></screen>
> 
>-      <para>The entries for the prompts may be generic
>-	<emphasis>except</emphasis> for the
>-	<literal>Common Name</literal>.  This entry must be
>-	<emphasis>different</emphasis> than the system hostname.  If
>-	this will be a self signed certificate, prefix the hostname
>-	with <literal>CA</literal> for certificate authority.</para>
>-
>-      <para>The next task is to create a certificate signing request
>-	and a private key.  Input this command and follow the
>-	prompts:</para>
>+      <para>With this command, a Certificate Authority called
>+	<filename>ca.crt</filename> is created in <filename>
>+	  /usr/local/etc/openldap</filename> and its private key
>+	<filename>ca.key</filename> is placed in
>+	<filename>/usr/local/etc/openldap/private</filename>.</para>
>+
>+      <para>A certificate (and a private key) for the
>+	<acronym>LDAP</acronym> server is now needed: it will be
>+	initially called a "Certificate Signing Request"; then,
>+	after being signed with the Certificate Authority, it will
>+	actually be a certificate.  Only the <literal>Common
>+	  Name</literal> attribute is important here like before: if
>+	for the Certificate Authority
>+	<filename>CAdomain.example</filename> was chosen, now the
>+	full hostname of the server <systemitem class="systemname">
>+	  domain.example</systemitem> can be used.  This is a
>+	trivial way to choose two different <literal>Common
>+	  Name</literal>s without effort.</para>
> 
>       <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -keyout server.key -out server.csr</userinput></screen>
> 
>-      <para>During the certificate generation process, be sure to
>-	correctly set the <literal>Common Name</literal> attribute.
>-	Once complete, sign the key:</para>
>+      <para>This Certificate Signing Request must be signed with the
>+	Certificate Authority in order to be used as a valid
>+	certificate:</para>
> 
>       <screen>&prompt.root; <userinput>openssl x509 -req -days <replaceable>365</replaceable> -in server.csr -out ../server.crt -CA ../ca.crt -CAkey ca.key -CAcreateserial</userinput></screen>
> 
>-      <para>The final part of the certificate generation process is to
>-	generate and sign the client certificates:</para>
>+      <para>In <filename>/usr/local/etc/openldap</filename> a file
>+	called <filename>server.crt</filename> has been created
>+	and it will be the server certificate: it is trusted
>+	because it is signed with the Certificate Authority.
>+	It is now possible to create even the <emphasis>
>+	  client</emphasis> Certificate Signing Request and to sign
>+	it with the same Certificate Authority as before (only this
>+	way also the client certificate will be trusted).
>+	If the client and the server are the same machine, the same
>+	<literal>Common Name</literal> as for
>+	<filename>server.csr</filename> must be used.  Otherwise,
>+	whatever name can be chosen, as far as it is different from
>+	the Certificate Authority <literal>Common Name</literal>
>+	<filename>CAdomain.example</filename>.</para>
> 
>       <screen>&prompt.root; <userinput>openssl req -days <replaceable>365</replaceable> -nodes -new -keyout client.key -out client.csr</userinput>
>-&prompt.root; <userinput>openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key</userinput></screen>
>+&prompt.root; <userinput>openssl x509 -req -days <replaceable>365</replaceable> -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key</userinput></screen>
> 
>-      <para>Remember to use the same <literal>Common Name</literal>
>-	attribute when prompted.  When finished, ensure that a total
>-	of eight (8) new files have been generated through the
>-	proceeding commands.  If so, the next step is to edit
>-	<filename>/usr/local/etc/openldap/slapd.conf</filename> and
>-	add the following options:</para>
>-
>-      <programlisting>TLSCipherSuite HIGH:MEDIUM:+SSLv3
>-TLSCertificateFile /usr/local/etc/openldap/server.crt
>-TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key
>-TLSCACertificateFile /usr/local/etc/openldap/ca.crt</programlisting>
>-
>-      <para>Then, edit
>-	<filename>/usr/local/etc/openldap/ldap.conf</filename> and add
>-	the following lines:</para>
>-
>-      <programlisting>TLS_CACERT /usr/local/etc/openldap/ca.crt
>-TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting>
>-
>-      <para>While editing this file, uncomment the following entries
>-	and set them to the desired values: <option>BASE</option>,
>-	<option>URI</option>, <option>SIZELIMIT</option> and
>-	<option>TIMELIMIT</option>.  Set the <option>URI</option> to
>-	contain <option>ldap://</option> and
>-	<option>ldaps://</option>.  Then, add two entries pointing to
>-	the certificate authority.  When finished, the entries should
>-	look similar to the following:</para>
>-
>-      <programlisting>BASE    dc=example,dc=com
>-URI     ldap:// ldaps://
>-
>-SIZELIMIT       12
>-TIMELIMIT       15
>-
>-TLS_CACERT /usr/local/etc/openldap/ca.crt
>-TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting>
>-
>-      <para>The default password for the server should then be
>-	changed:</para>
>-
>-      <screen>&prompt.root; <userinput>slappasswd -h "{SHA}" &gt;&gt; /usr/local/etc/openldap/slapd.conf</userinput></screen>
>-
>-      <para>This command will prompt for the password and, if the
>-	process does not fail, a password hash will be added to the
>-	end of <filename>slapd.conf</filename>.  Several hashing
>-	formats are supported.  Refer to the manual page for
>-	<command>slappasswd</command> for more information.</para>
>-
>-      <para>Next, edit
>-	<filename>/usr/local/etc/openldap/slapd.conf</filename> and
>-	add the following lines:</para>
>-
>-      <programlisting>password-hash {sha}
>-allow bind_v2</programlisting>
>-
>-      <para>The <option>suffix</option> in this file must be updated
>-	to match the <option>BASE</option> used in
>-	<filename>/usr/local/etc/openldap/ldap.conf</filename> and
>-	<option>rootdn</option> should also be set.  A recommended
>-	value for <option>rootdn</option> is something like
>-	<option>cn=Manager</option>.  Before saving this file, place
>-	the <option>rootpw</option> in front of the password output
>-	from <command>slappasswd</command> and delete the old
>-	<option>rootpw</option>.  The end result should
>-	look similar to this:</para>
>-
>-      <programlisting>TLSCipherSuite HIGH:MEDIUM:+SSLv3
>-TLSCertificateFile /usr/local/etc/openldap/server.crt
>-TLSCertificateKeyFile /usr/local/etc/openldap/private/server.key
>-TLSCACertificateFile /usr/local/etc/openldap/ca.crt
>-rootpw  {SHA}W6ph5Mm5Pz8GgiULbPgzG37mj9g=</programlisting>
>-
>-      <para>Finally, enable the <application>OpenLDAP</application>
>-	service in <filename>/etc/rc.conf</filename> and set the
>-	<acronym>URI</acronym>:</para>
>-
>-      <programlisting>slapd_enable="YES"
>-slapd_flags="-4 -h ldaps:///"</programlisting>
>-
>-      <para>At this point the server can be started and tested:</para>
>-
>-      <screen>&prompt.root; <userinput>service slapd start</userinput></screen>
>-
>-      <para>If everything is configured correctly, a search of the
>-	directory should show a successful connection with a single
>-	response as in this example:</para>
>-
>-      <screen>&prompt.root; <userinput>ldapsearch -Z</userinput>
>-# extended LDIF
>+      <para>When finished, be sure that eight new files have been
>+	created: the certificates <filename>ca.crt</filename>,
>+	<filename>server.crt</filename> and
>+	<filename>client.crt</filename> in
>+	<filename>/usr/local/etc/openldap</filename> and
>+	<filename>ca.key</filename>,
>+	<filename>client.csr</filename>,
>+	<filename>client.key</filename>,
>+	<filename>server.csr</filename>,
>+	<filename>server.key</filename> in
>+	<filename>/usr/local/etc/openldap/private</filename>.</para>
>+
>+      <para>The daemon running the OpenLDAP server is called
>+	<filename>slapd</filename> and it must be configured.
>+	Such a configuration can be performed in two ways: through a
>+	<filename>slapd.conf</filename> configuration file, or
>+	through a database file <filename>slapd.ldif</filename>.
>+	The former way is deprecated by OpenLDAP:</para>
>+
>+      <tip>
>+	<para>The use of <filename>slapd.ldif</filename> is
>+	  strongly recommended.</para>
>+      </tip>
>+
>+      <para>The structure of this file is not trivial.  A
>+	configuration example can be found <link xlink:href=
>+	  "http://www.openldap.org/doc/admin24/slapdconf2.html">
>+	  here</link>, in paragraph 5.3.  The directory
>+	<filename>/usr/local/etc/openldap</filename> contains a file
>+	named <filename>slapd.ldif.sample</filename> in order to
>+	ease the configuration.
>+	A full example of the <filename>slapd.ldif</filename> will
>+	be provided below, with some comments.  The file is composed
>+	by several parts: each of them is uniquely identified
>+	through a <literal>dn:</literal> (Distinguished Name).  The
>+	first one is the <emphasis>global configuration</emphasis>
>+	entry.  Be sure that no blank lines are between the
>+	<literal>dn:</literal> statement and the desired end of the
>+	section, otherwise an error will be generated.
>+	In the global section, options regarding the execution of
>+	<filename>slapd</filename> and security can be specified.
>+	The statements are generally the same as in <filename>slapd.conf
>+	  </filename>, but preceded by "<literal>olc</literal>".
>+	The beginning of the <filename>slapd.ldif</filename>
>+	configuration file is reported here: in
>+	this section, the certificate file, its key, and the
>+	Certificate Authority file should be specified, if a secure
>+	connection for communications is required.  In this example,
>+	TLS will be used to implement a secure channel.  All the
>+	following options (and more) are documented in
>+	<link xlink:href="https://www.freebsd.org/cgi/man.cgi?query=slapd-config&amp;manpath=FreeBSD+11.0-RELEASE+and+Ports">
>+	  slapd-config(5)</link>, which is recommended
>+	to be consulted during configuration.
>+	The following file is intended to work with the
>+	suggested TLS configuration.</para>
>+
>+      <programlisting>#
>+# See slapd-config(5) for details on configuration options.
>+# This file should NOT be world readable.
> #
>-# LDAPv3
>-# base &lt;dc=example,dc=com&gt; (default) with scope subtree
>-# filter: (objectclass=*)
>-# requesting: ALL
>+dn: cn=config
>+objectClass: olcGlobal
>+cn: config
>+#
>+#
>+# Define global ACLs to disable default read access.
> #
>+olcArgsFile: /var/run/openldap/slapd.args
>+olcPidFile: /var/run/openldap/slapd.pid
>+olcTLSCertificateFile: /usr/local/etc/openldap/server.crt <co xml:id="server-certificate"/>
>+olcTLSCertificateKeyFile: /usr/local/etc/openldap/private/server.key <co xml:id="server-key"/>
>+olcTLSCACertificateFile: /usr/local/etc/openldap/ca.crt <co xml:id="ca"/>
>+#olcTLSCipherSuite: HIGH:MEDIUM:+SSLv3 <co xml:id="cipher-suite"/>
>+olcTLSProtocolMin: 3.1 <co xml:id="protocol-min"/>
>+olcTLSVerifyClient: never <co xml:id="verify-client"/></programlisting>
> 
>-# search result
>-search: 3
>-result: 32 No such object
>+      <calloutlist>
>+	<callout arearefs="server-certificate">
>+	  <para>Specifies the location of the server certificate
>+	    for TLS operations.</para>
>+	</callout>
> 
>-# numResponses: 1</screen>
>+	<callout arearefs="server-key">
>+	  <para>Specifies the location of the server key.</para>
>+	</callout>
> 
>-      <note>
>-	<para>If the command fails and the configuration looks
>-	  correct, stop the <command>slapd</command> service and
>-	  restart it with debugging options:</para>
>+	<callout arearefs="ca">
>+	  <para>Specifies the location of the Certificate
>+	    Authority.</para>
>+	</callout>
> 
>-	<screen>&prompt.root; <userinput>service slapd stop</userinput>
>-&prompt.root; <userinput>/usr/local/libexec/slapd -d -1</userinput></screen>
>-      </note>
>+	<callout arearefs="cipher-suite">
>+	  <para>An option <literal>olcTLSCipherSuite</literal> can
>+	    be specified, but here is commented; it was suggested
>+	    to have the value <literal>HIGH:MEDIUM:+SSLv3</literal>.
>+	    It should be noted in fact that <literal>SSLv3</literal>
>+	    has been deprecated by IETF and that the syntax
>+	    <literal>HIGH:MEDIUM</literal> is related to <filename>
>+	      openssl</filename>; when clients with different
>+	    Operating Systems try to connect to this server, they
>+	    may not be able to parse this value.  In order to
>+	    connect to an <acronym>LDAP</acronym> server using TLS,
>+	    each client machine must run a <literal>TLS
>+	    client</literal>.  Linux machines, for example, use
>+	    <filename>gnutls</filename> as <literal>TLS
>+	    client</literal> instead of <filename>
>+	      openssl</filename>.  An error is generated if the
>+	    option
>+	    <literal>olcTLSCipherSuite: HIGH:MEDIUM:+SSLv3</literal>
>+	    is used with the shown syntax.
>+	    Otherwise <emphasis>all the clients</emphasis> won't run
>+	    FreeBSD, it is recommended to omit such a line, and let
>+	    the client OS choose the security cipher: this way, the
>+	    server configuration can be done and acceptable,
>+	    regardless of the <literal>TLS client</literal>s that
>+	    will connect.
>+	    The security cipher will be chosen according to the
>+	    available ciphers in the client machine, hopefully being
>+	    the most secure at the present time: it is not advisable
>+	    that the server force it and this is another benefit
>+	    when omitting the <literal>olcTLSCipherSuite</literal>.
>+	    The security of the client ciphers is demanded to the
>+	    package maintainers of the TLS clients.</para>
>+	</callout>
> 
>-      <para>Once the service is responding, the directory can be
>-	populated using <command>ldapadd</command>.  In this example,
>-	a file containing this list of users is first created.  Each
>-	user should use the following format:</para>
>-
>-      <programlisting>dn: dc=<replaceable>example</replaceable>,dc=<replaceable>com</replaceable>
>-objectclass: dcObject
>-objectclass: organization
>-o: <replaceable>Example</replaceable>
>-dc: <replaceable>Example</replaceable>
>-
>-dn: cn=<replaceable>Manager</replaceable>,dc=<replaceable>example</replaceable>,dc=<replaceable>com</replaceable>
>-objectclass: organizationalRole
>-cn: <replaceable>Manager</replaceable></programlisting>
>-
>-      <para>To import this file, specify the file name.  The following
>-	command will prompt for the password specified earlier and the
>-	output should look something like this:</para>
>-
>-      <screen>&prompt.root; <userinput>ldapadd -Z -D "cn=<replaceable>Manager</replaceable>,dc=<replaceable>example</replaceable>,dc=<replaceable>com</replaceable>" -W -f <replaceable>import.ldif</replaceable></userinput>
>-Enter LDAP Password:
>-adding new entry "dc=example,dc=com"
>+	<callout arearefs="protocol-min">
>+	  <para>The <acronym>LDAP</acronym> server Administrator can
>+	    anyway specify a minimum security level required by the
>+	    server.  Unlike for the previous one, the use of this
>+	    option is recommended:
>+	    <literal>olcTLSProtocolMin</literal>.</para>
>+	</callout>
> 
>-adding new entry "cn=Manager,dc=example,dc=com"</screen>
>+	<callout arearefs="verify-client">
>+	  <para>Server must always be verified, while clients can or
>+	    can not be verified: here it has been chosen to not
>+	    verify them with
>+	    <literal>olcTLSVerifyClient</literal>.</para>
>+	</callout>
> 
>-      <para>Verify the data was added by issuing a search on the
>-	server using <command>ldapsearch</command>:</para>
>+      </calloutlist>
>+
>+      <para>The second part is about the backend modules and can be
>+	configured as follows:</para>
>+
>+      <programlisting>#
>+# Load dynamic backend modules:
>+#
>+dn: cn=module,cn=config
>+objectClass: olcModuleList
>+cn: module
>+olcModulepath:	/usr/local/libexec/openldap
>+olcModuleload:	back_mdb.la
>+#olcModuleload:	back_bdb.la
>+#olcModuleload:	back_hdb.la
>+#olcModuleload:	back_ldap.la
>+#olcModuleload:	back_passwd.la
>+#olcModuleload:	back_shell.la</programlisting>
>+
>+      <para>The third part is devoted to load the needed <literal>
>+	  ldif</literal> schemas to be used by the databases: they
>+	are essential.</para>
>+
>+      <programlisting>dn: cn=schema,cn=config
>+objectClass: olcSchemaConfig
>+cn: schema
>+
>+include: file:///usr/local/etc/openldap/schema/core.ldif
>+include: file:///usr/local/etc/openldap/schema/cosine.ldif
>+include: file:///usr/local/etc/openldap/schema/inetorgperson.ldif
>+include: file:///usr/local/etc/openldap/schema/nis.ldif</programlisting>
>+
>+      <para>Then, the frontend configuration follows:</para>
>+
>+      <programlisting># Frontend settings
>+#
>+dn: olcDatabase={-1}frontend,cn=config
>+objectClass: olcDatabaseConfig
>+objectClass: olcFrontendConfig
>+olcDatabase: {-1}frontend
>+olcAccess: to * by * read
>+#
>+# Sample global access control policy:
>+#	Root DSE: allow anyone to read it
>+#	Subschema (sub)entry DSE: allow anyone to read it
>+#	Other DSEs:
>+#		Allow self write access
>+#		Allow authenticated users read access
>+#		Allow anonymous users to authenticate
>+#
>+#olcAccess: to dn.base="" by * read
>+#olcAccess: to dn.base="cn=Subschema" by * read
>+#olcAccess: to *
>+#	by self write
>+#	by users read
>+#	by anonymous auth
>+#
>+# if no access controls are present, the default policy
>+# allows anyone and everyone to read anything but restricts
>+# updates to rootdn.  (e.g., "access to * by * read")
>+#
>+# rootdn can always read and write EVERYTHING!
>+#
>+olcPasswordHash: {SSHA}
>+# {SSHA} is already the default for olcPasswordHash</programlisting>
>+
>+      <para>The following section describes the configuration
>+	backend: this will be the <emphasis>only way</emphasis> to
>+	access the global configuration for the system
>+	administrator, once this procedure is completed.  Thus, it
>+	is <emphasis>extremely important</emphasis> that all the
>+	needed options are here specified.  In particular, a root
>+	password must be chosen: together with the default
>+	administrator username <literal>cn=config</literal>, it will
>+	let the server administrator to later edit the configuration
>+	as the super-user.  Note that, without the specification of
>+	a <literal>olcRootPW</literal> here, after this file is
>+	imported as a configuration file for <filename>
>+	  slapd</filename>, no one will be able to modify this
>+	global configuration.  This is highly undesirable.
>+	If anyway something is wrong with the actual configuration,
>+	later will be shown a way to delete (and hopefully replace)
>+	it.
>+	A password can be generated using <link xlink:href=
>+	  "https://www.freebsd.org/cgi/man.cgi?query=slappasswd&amp;manpath=FreeBSD+11.0-RELEASE+and+Ports">
>+	  slappasswd(8c)</link> in a shell and its entire output must be
>+	used as a value for <literal>olcRootPW</literal>.</para>
>+
>+      <programlisting>dn: olcDatabase={0}config,cn=config
>+objectClass: olcDatabaseConfig
>+olcDatabase: {0}config
>+olcAccess: to * by * none
>+olcRootPW: {SSHA}iae+lrQZILpiUdf16Z9KmDmSwT77Dj4U</programlisting>
>+
>+      <para>The last section showed here is about the database
>+	backend, used for the <emphasis>actual contents</emphasis>
>+	of the <acronym>LDAP</acronym> directory.  This database can
>+	be used to add new groups and users as regards the domain
>+	<literal>domain.example</literal>.  Here, the database type
>+	<literal>mdb</literal> is used and another super-user is
>+	specified: it will be only able to modify this database and
>+	not the previous sections of
>+	<filename>slapd.ldif</filename>.  Here,	a username
>+	<literal>olcRootDN</literal> can be specified, being related
>+	to the domain.  A password can be generated as
>+	before.</para>
>+
>+      <programlisting>#######################################################################
>+# LMDB database definitions
>+#######################################################################
>+#
>+dn: olcDatabase=mdb,cn=config
>+objectClass: olcDatabaseConfig
>+objectClass: olcMdbConfig
>+olcDatabase: mdb
>+olcDbMaxSize: 1073741824
>+olcSuffix: dc=domain,dc=example
>+olcRootDN: cn=mdbadmin,dc=domain,dc=example
>+# Cleartext passwords, especially for the rootdn, should
>+# be avoided.  See slappasswd(8) and slapd-config(5) for details.
>+# Use of strong authentication encouraged.
>+olcRootPW: {SSHA}X2wHvIWDk6G76CQyCMS1vDCvtICWgn0+
>+# The database directory MUST exist prior to running slapd AND
>+# should only be accessible by the slapd and slap tools.
>+# Mode 700 recommended.
>+olcDbDirectory:	/var/db/openldap-data
>+# Indices to maintain
>+olcDbIndex: objectClass eq</programlisting>
>+
>+      <para>In <link xlink:href=
>+	  "http://www.openldap.org/devel/gitweb.cgi?p=openldap.git;a=tree;f=tests/data/regressions/its8444;h=8a5e808e63b0de3d2bdaf2cf34fecca8577ca7fd;hb=HEAD">this
>+	  repository</link>, four examples of <filename>slapd.ldif</filename>
>+	files are available (they are used as a 4-way multi master
>+	<acronym>LDAP</acronym> server).  At the bottom of <link
>+	  xlink:href="http://www.openldap.org/doc/admin24/slapdconf2.html">
>+	  this page</link>, section 5.4, also a way to convert an
>+	existing <filename>slapd.conf</filename> into a valid
>+	<filename>slapd.ldif</filename> is presented.  Please note
>+	that this may introduce some unuseful options.</para>
>+
>+      <para>Once the <filename>slapd.ldif</filename> configuration
>+	is completed, this file must be imported in an empty
>+	directory.  It is recommended to create it with the
>+	following name and location:</para>
>+
>+      <screen>&prompt.root; <userinput>mkdir /usr/local/etc/openldap/slapd.d/</userinput></screen>
>+
>+      <para>The commands suggested at points 9 and 10 in the <link
>+	  xlink:href="http://www.openldap.org/doc/admin24/quickstart.html">
>+	  OpenLDAP Quick Start guide</link> (which can anyway be
>+	considered as a reference for all the other operations) are
>+	currently wrong: instead, it is advisable to use</para>
>+
>+      <screen>&prompt.root; <userinput>/usr/local/sbin/slapadd -n0 -F /usr/local/etc/openldap/slapd.d/ -l /usr/local/etc/openldap/slapd.ldif</userinput></screen>
>+
>+      <para>This will import the configuration database.  To start
>+	the slapd daemon,</para>
>+
>+      <screen>&prompt.root; <userinput>/usr/local/libexec/slapd -F /usr/local/etc/openldap/slapd.d/</userinput></screen>
>+
>+      <para>Option <literal>-d</literal> can be used for debugging,
>+	as specified in <link xlink:href=
>+	  "https://www.freebsd.org/cgi/man.cgi?query=slapd&amp;sektion=8&amp;manpath=FreeBSD+11.0-RELEASE+and+Ports">
>+	  slapd(8)</link>.  To verify that the server is running and
>+	working,</para>
> 
>-      <screen>&prompt.user; <userinput>ldapsearch -Z</userinput>
>+      <screen>&prompt.root; <userinput>ldapsearch -x -b '' -s base '(objectclass=*)' namingContexts</userinput>
> # extended LDIF
> #
> # LDAPv3
>-# base &lt;dc=example,dc=com&gt; (default) with scope subtree
>+# base &lt;&gt; with scope baseObject
> # filter: (objectclass=*)
>-# requesting: ALL
>+# requesting: namingContexts
> #
> 
>-# example.com
>-dn: dc=example,dc=com
>-objectClass: dcObject
>-objectClass: organization
>-o: Example
>-dc: Example
>-
>-# Manager, example.com
>-dn: cn=Manager,dc=example,dc=com
>-objectClass: organizationalRole
>-cn: Manager
>+#
>+dn:
>+namingContexts: dc=domain,dc=example
> 
> # search result
>-search: 3
>+search: 2
> result: 0 Success
> 
>-# numResponses: 3
>-# numEntries: 2</screen>
>+# numResponses: 2
>+# numEntries: 1</screen>
>+
>+      <para>The server won't still be recognized by any client as
>+	trusted, anyway.
>+	The certificates were created in non-standard directories
>+	from the point of view of <filename>openssl</filename>.  In
>+	order for <filename>openssl</filename> to work, the
>+	directories where the certificates are stored must contain
>+	symbolic links (whose names are composed by a hash) to the
>+	certificates.  Even if some <filename>openssl</filename>
>+	commands are already available in a FreeBSD base system, it
>+	is necessary now to explicitly install the package:</para>
>+
>+      <screen>&prompt.root; <userinput>pkg install openssl</userinput></screen>
>+
>+      <para>This will provide the <link xlink:href=
>+	  "https://www.freebsd.org/cgi/man.cgi?query=c_rehash&amp;manpath=FreeBSD+11.0-RELEASE+and+Ports">c_rehash(1)</link>
>+	tool.  Now run</para>
>+
>+      <screen>&prompt.root; <userinput>c_rehash .</userinput></screen>
>+
>+      <para>from the directory where the CA is stored (in this
>+	example, <filename>/usr/local/etc/openldap</filename>,
>+	which contains the file <filename>ca.crt</filename>).  This
>+	utility must create a symlink for each
>+	<filename>.pem</filename>, <filename>.crt</filename>,
>+	<filename>.crl</filename> or <filename>.cer</filename> file
>+	in the directory.  Only this way <filename>server.crt</filename>
>+	can be recognized as a valid, trusted and acceptable
>+	certificate.  After having verified that symlinks have been
>+	created, in order to verify if the server certificate is
>+	trusted (and this is the operation each
>+	<acronym>LDAP</acronym> client does before accessing the
>+	server), run (from the <filename>server.crt</filename>
>+	directory):</para>
>+
>+      <screen>&prompt.root; <userinput>openssl verify -verbose -CApath . server.crt</userinput></screen>
>+
>+      <para>If <filename>slapd</filename> was running, it must now
>+	be restarted before using the server.
>+	Please, carefully read the comments included in
>+	<filename>/usr/local/etc/rc.d/slapd</filename>, to make a
>+	correct configuration to run <filename>slapd</filename> at
>+	boot.
>+	An additional option is needed if the
>+	<literal>cn=config</literal> style (that is: the file
>+	<filename>slapd.ldif</filename>) is used for configuration.
>+	You could put in <filename>/etc/rc.conf</filename> the
>+	following lines:</para>
>+
>+      <programlisting>lapd_enable="YES"
>+slapd_flags='-h "ldapi://%2fvar%2frun%2fopenldap%2fldapi/
>+ldap://0.0.0.0/"'
>+slapd_sockets="/var/run/openldap/ldapi"
>+slapd_cn_config="YES"</programlisting>
>+
>+      <para><filename>slapd</filename> doesn't provide debugging at
>+	boot, but <filename>dmesg -a</filename>, <filename>/var/log/messages</filename>
>+	and (in particular) <filename>/var/log/debug.log</filename>
>+	can be checked.</para>
>+
>+      <para>The <acronym>LDAP</acronym> users database is still
>+	empty.  An example, which adds a group called
>+	<literal>team</literal> and a user called
>+	<literal>john</literal> to the
>+	<systemitem class="systemname">domain.example</systemitem>
>+	database is here provided. Create a file
>+	<filename>domain.ldif</filename> with the following
>+	contents:</para>
>+
>+      <screen>&prompt.root; <userinput>cat domain.ldif</userinput>
>+dn: dc=domain,dc=example
>+objectClass: dcObject
>+objectClass: organization
>+o: domain.example
>+dc: domain
>+
>+dn: ou=groups,dc=domain,dc=example
>+objectClass: top
>+objectClass: organizationalunit
>+ou: groups
>+
>+dn: ou=users,dc=domain,dc=example
>+objectClass: top
>+objectClass: organizationalunit
>+ou: users
>+
>+dn: cn=team,ou=groups,dc=domain,dc=example
>+objectClass: top
>+objectClass: posixGroup
>+cn: team
>+gidNumber: 10001
>+
>+dn: uid=john,ou=users,dc=domain,dc=example
>+objectClass: top
>+objectClass: account
>+objectClass: posixAccount
>+objectClass: shadowAccount
>+cn: John McUser
>+uid: john
>+uidNumber: 10001
>+gidNumber: 10001
>+homeDirectory: /home/john/
>+loginShell: /usr/bin/bash
>+userPassword: secret</screen>
>+
>+      <para>Instead of being <literal>secret</literal>, the password
>+	in the last line of <filename>domain.ldif</filename> for
>+	<literal>john</literal> can be generated with
>+	<link xlink:href=
>+	  "https://www.freebsd.org/cgi/man.cgi?query=slappasswd&amp;manpath=FreeBSD+11.0-RELEASE+and+Ports">
>+	  slappasswd(8c)</link>.  Be careful about the
>+	default shell path: if it doesn't exist in the system where
>+	the user tries to log in, an error can be generated and the
>+	user could not be able to actually log in.  A symlink can be
>+	created, or a different shell can be used to avoid this.
>+	For the structure of the <literal>ldif</literal> files and
>+	the <acronym>LDAP</acronym> directory, see the OpenLDAP
>+	documentation.  Such data can be added to the database using
>+	the <literal>mdb</literal> administrator:</para>
>+
>+      <screen>&prompt.root; <userinput>ldapadd -W -D "cn=mdbadmin,dc=domain,dc=example" -f domain.ldif</userinput></screen>
>+
>+      <para>If instead a global option is to be modified, a
>+	<emphasis>different user</emphasis> must be considered: as
>+	anticipated, it is the <emphasis>global</emphasis>
>+	super-user.  Let's assume that the option
>+	<literal>olcTLSCipherSuite: HIGH:MEDIUM:SSLv3</literal> was
>+	specified before and now it must be deleted.  The
>+	instructions for the modification can be stored in the file
>+	<filename>global_mod</filename>.
>+	It must not contain the previous value of the option to be
>+	deleted in the last line: this means that
>+	<literal>olcTLSCipherSuite: HIGH:MEDIUM:SSLv3</literal> must
>+	not be included as last line.</para>
>+
>+      <screen>&prompt.root; <userinput>cat global_mod</userinput>
>+dn: cn=config
>+changetype: modify
>+delete: olcTLSCipherSuite</screen>
>+
>+      <para>The modifications can be applied with</para>
>+
>+      <screen>&prompt.root; <userinput>ldapmodify -f global_mod -x -D "cn=config" -W</userinput></screen>
>+
>+      <para><literal>cn=config</literal> is the
>+	<literal>dn</literal> (Distinguished Name) of the entry
>+	(section) of the database to be modified.
>+	Use <literal>ldapmodify</literal> to delete a single line
>+	of the database; <literal>ldapdelete</literal> is used to
>+	delete an entire entry (section) instead.
>+	Each database section has its own administrator and it must
>+	be specified while applying a modification.
>+	The global super-user, whose name is by default
>+	<literal>cn=config</literal>, should have a password set by
>+	<literal>olcRootPW</literal> in the
>+	<literal>dn: olcDatabase={0}config,cn=config</literal>
>+	section.  It is the one who must used here.  If something
>+	goes wrong, or if this root administrator cannot access the
>+	configuration backend, it is possible to completeley delete
>+	the current configuration.  It can be done by removing the
>+	directory that was previously created:</para>
>+
>+      <screen>&prompt.root; <userinput>rm -rf /usr/local/etc/openldap/slapd.d/</userinput></screen>
>+
>+      <para><filename>slapd.ldif</filename> can then be edited and
>+	imported again.  Please note that this procedure
>+	is not to be considered as ordinary, nor normal:
>+	it won't have side effects, but it should be followed
>+	<emphasis>only</emphasis> when no other solution is
>+	suitable.</para>
>+
>+      <para>This is the configuration of the server only.  The
>+	client, which can be the server itself, and/or another
>+	machine, relies upon other configuration files: a dedicated
>+	guide must be followed for them.</para>
> 
>-      <para>At this point, the server should be configured and
>-	functioning properly.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-dhcp">
>     
>     <title>Dynamic Host Configuration Protocol
>       (<acronym>DHCP</acronym>)</title>
> 
>     <indexterm>
>       <primary>Dynamic Host Configuration Protocol</primary>
>       <see><acronym>DHCP</acronym></see>
>     </indexterm>
>     <indexterm>
>       <primary>Internet Systems Consortium (ISC)</primary>
>     </indexterm>
> 
>     <para>The Dynamic Host Configuration Protocol
>       (<acronym>DHCP</acronym>) allows a system to connect to a
>       network in order to be assigned the necessary addressing
>       information for communication on that network.  &os; includes
>       the OpenBSD version of <command>dhclient</command> which is used
>       by the client to obtain the addressing information.  &os; does
>       not install a <acronym>DHCP</acronym> server, but several
>       servers are available in the &os; Ports Collection.  The
>       <acronym>DHCP</acronym> protocol is fully described in <link
> 	xlink:href="http://www.freesoft.org/CIE/RFC/2131/">RFC
> 	2131</link>.
>       Informational resources are also available at <link
> 	xlink:href="http://www.isc.org/downloads/dhcp/">isc.org/downloads/dhcp/</link>.</para>
> 
>     <para>This section describes how to use the built-in
>       <acronym>DHCP</acronym> client.  It then describes how to
>       install and configure a <acronym>DHCP</acronym> server.</para>
> 
>     <note>
>       <para>In &os;, the &man.bpf.4; device is needed by both the
> 	<acronym>DHCP</acronym> server and <acronym>DHCP</acronym>
> 	client.  This device is included in the
> 	<filename>GENERIC</filename>  kernel that is installed with
> 	&os;.  Users who prefer to create a custom kernel need to keep
> 	this device if  <acronym>DHCP</acronym> is used.</para>
> 
>       <para>It should be noted that <filename>bpf</filename> also
> 	allows privileged users to run network packet sniffers on
> 	that system.</para>
>     </note>
> 
>     <sect2>
>       <title>Configuring a <acronym>DHCP</acronym> Client</title>
> 
>       <para><acronym>DHCP</acronym> client support is included in the
> 	&os; installer, making it easy to configure a newly installed
> 	system to automatically receive its networking addressing
> 	information from an existing <acronym>DHCP</acronym> server.
> 	Refer to <xref linkend="bsdinstall-post"/> for examples of
> 	network configuration.</para>
> 
>       <indexterm><primary><acronym>UDP</acronym></primary></indexterm>
>       <para>When <command>dhclient</command> is executed on the client
> 	machine, it begins broadcasting requests for configuration
> 	information.  By default, these requests use
> 	<acronym>UDP</acronym> port 68.  The server replies on
> 	<acronym>UDP</acronym> port 67, giving the client an
> 	<acronym>IP</acronym> address and other relevant network
> 	information such as a subnet mask, default gateway, and
> 	<acronym>DNS</acronym> server addresses.  This information is
> 	in the form of a <acronym>DHCP</acronym>
> 	<quote>lease</quote> and is valid for a configurable time.
> 	This allows stale <acronym>IP</acronym> addresses for clients
> 	no longer connected to the network to automatically be reused.
> 	<acronym>DHCP</acronym> clients can obtain a great deal of
> 	information from the server.  An exhaustive list may be found
> 	in &man.dhcp-options.5;.</para>
> 
>       <para>By default, when a &os; system boots, its
> 	<acronym>DHCP</acronym> client runs in the background, or
> 	<firstterm>asynchronously</firstterm>.  Other startup scripts
> 	continue to run while the <acronym>DHCP</acronym> process
> 	completes, which speeds up system startup.</para>
> 
>       <para>Background <acronym>DHCP</acronym> works well when the
> 	<acronym>DHCP</acronym> server responds quickly to the
> 	client's requests.  However, <acronym>DHCP</acronym> may take
> 	a long time to complete on some systems.  If network services
> 	attempt to run before <acronym>DHCP</acronym> has assigned the
> 	network addressing information, they will fail.  Using
> 	<acronym>DHCP</acronym> in <firstterm>synchronous</firstterm>
> 	mode prevents this problem as it pauses startup until the
> 	<acronym>DHCP</acronym> configuration has completed.</para>
> 
>       <para>This line in <filename>/etc/rc.conf</filename> is used to
> 	configure background or asynchronous mode:</para>
> 
>       <programlisting>ifconfig_<replaceable>fxp0</replaceable>="DHCP"</programlisting>
> 
>       <para>This line may already exist if the system was configured
> 	to use <acronym>DHCP</acronym> during installation.  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>
> 
>       <para>To instead configure the system to use synchronous mode,
> 	and to pause during startup while <acronym>DHCP</acronym>
> 	completes, use
> 	<quote><literal>SYNCDHCP</literal></quote>:</para>
> 
>       <programlisting>ifconfig_<replaceable>fxp0</replaceable>="SYNCDHCP"</programlisting>
> 
>       <para>Additional client options are available.  Search for
> 	<literal>dhclient</literal> in &man.rc.conf.5; for
> 	details.</para>
> 
>       <indexterm>
> 	<primary><acronym>DHCP</acronym></primary>
> 	<secondary>configuration files</secondary>
>       </indexterm>
> 
>       <para>The <acronym>DHCP</acronym> client uses the following
> 	files:</para>
> 
>       <itemizedlist>
> 	<listitem>
> 	  <para><filename>/etc/dhclient.conf</filename></para>
> 
> 	  <para>The configuration file used by
> 	    <command>dhclient</command>.  Typically, this file
> 	    contains only comments as the defaults are suitable for
> 	    most clients.  This configuration file is described in
> 	    &man.dhclient.conf.5;.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><filename>/sbin/dhclient</filename></para>
> 
> 	  <para>More information about the command itself can
> 	    be found in &man.dhclient.8;.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><filename>/sbin/dhclient-script</filename></para>
> 
> 	  <para>The
> 	    &os;-specific <acronym>DHCP</acronym> 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 <acronym>DHCP</acronym> client keeps a database of
> 	    valid leases in this file, which is written as a log and
> 	    is described in &man.dhclient.leases.5;.</para>
> 	</listitem>
>       </itemizedlist>
>     </sect2>
> 
>     <sect2 xml:id="network-dhcp-server">
>       <title>Installing and Configuring a <acronym>DHCP</acronym>
> 	Server</title>
> 
>       <para>This section demonstrates how to configure a &os; system
> 	to act as a <acronym>DHCP</acronym> server using the Internet
> 	Systems Consortium (<acronym>ISC</acronym>) implementation of
> 	the <acronym>DHCP</acronym> server.  This implementation and
> 	its documentation can be installed using the
> 	<package>net/isc-dhcp43-server</package> package or
> 	port.</para>
> 
>       <indexterm>
> 	<primary><acronym>DHCP</acronym></primary>
> 	<secondary>server</secondary>
>       </indexterm>
> 
>       <indexterm>
> 	<primary><acronym>DHCP</acronym></primary>
> 	  <secondary>installation</secondary>
>       </indexterm>
> 
>       <para>The installation of
> 	<package>net/isc-dhcp43-server</package> installs a sample
> 	configuration file.  Copy
> 	<filename>/usr/local/etc/dhcpd.conf.example</filename> to
> 	<filename>/usr/local/etc/dhcpd.conf</filename> and make any
> 	edits to this new file.</para>
> 
>       <indexterm>
> 	<primary><acronym>DHCP</acronym></primary>
> 	  <secondary>dhcpd.conf</secondary>
>       </indexterm>
>       <para>The configuration file is comprised of declarations for
> 	subnets and hosts which define the  information that is
> 	provided to <acronym>DHCP</acronym>  clients.  For example,
> 	these  lines configure the following:</para>
> 
>       <programlisting>option domain-name "example.org";<co xml:id="domain-name"/>
> option domain-name-servers ns1.example.org;<co xml:id="domain-name-servers"/>
> option subnet-mask 255.255.255.0;<co xml:id="subnet-mask"/>
> 
> default-lease-time 600;<co xml:id="default-lease-time"/>
> max-lease-time 72400;<co xml:id="max-lease-time"/>
> ddns-update-style none;<co xml:id="ddns-update-style"/>
> 
> subnet 10.254.239.0 netmask 255.255.255.224 {
>   range 10.254.239.10 10.254.239.20;<co xml:id="range"/>
>   option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;<co xml:id="routers"/>
> }
> 
> host fantasia {
>   hardware ethernet 08:00:07:26:c0:a5;<co xml:id="hardware"/>
>   fixed-address fantasia.fugue.com;<co xml:id="fixed-address"/>
> }</programlisting>
> 
>       <calloutlist>
> 	<callout arearefs="domain-name">
> 	  <para>This option specifies the default search domain that
> 	    will be provided to clients.  Refer to
> 	    &man.resolv.conf.5; for more information.</para>
> 	</callout>
> 
> 	<callout arearefs="domain-name-servers">
> 	  <para>This option specifies a comma separated list of
> 	    <acronym>DNS</acronym> servers that the client should use.
> 	    They can be listed by their Fully Qualified Domain Names
> 	    (<acronym>FQDN</acronym>), as seen in the example, or by
> 	    their <acronym>IP</acronym> addresses.</para>
> 	</callout>
> 
> 	<callout arearefs="subnet-mask">
> 	  <para>The subnet mask that will be provided to
> 	    clients.</para>
> 	</callout>
> 
> 	<callout arearefs="default-lease-time">
> 	  <para>The default lease expiry time in seconds.  A client
>-	    can be configured to override this value.  </para>
>+	    can be configured to override this value.</para>
> 	</callout>
> 
> 	<callout arearefs="max-lease-time">
> 	  <para>The maximum allowed length of time, in seconds, for a
> 	    lease.  Should a client request a longer lease, a lease
> 	    will still be issued, but it will only be valid for
> 	    <literal>max-lease-time</literal>.</para>
> 	</callout>
> 
> 	<callout arearefs="ddns-update-style">
> 	  <para>The default of <option>none</option> disables dynamic
> 	    DNS updates.  Changing this to <option>interim</option>
> 	    configures the <acronym>DHCP</acronym> server to update a
> 	    <acronym>DNS</acronym> server whenever it hands out a
> 	    lease so that the <acronym>DNS</acronym> server knows
> 	    which <acronym>IP</acronym> addresses are associated with
> 	    which computers in the network.  Do not change the default
> 	    setting unless the <acronym>DNS</acronym> server has  been
> 	    configured to support dynamic
> 	    <acronym>DNS</acronym>.</para>
> 	</callout>
> 
> 	<callout arearefs="range">
> 	  <para>This line creates a pool of available
> 	    <acronym>IP</acronym> addresses which are reserved for
> 	    allocation to <acronym>DHCP</acronym> clients.  The range
> 	    of addresses must be valid for the network or subnet
> 	    specified in the previous line.</para>
> 	</callout>
> 
> 	<callout arearefs="routers">
> 	  <para>Declares the default gateway that is valid for the
> 	    network or subnet specified before the opening
> 	    <literal>{</literal> bracket.</para>
> 	</callout>
> 
> 	<callout arearefs="hardware">
> 	  <para>Specifies the hardware <acronym>MAC</acronym> address
> 	    of a client so that the <acronym>DHCP</acronym> server can
> 	    recognize the client when it makes a request.</para>
> 	</callout>
> 
> 	<callout arearefs="fixed-address">
> 	  <para>Specifies that this host should always be given the
> 	    same <acronym>IP</acronym> address.  Using the hostname is
> 	    correct, since the <acronym>DHCP</acronym> server will
> 	    resolve the hostname before returning the lease
> 	    information.</para>
> 	</callout>
>       </calloutlist>
> 
>       <para>This configuration file supports many more options.  Refer
> 	to dhcpd.conf(5), installed with the server, for details and
> 	examples.</para>
> 
>       <para>Once the configuration of <filename>dhcpd.conf</filename>
> 	is complete, enable the <acronym>DHCP</acronym> server in
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>dhcpd_enable="YES"
> dhcpd_ifaces="dc0"</programlisting>
> 
>       <para>Replace the <literal>dc0</literal> with the interface (or
> 	interfaces, separated by whitespace) that the
> 	<acronym>DHCP</acronym> server should listen on for
> 	<acronym>DHCP</acronym> client requests.</para>
> 
>       <para>Start the server by issuing the following command:</para>
> 
>       <screen>&prompt.root; <userinput>service isc-dhcpd start</userinput></screen>
> 
>       <para>Any future changes to the configuration of the server will
> 	require the <application>dhcpd</application> service to be
> 	stopped and then started using &man.service.8;.</para>
> 
>       <para>The <acronym>DHCP</acronym> server uses the following
> 	files.  Note that the manual pages are installed with the
> 	server software.</para>
> 
>       <indexterm>
> 	<primary><acronym>DHCP</acronym></primary>
> 	<secondary>configuration files</secondary>
>       </indexterm>
>       <itemizedlist>
> 	<listitem>
> 	  <para><filename>/usr/local/sbin/dhcpd</filename></para>
> 
> 	  <para>More information about the
> 	    <application>dhcpd</application> server can be found in
> 	    dhcpd(8).</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><filename>/usr/local/etc/dhcpd.conf</filename></para>
> 
> 	  <para>The server configuration file needs to contain all the
> 	    information that should be provided to clients, along with
> 	    information regarding the operation of the server.  This
> 	    configuration file is described in dhcpd.conf(5).</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><filename>/var/db/dhcpd.leases</filename></para>
> 
> 	  <para>The <acronym>DHCP</acronym> server keeps a database of
> 	    leases it has issued in this file, which is written as a
> 	    log.  Refer to dhcpd.leases(5), which gives a slightly
> 	    longer description.</para>
> 	</listitem>
> 
> 	<listitem>
> 	  <para><filename>/usr/local/sbin/dhcrelay</filename></para>
> 
> 	  <para>This daemon is used in advanced environments where one
> 	    <acronym>DHCP</acronym> server forwards a request from a
> 	    client to another <acronym>DHCP</acronym> server on a
> 	    separate network.  If this functionality is required,
> 	    install the <package>net/isc-dhcp43-relay</package>
> 	    package or port.  The installation includes dhcrelay(8)
> 	    which provides more detail.</para>
> 	</listitem>
>       </itemizedlist>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-dns">
>     
>     <title>Domain Name System (<acronym>DNS</acronym>)</title>
> 
>     <indexterm><primary>DNS</primary></indexterm>
> 
>     <para>Domain Name System (<acronym>DNS</acronym>) is the protocol
>       through which domain names are mapped to <acronym>IP</acronym>
>       addresses, and vice versa.  <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.  It is not
>       necessary to run a name server to perform
>       <acronym>DNS</acronym> lookups on a system.</para>
> 
>     <indexterm><primary>BIND</primary></indexterm>
> 
>     <para>In &os; 10, the Berkeley Internet Name Domain
>       (<acronym>BIND</acronym>) has been removed from the base system
>       and replaced with Unbound.  Unbound as configured in the &os;
>       Base is a local caching resolver.  <acronym>BIND</acronym> is
>       still available from The Ports Collection as <package
>       role="port">dns/bind99</package> or <package
>       role="port">dns/bind98</package>.  In &os; 9 and lower,
>       <acronym>BIND</acronym> is included in &os; Base.  The &os;
>       version provides enhanced security features, a new file system
>       layout, and automated &man.chroot.8; configuration.
>       <acronym>BIND</acronym> is maintained by the <link
> 	xlink:href="https://www.isc.org/">Internet Systems
> 	Consortium</link>.</para>
> 
>     <indexterm><primary>resolver</primary></indexterm>
>     <indexterm><primary>reverse
>       <acronym>DNS</acronym></primary></indexterm>
>     <indexterm><primary>root zone</primary></indexterm>
> 
>     <para>The following table describes some of the terms associated
>       with <acronym>DNS</acronym>:</para>
> 
>     <table frame="none" pgwide="1">
>       <title><acronym>DNS</acronym> Terminology</title>
> 
>       <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 <acronym>IP</acronym>
> 	      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>
>     </table>
> 
>     <indexterm>
>       <primary>zones</primary>
>       <secondary>examples</secondary>
>     </indexterm>
> 
>     <para>Examples of zones:</para>
> 
>     <itemizedlist>
>       <listitem>
> 	<para><systemitem>.</systemitem> is how the root zone is
> 	  usually referred to in documentation.</para>
>       </listitem>
> 
>       <listitem>
> 	<para><systemitem>org.</systemitem> is a Top Level Domain
> 	  (<acronym>TLD</acronym>) under the root zone.</para>
>       </listitem>
> 
>       <listitem>
> 	<para><systemitem
> 	    class="fqdomainname">example.org.</systemitem> is a zone
> 	  under the <systemitem>org.</systemitem>
> 	  <acronym>TLD</acronym>.</para>
>       </listitem>
> 
>       <listitem>
> 	<para><systemitem>1.168.192.in-addr.arpa</systemitem> is a
> 	  zone referencing all <acronym>IP</acronym> addresses which
> 	  fall under the <systemitem
> 	      class="ipaddress">192.168.1.*</systemitem>
> 	  <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, <systemitem
> 	class="fqdomainname">example.org.</systemitem> is more
>       specific than <systemitem>org.</systemitem>, as
>       <systemitem>org.</systemitem> is more specific than the root
>       zone.  The layout of each part of a hostname is much like a file
>       system: the <filename>/dev</filename> directory falls within the
>       root, and so on.</para>
> 
>     <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 <systemitem
> 	      class="fqdomainname">example.org</systemitem>, 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 <systemitem
> 	  class="fqdomainname">www.FreeBSD.org</systemitem>, 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><acronym>DNS</acronym> Server Configuration in &os; 10.0
> 	and Later</title>
> 
>       <para>In &os; 10.0, <application>BIND</application> has been
> 	replaced with <application>Unbound</application>.
> 	<application>Unbound</application> is a validating caching
> 	resolver only.  If an authoritative server is needed, many are
> 	available from the Ports Collection.</para>
> 
>       <para><application>Unbound</application> is provided in the &os;
> 	base system.  By default, it will provide
> 	<acronym>DNS</acronym> resolution to the local machine only.
> 	While the base system package can be configured to provide
> 	resolution services beyond the local machine, it is
> 	recommended that such requirements be addressed by installing
> 	<application>Unbound</application> from the &os; Ports
> 	Collection.</para>
> 
>       <para>To enable <application>Unbound</application>, add the
> 	following to <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>local_unbound_enable="YES"</programlisting>
> 
>       <para>Any existing nameservers in
> 	<filename>/etc/resolv.conf</filename> will be configured as
> 	forwarders in the new <application>Unbound</application>
> 	configuration.</para>
> 
>       <note>
> 	<para>If any of the listed nameservers do not support
> 	  <acronym>DNSSEC</acronym>, local <acronym>DNS</acronym>
> 	  resolution will fail.  Be sure to test each nameserver and
> 	  remove any that fail the test.  The following command will
> 	  show the trust tree or a failure for a nameserver running on
> 	  <systemitem
> 	    class="ipaddress">192.168.1.1</systemitem>:</para>
>       </note>
> 
>       <screen>&prompt.user; <userinput>drill -S FreeBSD.org @<replaceable>192.168.1.1</replaceable></userinput></screen>
> 
>       <para>Once each nameserver is confirmed to support
> 	<acronym>DNSSEC</acronym>, start
> 	<application>Unbound</application>:</para>
> 
>       <screen>&prompt.root; <userinput>service local_unbound onestart</userinput></screen>
> 
>       <para>This will take care of updating
> 	<filename>/etc/resolv.conf</filename> so that queries for
> 	<acronym>DNSSEC</acronym> secured domains will now work.  For
> 	example, run the following to validate the FreeBSD.org
> 	<acronym>DNSSEC</acronym> trust tree:</para>
> 
>       <screen>&prompt.user; <userinput>drill -S FreeBSD.org</userinput>
> ;; Number of trusted keys: 1
> ;; Chasing: freebsd.org. A
> 
> DNSSEC Trust tree:
> freebsd.org. (A)
> |---freebsd.org. (DNSKEY keytag: 36786 alg: 8 flags: 256)
>     |---freebsd.org. (DNSKEY keytag: 32659 alg: 8 flags: 257)
>     |---freebsd.org. (DS keytag: 32659 digest type: 2)
>         |---org. (DNSKEY keytag: 49587 alg: 7 flags: 256)
>             |---org. (DNSKEY keytag: 9795 alg: 7 flags: 257)
>             |---org. (DNSKEY keytag: 21366 alg: 7 flags: 257)
>             |---org. (DS keytag: 21366 digest type: 1)
>             |   |---. (DNSKEY keytag: 40926 alg: 8 flags: 256)
>             |       |---. (DNSKEY keytag: 19036 alg: 8 flags: 257)
>             |---org. (DS keytag: 21366 digest type: 2)
>                 |---. (DNSKEY keytag: 40926 alg: 8 flags: 256)
>                     |---. (DNSKEY keytag: 19036 alg: 8 flags: 257)
> ;; Chase successful</screen>
>     </sect2>
> 
>     <sect2>
>       <title>DNS Server Configuration in &os;
> 	9.<replaceable>X</replaceable></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>/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>master</filename>,
> 	<filename>slave</filename>, or
> 	<filename>dynamic</filename> subdirectories
> 	of the <filename>/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>
> 
>       <sect3>
> 	<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>service 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 many configuration options for
> 	  <filename>/etc/namedb/named.conf</filename> that are beyond
> 	  the scope of this document.  Other startup options for
> 	  <application>named</application> on &os; can be found in the
> 	  <literal>named_<replaceable>*</replaceable></literal> flags
> 	  in <filename>/etc/defaults/rc.conf</filename> and in
> 	  &man.rc.conf.5;.  The <xref linkend="configtuning-rcd"/>
> 	  section is also a good read.</para>
>       </sect3>
> 
>       <sect3>
> 	<title>Configuration Files</title>
> 
> 	<indexterm>
> 	  <primary>BIND</primary>
> 	  <secondary>configuration files</secondary>
> 	</indexterm>
> 
> 	<para>Configuration files for <application>named</application>
> 	  currently reside in <filename>/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>
> 
> 	<sect4>
> 	  <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 have a DNS server around at your upstream provider, enter
>+// 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><systemitem class="ipaddress">127.0.0.1</systemitem>
> 	      will <emphasis>not</emphasis> work here.  Change this
> 	      <acronym>IP</acronym> address to a name server at the
> 	      uplink.</para>
> 	  </warning>
> 
> 	  <programlisting>	/*
> 	   Modern versions of BIND use a random <acronym>UDP</acronym> 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, do not forget to enter 127.0.0.1
>+// 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: Do not blindly enable the examples below. :-)  Use actual names
>+// 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
> 	    <systemitem class="fqdomainname">example.org</systemitem>
> 	    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>
> 	</sect4>
> 
> 	<sect4>
> 	  <title>Zone Files</title>
> 
> 	  <indexterm>
> 	    <primary>BIND</primary>
> 	    <secondary>zone files</secondary>
> 	  </indexterm>
> 
> 	  <para>An example master zone file for
> 	    <systemitem class="fqdomainname">example.org</systemitem>
> 	    (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><acronym>DNS</acronym></primary>
> 	    <secondary>records</secondary>
> 	  </indexterm>
> 
> 	  <para>The most commonly used <acronym>DNS</acronym>
> 	    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
> 		  <acronym>DNS</acronym>)</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><systemitem
> 		  class="fqdomainname">example.org.</systemitem></term>
> 
> 	      <listitem>
> 		<para>the domain name, also the origin for this
> 		  zone file.</para>
> 	      </listitem>
> 	    </varlistentry>
> 
> 	    <varlistentry>
> 	      <term><systemitem
> 		  class="fqdomainname">ns1.example.org.</systemitem></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,
> 	    <systemitem
> 	      class="fqdomainname">ns1.example.org</systemitem> would
> 	    resolve to <systemitem
> 	      class="ipaddress">192.168.1.2</systemitem>.</para>
> 
> 	  <programlisting>                IN      A       192.168.1.1</programlisting>
> 
> 	  <para>This line assigns <acronym>IP</acronym> address
> 	    <systemitem class="ipaddress">192.168.1.1</systemitem> to
> 	    the current origin, in this case <systemitem
> 	      class="fqdomainname">example.org</systemitem>.</para>
> 
> 	  <programlisting>www             IN CNAME        @</programlisting>
> 
> 	  <para>The canonical name record is usually used for giving
> 	    aliases to a machine.  In the example,
> 	    <systemitem>www</systemitem> is aliased to the
> 	    <quote>master</quote> machine whose name happens to be the
> 	    same as the domain name
> 	    <systemitem class="fqdomainname">example.org</systemitem>
> 	    (<systemitem class="ipaddress">192.168.1.1</systemitem>).
> 	    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.
> 	    <systemitem
> 	      class="fqdomainname">mail.example.org</systemitem> 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
> 	    <systemitem class="fqdomainname">example.org</systemitem>
> 	    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
> 	    <acronym>DNS</acronym>), 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 <acronym>IP</acronym>
> 	    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>
> 	</sect4>
>       </sect3>
> 
>       <sect3>
> 	<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>
>       </sect3>
> 
>       <sect3>
> 	<title><acronym role="Domain Name Security
> 	    Extensions">DNSSEC</acronym></title>
> 
> 	<indexterm>
> 	  <primary>BIND</primary>
> 	  <secondary><acronym>DNS</acronym> 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
> 	  <systemitem class="fqdomainname">example.net</systemitem>
> 	  instead of
> 	  <systemitem class="fqdomainname">example.com</systemitem>.
> 	  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>
> 
> 	<sect4>
> 	  <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 <link
> 	      xlink:href="https://data.iana.org/root-anchors/root-anchors.xml">https://data.iana.org/root-anchors/root-anchors.xml</link>.
> 	    To be absolutely sure that the key has not been tampered
>-	    with the data in the <acronym>XML</acronym> file should be
>-	    verified using a proper <acronym>PGP</acronym> signature.</para>
>-	    
>+	    with the data in the <acronym>XML</acronym> file can be
>+	    verified using the <acronym>PGP</acronym> signature in
>+	    <link
>+	      xlink:href="https://data.iana.org/root-anchors/root-anchors.asc">https://data.iana.org/root-anchors/root-anchors.asc</link>.</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>
> 	</sect4>
> 
> 	<sect4 xml: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 <link
> 	      xlink:href="http://tools.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym>
> 	      4641: <acronym>DNSSEC</acronym> Operational
> 	      Practices</link>.  Practices regarding the root zone can
> 	    be found in <link
> 	      xlink:href="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</link> and <link
> 	      xlink:href="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</link>.  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
> 	    <systemitem class="fqdomainname">example.com</systemitem>
> 	    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
> 	    <systemitem class="fqdomainname">example.com</systemitem>,
> 	    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
> 	    <systemitem class="fqdomainname">example.com</systemitem>,
> 	    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 <link
> 	      xlink:href="http://www.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym>
> 	      4641: <acronym>DNSSEC</acronym> Operational
> 	      practices</link>.</para>
> 	</sect4>
> 
> 	<sect4>
> 	  <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 <systemitem
> 	      class="fqdomainname">example.com</systemitem>, 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>
> 	</sect4>
>       </sect3>
> 
>       <sect3>
> 	<title>Security</title>
> 
> 	<para>Although BIND is the most common implementation of
> 	  <acronym>DNS</acronym>, 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
> 	  <link xlink:href="http://www.cert.org/">CERT</link>'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>
>       </sect3>
> 
>       <sect3 xml: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.1; &man.dnssec-signzone.8;
> 	  &man.dnssec-keygen.8;</para>
> 
> 	<itemizedlist>
> 	  <listitem>
> 	    <para><link
> 		xlink:href="https://www.isc.org/software/bind">Official
> 		ISC BIND Page</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="https://www.isc.org/software/guild">Official
> 		ISC BIND Forum</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://www.oreilly.com/catalog/dns5/">O'Reilly
> 		<acronym>DNS</acronym> and BIND 5th
> 		Edition</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://www.root-dnssec.org/documentation/">Root
> 		<acronym>DNSSEC</acronym></link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html"><acronym>DNSSEC</acronym>
> 		Trust Anchor Publication for the Root
> 		Zone</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc1034">RFC1034
> 		- Domain Names - Concepts and Facilities</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc1035">RFC1035
> 		- Domain Names - Implementation and
> 		Specification</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc4033">RFC4033
> 		- <acronym>DNS</acronym> Security Introduction and
> 		Requirements</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc4034">RFC4034
> 		- Resource Records for the <acronym>DNS</acronym>
> 		Security Extensions</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc4035">RFC4035
> 		- Protocol Modifications for the
> 		<acronym>DNS</acronym> Security
> 		Extensions</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc4641">RFC4641
> 		- DNSSEC Operational Practices</link></para>
> 	  </listitem>
> 
> 	  <listitem>
> 	    <para><link
> 		xlink:href="http://tools.ietf.org/html/rfc5011">RFC
> 		5011 - Automated Updates of <acronym>DNS</acronym>
> 		Security (<acronym>DNSSEC</acronym>
> 		Trust Anchors</link></para>
> 	  </listitem>
> 	</itemizedlist>
>       </sect3>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-apache">
>     <info>
>       <title>Apache HTTP Server</title>
> 
>       <authorgroup>
> 	<author>
> 	  <personname>
> 	    <firstname>Murray</firstname>
> 	    <surname>Stokely</surname>
> 	  </personname>
> 	  <contrib>Contributed by </contrib>
> 	</author>
>       </authorgroup>
>     </info>
> 
>     <indexterm><primary>web servers</primary>
>       <secondary>setting up</secondary></indexterm>
>     <indexterm><primary>Apache</primary></indexterm>
> 
>     <para>The open source
>       <application>Apache HTTP Server</application> is the most widely
>       used web server.  &os; does not install this web server by
>       default, but it can be installed from the
>       <package>www/apache24</package> package or port.</para>
> 
>     <para>This section summarizes how to configure and start version
>       2.<replaceable>x</replaceable> of the <application>Apache HTTP
> 	Server</application> on &os;.  For more detailed information
>       about <application>Apache</application>&nbsp;2.X and its
>       configuration directives, refer to <link
> 	xlink:href="http://httpd.apache.org/">httpd.apache.org</link>.</para>
> 
>     <sect2>
>       <title>Configuring and Starting Apache</title>
> 
>       <indexterm><primary>Apache</primary>
> 	<secondary>configuration file</secondary></indexterm>
> 
>       <para>In &os;, the main <application>Apache HTTP
> 	  Server</application> configuration file is installed as
> 	<filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>,
> 	where <replaceable>x</replaceable> represents the version
> 	number.  This <acronym>ASCII</acronym> text file begins
> 	comment lines with a <literal>#</literal>.  The most
> 	frequently modified directives are:</para>
> 
>       <variablelist>
> 	<varlistentry>
> 	  <term><literal>ServerRoot "/usr/local"</literal></term>
> 
> 	  <listitem>
> 	    <para>Specifies the default directory hierarchy for the
> 	      <application>Apache</application> installation.
> 	      Binaries are stored in the <filename>bin</filename> and
> 	      <filename>sbin</filename> subdirectories of the server
> 	      root and configuration files are stored in the <filename
> 		>etc/apache2<replaceable>x</replaceable></filename>
> 	      subdirectory.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term><literal>ServerAdmin you@example.com</literal></term>
> 
> 	  <listitem>
> 	    <para>Change this to the email address to receive problems
> 	      with the server.  This address also appears on some
> 	      server-generated pages, such as error documents.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term><literal>ServerName
> 	      www.example.com:80</literal></term>
> 
> 	  <listitem>
> 	    <para>Allows an administrator to set a hostname which is
> 	      sent back to clients for the server.  For example,
> 	      <systemitem>www</systemitem> can be used instead of the
> 	      actual hostname.  If the system does not have a
> 	      registered <acronym>DNS</acronym> name, enter its
> 	      <acronym>IP</acronym> address instead.  If the server
> 	      will listen on an alternate report, change
> 	      <literal>80</literal> to the alternate port
> 	      number.</para>
> 	  </listitem>
> 	</varlistentry>
> 
> 	<varlistentry>
> 	  <term><literal>DocumentRoot
> 	    "/usr/local/www/apache2<replaceable>x</replaceable>/data"</literal></term>
> 
> 	  <listitem>
> 	    <para>The directory where documents will be served from.
> 	      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 a backup copy of the
> 	default <application>Apache</application> configuration file
> 	before making changes.  When the configuration of
> 	<application>Apache</application> is complete, save the file
> 	and verify the configuration using
> 	<command>apachectl</command>.  Running <command>apachectl
> 	  configtest</command> should return <literal>Syntax
> 	  OK</literal>.</para>
> 
>       <indexterm><primary>Apache</primary>
> 	<secondary>starting or stopping</secondary></indexterm>
> 
>       <para>To launch <application>Apache</application> at system
> 	startup, add the following line to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>apache<replaceable>24</replaceable>_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> to specify the needed
> 	flags:</para>
> 
>       <programlisting>apache<replaceable>24</replaceable>_flags=""</programlisting>
> 
>       <para>If <application>apachectl</application> does not report
> 	configuration errors, start <command>httpd</command>
> 	now:</para>
> 
>       <screen>&prompt.root; <userinput>service apache<replaceable>24</replaceable> start</userinput></screen>
> 
>       <para>The <command>httpd</command> service can be tested by
> 	entering
> 	<literal>http://<replaceable>localhost</replaceable></literal>
> 	in a web browser, replacing
> 	<replaceable>localhost</replaceable> with the fully-qualified
> 	domain name of the machine running <command>httpd</command>.
> 	The default web page that is displayed is
> 	<filename>/usr/local/www/apache<replaceable>24</replaceable>/data/index.html</filename>.</para>
> 
>       <para>The <application>Apache</application> configuration can be
> 	tested for errors after making subsequent configuration
> 	changes while <command>httpd</command> is running using the
> 	following command:</para>
> 
>       <screen>&prompt.root; <userinput>service apache<replaceable>24</replaceable> configtest</userinput></screen>
> 
>       <note>
> 	<para>It is important to note that
> 	  <literal>configtest</literal> is not an &man.rc.8; standard,
> 	  and should not be expected to work for all startup
> 	  scripts.</para>
>       </note>
>     </sect2>
> 
>     <sect2>
>       <title>Virtual Hosting</title>
> 
>       <para>Virtual hosting allows multiple websites to run on one
> 	<application>Apache</application> server.  The virtual hosts
> 	can be <firstterm>IP-based</firstterm> or
> 	<firstterm>name-based</firstterm>.
> 	<acronym>IP</acronym>-based virtual hosting uses a different
> 	<acronym>IP</acronym> address for each website.  Name-based
> 	virtual hosting uses the clients HTTP/1.1 headers to figure
> 	out the hostname, which allows the websites to share the same
> 	<acronym>IP</acronym> address.</para>
> 
>       <para>To setup <application>Apache</application> to use
> 	name-based virtual hosting, add a
> 	<literal>VirtualHost</literal> block for each website.  For
> 	example, for the webserver named <systemitem
> 	  class="fqdomainname">www.domain.tld</systemitem> with a
> 	virtual domain of <systemitem
> 	  class="fqdomainname">www.someotherdomain.tld</systemitem>,
> 	add the following entries to
> 	<filename>httpd.conf</filename>:</para>
> 
>       <programlisting>&lt;VirtualHost *&gt;
>     ServerName <replaceable>www.domain.tld</replaceable>
>     DocumentRoot <replaceable>/www/domain.tld</replaceable>
> &lt;/VirtualHost&gt;
> 
> &lt;VirtualHost *&gt;
>     ServerName <replaceable>www.someotherdomain.tld</replaceable>
>     DocumentRoot <replaceable>/www/someotherdomain.tld</replaceable>
> &lt;/VirtualHost&gt;</programlisting>
> 
>       <para>For each virtual host, replace the values for
> 	<literal>ServerName</literal> and
> 	<literal>DocumentRoot</literal> with the values to be
> 	used.</para>
> 
>       <para>For more information about setting up virtual hosts,
> 	consult the official <application>Apache</application>
> 	documentation at: <uri
> 	  xlink:href="http://httpd.apache.org/docs/vhosts/">http://httpd.apache.org/docs/vhosts/</uri>.</para>
>     </sect2>
> 
>     <sect2>
>       <title>Apache Modules</title>
> 
>       <indexterm><primary>Apache</primary>
> 	<secondary>modules</secondary></indexterm>
> 
>       <para><application>Apache</application> uses modules to augment
> 	the functionality provided by the basic server.  Refer to <uri
> 	  xlink:href="http://httpd.apache.org/docs/current/mod/">http://httpd.apache.org/docs/current/mod/</uri>
> 	for a complete listing of and the configuration details for
> 	the available modules.</para>
> 
>       <para>In &os;, some modules can be compiled with the
> 	<package>www/apache24</package> port.  Type <command>make
> 	  config</command> within
> 	<filename>/usr/ports/www/apache24</filename> to see which
> 	modules are available and which are enabled by default.  If
> 	the module is not compiled with the port, the &os; Ports
> 	Collection provides an easy way to install many modules.  This
> 	section describes three of the most commonly used
> 	modules.</para>
> 
>       <sect3>
> 	<title><filename>mod_ssl</filename></title>
> 
> 	<indexterm>
> 	  <primary>web servers</primary>
> 	  <secondary>secure</secondary>
> 	</indexterm>
> 	<indexterm><primary>SSL</primary></indexterm>
> 	<indexterm><primary>cryptography</primary></indexterm>
> 
> 	<para>The <filename>mod_ssl</filename> module uses the
> 	  <application>OpenSSL</application> library to provide strong
> 	  cryptography via the Secure Sockets Layer
> 	  (<acronym>SSLv3</acronym>) and Transport Layer Security
> 	  (<acronym>TLSv1</acronym>) protocols.  This module provides
> 	  everything necessary to request a signed certificate from a
> 	  trusted certificate signing authority to run a secure web
> 	  server on &os;.</para>
> 
> 	<para>In &os;, <filename>mod_ssl</filename> module is enabled
> 	  by default in both the package and the port.  The available
> 	  configuration directives are explained at <uri
> 	    xlink:href="http://httpd.apache.org/docs/current/mod/mod_ssl.html">http://httpd.apache.org/docs/current/mod/mod_ssl.html</uri>.</para>
>       </sect3>
> 
>       <sect3>
> 	<title><filename>mod_perl</filename></title>
> 
> 	<indexterm>
> 	  <primary>mod_perl</primary>
> 	  <secondary>Perl</secondary>
> 	</indexterm>
> 
> 	<para>The
> 	  <filename>mod_perl</filename> module makes it possible to
> 	  write <application>Apache</application> modules in
> 	  <application>Perl</application>.  In addition, the
> 	  persistent interpreter embedded in the server avoids the
> 	  overhead of starting an external interpreter and the penalty
> 	  of <application>Perl</application> start-up time.</para>
> 
> 	<para>The <filename>mod_perl</filename> can be installed using
> 	  the <package>www/mod_perl2</package> package or port.
> 	  Documentation for using this module can be found at <uri
> 	    xlink:href="http://perl.apache.org/docs/2.0/index.html">http://perl.apache.org/docs/2.0/index.html</uri>.</para>
>       </sect3>
> 
>       <sect3>
> 	<info>
> 	  <title><filename>mod_php</filename></title>
> 
> 	  <authorgroup>
> 	    <author>
> 	      <personname>
> 		<firstname>Tom</firstname>
> 		<surname>Rhodes</surname>
> 	      </personname>
> 	      <contrib>Written by </contrib>
> 	    </author>
> 	  </authorgroup>
> 	</info>
> 
> 	<indexterm>
> 	  <primary>mod_php</primary>
> 	  <secondary>PHP</secondary>
> 	</indexterm>
> 
> 	<para><firstterm>PHP: Hypertext Preprocessor</firstterm>
> 	  (<acronym>PHP</acronym>) 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 <application>C</application>, &java;, and
> 	  <application>Perl</application> 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, install the
> 	  <package>www/mod_php56</package> package or port.  This will
> 	  install and configure the modules required to support
> 	  dynamic <acronym>PHP</acronym> applications.  The
> 	  installation will automatically add this line to
> 	  <filename>/usr/local/etc/apache2<replaceable>4</replaceable>/httpd.conf</filename>:</para>
> 
> 	<programlisting>LoadModule php5_module        libexec/apache24/libphp5.so</programlisting>
> 
> 
> 
> 	<para>Then, perform a graceful restart to load the
> 	  <acronym>PHP</acronym> module:</para>
> 
> 	<screen>&prompt.root; <userinput>apachectl graceful</userinput></screen>
> 
> 	<para>The <acronym>PHP</acronym> support provided by
> 	  <package>www/mod_php56</package> is limited.  Additional
> 	  support can be installed using the
> 	  <package>lang/php56-extensions</package> port which provides
> 	  a menu driven interface to the available
> 	  <acronym>PHP</acronym> extensions.</para>
> 
> 	<para>Alternatively, individual extensions can be installed
> 	  using the appropriate port.  For instance, to add
> 	  <acronym>PHP</acronym> support for the
> 	  <application>MySQL</application> database server, install
> 	  <package>databases/php56-mysql</package>.</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>
> 
>     <sect2>
>       <title>Dynamic Websites</title>
> 
>       <indexterm>
> 	<primary>web servers</primary>
> 	<secondary>dynamic</secondary>
>       </indexterm>
> 
>       <para>In addition to <application>mod_perl</application> and
> 	<application>mod_php</application>, other languages are
> 	available for creating dynamic web content.  These include
> 	<application>Django</application> and
> 	<application>Ruby on Rails</application>.</para>
> 
>       <sect3>
> 	<title>Django</title>
> 
> 	<indexterm><primary>Python</primary></indexterm>
> 	<indexterm><primary>Django</primary></indexterm>
> 
> 	<para><application>Django</application> 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 <application>Python</application> objects.  A rich
> 	  dynamic database-access <acronym>API</acronym> is provided
> 	  for those objects without the developer ever having to write
> 	  <acronym>SQL</acronym>.  It also provides an extensible
> 	  template system so that the logic of the application is
> 	  separated from the <acronym>HTML</acronym>
> 	  presentation.</para>
> 
> 	<para>Django depends on <filename>mod_python</filename>, and
> 	  an <acronym>SQL</acronym> database engine.  In &os;, the
> 	  <package>www/py-django</package> port automatically installs
> 	  <filename>mod_python</filename> and supports the
> 	  <application>PostgreSQL</application>,
> 	  <application>MySQL</application>, or
> 	  <application>SQLite</application> databases, with the
> 	  default being <application>SQLite</application>.  To change
> 	  the database engine, type <command>make config</command>
> 	  within <filename>/usr/ports/www/py-django</filename>, then
> 	  install the port.</para>
> 
> 	<para>Once <application>Django</application> is installed, the
> 	  application will need a project directory along with the
> 	  <application>Apache</application> configuration in order to
> 	  use the embedded <application>Python</application>
> 	  interpreter.  This interpreter is used to call the
> 	  application for specific <acronym>URL</acronym>s on the
> 	  site.</para>
> 
> 	<para>To configure <application>Apache</application> to pass
> 	  requests for certain <acronym>URL</acronym>s to the web
> 	  application, add the following to
> 	  <filename>httpd.conf</filename>, specifying the full path to
> 	  the project directory:</para>
> 
> 	<programlisting>&lt;Location "/"&gt;
>     SetHandler python-program
>     PythonPath "['<replaceable>/dir/to/the/django/packages/</replaceable>'] + sys.path"
>     PythonHandler django.core.handlers.modpython
>     SetEnv DJANGO_SETTINGS_MODULE mysite.settings
>     PythonAutoReload On
>     PythonDebug On
> &lt;/Location&gt;</programlisting>
> 
> 	<para>Refer to <uri
>-	    xlink:href="https://docs.djangoproject.com">https://docs.djangoproject.com</uri>
>+	    xlink:href="https://docs.djangoproject.com/en/1.6/">https://docs.djangoproject.com/en/1.6/</uri>
> 	  for more information on how to use
> 	  <application>Django</application>.</para>
>       </sect3>
> 
>       <sect3>
> 	<title>Ruby on Rails</title>
> 
> 	<indexterm><primary>Ruby on Rails</primary></indexterm>
> 
> 	<para><application>Ruby on Rails</application> is another open
> 	  source web framework that provides a full development stack.
> 	  It is optimized to make web developers more productive and
> 	  capable of writing powerful applications quickly.  On &os;,
> 	  it can be installed using the
> 	  <package>www/rubygem-rails</package> package or port.</para>
> 
> 	<para>Refer to <uri
>-	    xlink:href="http://guides.rubyonrails.org">http://guides.rubyonrails.org</uri>
>+	    xlink:href="http://rubyonrails.org/documentation">http://rubyonrails.org/documentation</uri>
> 	  for more information on how to use <application>Ruby on
> 	    Rails</application>.</para>
>       </sect3>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-ftp">
>     
>     <title>File Transfer Protocol (<acronym>FTP</acronym>)</title>
> 
>     <indexterm><primary><acronym>FTP</acronym>
> 	servers</primary></indexterm>
> 
>     <para>The File Transfer Protocol (<acronym>FTP</acronym>) provides
>       users with a simple way to transfer files to and from an
>       <acronym>FTP</acronym> server.  &os; includes
>       <acronym>FTP</acronym> server software,
>       <application>ftpd</application>, in the base system.</para>
> 
>     <para>&os; provides several configuration files for controlling
>       access to the <acronym>FTP</acronym> server.  This section
>       summarizes these files.  Refer to &man.ftpd.8; for more details
>       about the built-in <acronym>FTP</acronym> server.</para>
> 
>     <sect2>
>       <title>Configuration</title>
> 
>       <para>The most important configuration step is deciding which
> 	accounts will be allowed access to the <acronym>FTP</acronym>
> 	server.  A &os; system has a number of system accounts which
> 	should not be allowed <acronym>FTP</acronym> access.  The list
> 	of users disallowed any <acronym>FTP</acronym> access can be
> 	found in <filename>/etc/ftpusers</filename>.  By default, it
> 	includes system accounts.  Additional users that should not be
> 	allowed access to <acronym>FTP</acronym> can be added.</para>
> 
>       <para>In some cases it may be desirable to restrict the access
> 	of some users without preventing them completely from using
> 	<acronym>FTP</acronym>.  This can be accomplished be creating
> 	<filename>/etc/ftpchroot</filename> as described in
> 	&man.ftpchroot.5;.  This file lists users and groups subject
> 	to <acronym>FTP</acronym> access restrictions.</para>
> 
>       <indexterm>
> 	<primary><acronym>FTP</acronym></primary>
> 	<secondary>anonymous</secondary>
>       </indexterm>
> 
>       <para>To enable anonymous <acronym>FTP</acronym> access to the
> 	server, create a user named <systemitem
> 	  class="username">ftp</systemitem> on the &os; system.  Users
> 	will then be able to log on to the
> 	<acronym>FTP</acronym> server with a username of
> 	<systemitem class="username">ftp</systemitem> or <systemitem
> 	  class="username">anonymous</systemitem>.  When prompted for
> 	the password, any input will be accepted, but by convention,
> 	an email address should be used as the password.  The
> 	<acronym>FTP</acronym> server will call &man.chroot.2; when an
> 	anonymous user logs in, to restrict access to only the home
> 	directory of the <systemitem
> 	  class="username">ftp</systemitem> user.</para>
> 
>       <para>There are two text files that can be created to specify
> 	welcome messages to be displayed to <acronym>FTP</acronym>
> 	clients.  The contents of
> 	<filename>/etc/ftpwelcome</filename> will be displayed to
> 	users before they reach the login prompt.  After a successful
> 	login, the contents of
> 	<filename>/etc/ftpmotd</filename> will be displayed.  Note
> 	that the path to this file is relative to the login
> 	environment, so the contents of
> 	<filename>~ftp/etc/ftpmotd</filename> would be displayed for
> 	anonymous users.</para>
> 
>       <para>Once the <acronym>FTP</acronym> server has been
> 	configured, set the appropriate variable in
> 	<filename>/etc/rc.conf</filename> to start the service during
> 	boot:</para>
> 
>       <programlisting>ftpd_enable="YES"</programlisting>
> 
>       <para>To start the service now:</para>
> 
>       <screen>&prompt.root; <userinput>service ftpd start</userinput></screen>
> 
>       <para>Test the connection to the <acronym>FTP</acronym> server
> 	by typing:</para>
> 
>       <screen>&prompt.user; <userinput>ftp localhost</userinput></screen>
> 
>       <indexterm><primary>syslog</primary></indexterm>
>       <indexterm><primary>log files</primary>
> 	<secondary><acronym>FTP</acronym></secondary></indexterm>
> 
>       <para>The <application>ftpd</application> daemon uses
> 	&man.syslog.3; to log messages.  By default, the system log
> 	daemon will write messages related to <acronym>FTP</acronym>
> 	in <filename>/var/log/xferlog</filename>.  The location of
> 	the <acronym>FTP</acronym> 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><acronym>FTP</acronym></primary>
> 	<secondary>anonymous</secondary>
>       </indexterm>
> 
>       <note>
> 	<para>Be aware of the potential problems involved with running
> 	  an anonymous <acronym>FTP</acronym> server.  In particular,
> 	  think twice about allowing anonymous users to upload files.
> 	  It may turn out that the <acronym>FTP</acronym> site becomes
> 	  a forum for the trade of unlicensed commercial software or
> 	  worse.  If anonymous <acronym>FTP</acronym> uploads are
> 	  required, then verify the permissions so that these files
>-	  cannot be read by other anonymous users until they have
>+	  can not be read by other anonymous users until they have
> 	  been reviewed by an administrator.</para>
>       </note>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-samba">
>     
>     <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>
> 
>     <para><application>Samba</application> is a popular open source
>       software package that provides file and print services using the
>       <acronym>SMB/CIFS</acronym> protocol.  This protocol is built
>       into &microsoft.windows; systems.  It can be added to
>       non-&microsoft.windows; systems by installing the
>       <application>Samba</application> client libraries.  The protocol
>       allows clients to access shared data and printers.  These shares
>       can be mapped as a local disk drive and shared printers can be
>       used as if they were local printers.</para>
> 
>     <para>On &os;, the <application>Samba</application> client
>       libraries can be installed using the
>       <package>net/samba-smbclient</package> port or package.  The
>       client provides the ability for a &os; system to access
>       <acronym>SMB/CIFS</acronym> shares in a &microsoft.windows;
>       network.</para>
> 
>     <para>A &os; system can also be configured to act as a
>       <application>Samba</application> server by installing the
>       <package>net/samba43</package> port or package.  This allows the
>-      administrator to create <acronym>SMB</acronym>/<acronym>CIFS</acronym>
>-      shares on
>+      administrator to create <acronym>SMB</acronym>/<acronym>CIFS</acronym>shares on
>       the &os; system which can be accessed by clients running
>       &microsoft.windows; or the <application>Samba</application>
>       client libraries.</para>
> 
>     <sect2>
>       <title>Server Configuration</title>
> 
>       <para><application>Samba</application> is configured in
> 	<filename>/usr/local/etc/smb4.conf</filename>.  This file must
> 	be created before <application>Samba</application>
> 	can be used.</para>
> 
>       <para>A simple <filename>smb4.conf</filename> to share
> 	directories and printers  with &windows; clients in a
> 	workgroup is shown here.  For more complex setups
>-	involving LDAP or Active Directory, it is easier to use
>-	&man.samba-tool.8; to create the initial
>+	involving <acronym>LDAP</acronym> or Active Directory, it is
>+	easier to use &man.samba-tool.8; to create the initial
> 	<filename>smb4.conf</filename>.</para>
> 
>       <programlisting>[global]
> workgroup = WORKGROUP
> server string = Samba Server Version %v
> netbios name = ExampleMachine
> wins support = Yes
> security = user
> passdb backend = tdbsam
> 
> # Example: share /usr/src accessible only to 'developer' user
> [src]
> path = /usr/src
> valid users = developer
> writable  = yes
> browsable = yes
> read only = no
> guest ok = no
> public = no
> create mask = 0666
> directory mask = 0755</programlisting>
> 
>       <sect3>
> 	<title>Global Settings</title>
> 
> 	<para>Settings that describe the network are added in
> 	  <filename>/usr/local/etc/smb4.conf</filename>:</para>
> 
> 	<variablelist>
> 	  <varlistentry>
> 	    <term><literal>workgroup</literal></term>
> 
> 	    <listitem>
> 	      <para>The name of the workgroup to be served.</para>
> 	    </listitem>
> 	  </varlistentry>
> 
> 	  <varlistentry>
> 	    <term><literal>netbios name</literal></term>
> 
> 	    <listitem>
> 	      <para>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 <acronym>DNS</acronym> name.</para>
> 	    </listitem>
> 	  </varlistentry>
> 
> 	  <varlistentry>
> 	    <term><literal>server string</literal></term>
> 
> 	    <listitem>
> 	      <para>The string that will be displayed in the output of
> 		<command>net view</command> and some other
> 		networking tools that seek to display descriptive text
> 		about the server.</para>
> 	    </listitem>
> 	  </varlistentry>
> 
> 	  <varlistentry>
> 	    <term><literal>wins support</literal></term>
> 
> 	    <listitem>
> 	      <para>Whether <application>Samba</application> will
> 		act as a <acronym>WINS</acronym> server.  Do not
> 		enable support for <acronym>WINS</acronym> on more than
> 		one server on the network.</para>
> 	    </listitem>
> 	  </varlistentry>
> 	</variablelist>
>       </sect3>
> 
>       <sect3>
> 	<title>Security Settings</title>
> 
> 	<para>The most important settings in
> 	  <filename>/usr/local/etc/smb4.conf</filename> are the
> 	  security model and the backend password format.  These
> 	  directives control the options:</para>
> 
> 	<variablelist>
> 	  <varlistentry>
> 	    <term><literal>security</literal></term>
> 
> 	    <listitem>
> 	      <para>The most common settings are
> 		<literal>security = share</literal> and
> 		<literal>security = user</literal>.  If the clients
> 		use usernames that are the same as their usernames on
> 		the &os; machine, user level security should be
> 		used.  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, clients 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.  Clients may
> 		be authenticated with LDAP, NIS+, an SQL database,
> 		or a modified password file.  The recommended
> 		authentication method, <literal>tdbsam</literal>,
> 		is ideal for simple networks and is covered here.
> 		For larger or more complex networks,
> 		<literal>ldapsam</literal> is recommended.
> 		<literal>smbpasswd</literal>
> 		was the former default and is now obsolete.</para>
> 	    </listitem>
> 	  </varlistentry>
> 	</variablelist>
> 
>       </sect3>
> 
>       <sect3>
> 	<title><application>Samba</application> Users</title>
> 
> 	<para>&os; user accounts must be mapped to the
> 	  <literal>SambaSAMAccount</literal> database for
> 	  &windows; clients to access the share.
> 	  Map existing &os; user accounts using
> 	  &man.pdbedit.8;:</para>
> 
> 	<screen>&prompt.root; <userinput>pdbedit -a <replaceable>username</replaceable></userinput></screen>
> 
> 	<para>This section has only mentioned the most commonly used
> 	  settings.  Refer to the <link
> 	    xlink:href="http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/">Official
> 	    Samba HOWTO</link> for additional information about the
> 	  available configuration options.</para>
>       </sect3>
>     </sect2>
> 
>     <sect2>
>       <title>Starting <application>Samba</application></title>
> 
>       <para>To enable <application>Samba</application> at boot time,
> 	add the following line to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>samba_enable="YES"</programlisting>
> 
>-      <para>To enable Samba4, use:</para>
>-      <programlisting>samba_server_enable="YES"</programlisting>
>-
>       <para>To start <application>Samba</application> now:</para>
> 
>       <screen>&prompt.root; <userinput>service samba start</userinput>
> Starting SAMBA: removing stale tdbs :
> Starting nmbd.
> Starting smbd.</screen>
> 
>       <para><application>Samba</application> consists of three
> 	separate daemons.  Both the <application>nmbd</application>
> 	and <application>smbd</application> daemons are started by
> 	<varname>samba_enable</varname>.  If winbind name resolution
>-	is also required, set:</para>
>+	is also required, set:</para> 
> 
> 	<programlisting>winbindd_enable="YES"</programlisting>
> 
>       <para><application>Samba</application> can be stopped at any
> 	time by typing:</para>
> 
>       <screen>&prompt.root; <userinput>service 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 configuration described here,
> 	refer to <uri
> 	  xlink:href="http://www.samba.org">http://www.samba.org</uri>.</para>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-ntp">
>     
>     <title>Clock Synchronization with NTP</title>
> 
>     <indexterm><primary>NTP</primary>
>       <secondary>ntpd</secondary>
>     </indexterm>
> 
>     <para>Over time, a computer's clock is prone to drift.   This is
>       problematic as many network services require the computers on a
>       network to share the same accurate time.  Accurate time is also
>       needed to ensure that file timestamps stay consistent.  The
>       Network Time Protocol (<acronym>NTP</acronym>) is one way to
>       provide clock accuracy in a network.</para>
> 
>     <para>&os; includes &man.ntpd.8; which can be configured to query
>       other <acronym>NTP</acronym> servers in order to synchronize the
>       clock on that machine or to provide time services to other
>       computers in the network.  The servers which are queried can be
>       local to the network or provided by an <acronym>ISP</acronym>.
>       In addition, an <link
> 	xlink:href="http://support.ntp.org/bin/view/Servers/WebHome">online
> 	list of publicly accessible <acronym>NTP</acronym>
>       servers</link> is available.  When choosing a public
>       <acronym>NTP</acronym> server, select one that is geographically
>       close and review its usage policy.</para>
> 
>     <para>Choosing several <acronym>NTP</acronym> servers is
>       recommended in case one of the servers becomes unreachable or
>       its clock proves unreliable.  As <application>ntpd</application>
>       receives responses, it favors reliable servers over the less
>       reliable ones.</para>
> 
>     <para>This section describes how to configure
>       <application>ntpd</application> on &os;.  Further documentation
>       can be found in <filename>/usr/share/doc/ntp/</filename> in HTML
>       format.</para>
> 
>     <sect2>
>       <title><acronym>NTP</acronym> Configuration</title>
> 
>       <indexterm><primary>NTP</primary>
> 	<secondary>ntp.conf</secondary>
>       </indexterm>
> 
>       <para>On &os;, the built-in <application>ntpd</application> can
> 	be used to synchronize a system's clock.  To enable
> 	<application>ntpd</application> at boot time, add
> 	<literal>ntpd_enable="YES"</literal> to
> 	<filename>/etc/rc.conf</filename>.  Additional variables can
> 	be specified in <filename>/etc/rc.conf</filename>.  Refer to
> 	&man.rc.conf.5; and &man.ntpd.8; for
> 	details.</para>
> 
>       <para>This application reads <filename>/etc/ntp.conf</filename>
> 	to determine which <acronym>NTP</acronym> servers to query.
> 	Here is a simple example of an
> 	<filename>/etc/ntp.conf</filename>:</para>
> 
>       <example>
> 	<title> Sample <filename>/etc/ntp.conf</filename></title>
> 
> 	<programlisting>server ntplocal.example.com prefer
> server timeserver.example.org
> server ntp2a.example.net
> 
> driftfile /var/db/ntp.drift</programlisting>
>       </example>
> 
>       <para>The format of this file is described in &man.ntp.conf.5;.
> 	The <literal>server</literal> option specifies which servers
> 	to query, with one server listed on each line.  If a server
> 	entry includes <literal>prefer</literal>, 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.  The
> 	<literal>prefer</literal> argument should only be used for
> 	<acronym>NTP</acronym> servers that are known to be highly
> 	accurate, such as those with special time monitoring
> 	hardware.</para>
> 
>       <para>The <literal>driftfile</literal> entry specifies which
> 	file is used to store the system clock's frequency offset.
> 	<application>ntpd</application> 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.  This
> 	file also stores information about previous responses
> 	from <acronym>NTP</acronym> servers.  Since this file contains
> 	internal information for <acronym>NTP</acronym>, it should not
> 	be modified.</para>
> 
>       <para>By default, an <acronym>NTP</acronym> server is accessible
> 	to any network host.  The <literal>restrict</literal> option
> 	in <filename>/etc/ntp.conf</filename> can be used to control
> 	which systems can access the server.  For example, to deny all
> 	machines from accessing the <acronym>NTP</acronym> 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 other
> 	  <acronym>NTP</acronym> servers.  If there is a need to
> 	  synchronize with an external <acronym>NTP</acronym> server,
> 	  allow only that specific server.  Refer to &man.ntp.conf.5;
> 	  for more information.</para>
>       </note>
> 
>       <para>To allow machines within the network to synchronize their
> 	clocks with the server, but ensure they are not allowed to
> 	configure the server or be used as peers to synchronize
> 	against, instead use:</para>
> 
>       <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting>
> 
>       <para>where <systemitem
> 	  class="ipaddress">192.168.1.0</systemitem> is the local
> 	network address and <systemitem
> 	  class="netmask">255.255.255.0</systemitem> is the network's
> 	subnet mask.</para>
> 
>       <para>Multiple <literal>restrict</literal> entries are
> 	supported.  For more details, refer to the <literal>Access
> 	  Control Support</literal> subsection of
> 	&man.ntp.conf.5;.</para>
> 
>       <para>Once <literal>ntpd_enable="YES"</literal> has been added
> 	to <filename>/etc/rc.conf</filename>,
> 	<application>ntpd</application> can be started now without
> 	rebooting the system by typing:</para>
> 
>       <screen>&prompt.root; <userinput>service ntpd start</userinput></screen>
>     </sect2>
> 
>     <sect2>
>       <title>Using <acronym>NTP</acronym> with a
> 	<acronym>PPP</acronym> Connection</title>
> 
>       <para><application>ntpd</application> does not need a permanent
> 	connection to the Internet to function properly.  However, if
> 	a <acronym>PPP</acronym> connection is configured to dial out
> 	on demand, <acronym>NTP</acronym> traffic should be prevented
> 	from triggering a dial out or keeping the connection alive.
> 	This can be configured with <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, refer to 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
> 	  the machine.</para>
>       </note>
>     </sect2>
>   </sect1>
> 
>   <sect1 xml:id="network-iscsi">
>     
> 
>     <title><acronym>iSCSI</acronym> Initiator and Target
>       Configuration</title>
> 
>     <para><acronym>iSCSI</acronym> is a way to share storage over a
>       network.  Unlike <acronym>NFS</acronym>, which works at the file
>       system level, <acronym>iSCSI</acronym> works at the block device
>       level.</para>
> 
>     <para>In <acronym>iSCSI</acronym> terminology, the system that
>       shares the storage is known as the <emphasis>target</emphasis>.
>       The storage can be a physical disk, or an area representing
>       multiple disks or a portion of a physical disk.  For example, if
>       the disk(s) are formatted with <acronym>ZFS</acronym>, a zvol
>       can be created to use as the <acronym>iSCSI</acronym>
>       storage.</para>
> 
>     <para>The clients which access the <acronym>iSCSI</acronym>
>       storage are called <emphasis>initiators</emphasis>.  To
>       initiators, the storage available through
>       <acronym>iSCSI</acronym> appears as a raw, unformatted disk
>       known as a <acronym>LUN</acronym>.  Device nodes for the disk
>       appear in <filename>/dev/</filename> and the device must be
>       separately formatted and mounted.</para>
> 
>     <para>Beginning with 10.0-RELEASE, &os; provides a native,
>       kernel-based <acronym>iSCSI</acronym> target and initiator.
>       This section describes how to configure a &os; system as a
>       target or an initiator.</para>
> 
>     <sect2 xml:id="network-iscsi-target">
>       <title>Configuring an <acronym>iSCSI</acronym> Target</title>
> 
>       <note>
> 	<para>The native <acronym>iSCSI</acronym> target is supported
> 	  starting with &os; 10.0-RELEASE.  To use
> 	  <acronym>iSCSI</acronym> in older versions of &os;, install
> 	  a userspace target from the Ports Collection, such as
> 	  <package>net/istgt</package>.  This chapter only describes
> 	  the native target.</para>
>       </note>
> 
>       <para>To configure an <acronym>iSCSI</acronym> target, create
> 	the <filename>/etc/ctl.conf</filename> configuration file, add
> 	a line to <filename>/etc/rc.conf</filename> to make sure the
> 	&man.ctld.8; daemon is automatically started at boot, and then
> 	start the daemon.</para>
> 
>       <para>The following is an example of a simple
> 	<filename>/etc/ctl.conf</filename> configuration file.  Refer
> 	to &man.ctl.conf.5; for a more complete description of this
> 	file's available options.</para>
> 
>       <programlisting>portal-group pg0 {
> 	discovery-auth-group no-authentication
> 	listen 0.0.0.0
> 	listen [::]
> }
> 
> target iqn.2012-06.com.example:target0 {
> 	auth-group no-authentication
> 	portal-group pg0
> 
> 	lun 0 {
> 		path /data/target0-0
> 		size 4G
> 	}
> }</programlisting>
> 
>       <para>The first entry defines the <literal>pg0</literal> portal
> 	group.  Portal groups define which network addresses the
> 	&man.ctld.8; daemon will listen on.  The
> 	<literal>discovery-auth-group no-authentication</literal>
> 	entry indicates that any initiator is allowed to perform
> 	<acronym>iSCSI</acronym> target discovery without
> 	authentication.  Lines three and four configure &man.ctld.8;
> 	to listen on all <acronym>IPv4</acronym>
> 	(<literal>listen 0.0.0.0</literal>) and
> 	<acronym>IPv6</acronym> (<literal>listen [::]</literal>)
> 	addresses on the default port of 3260.</para>
> 
>       <para>It is not necessary to define a portal group as there is a
> 	built-in portal group called <literal>default</literal>.  In
> 	this case, the difference between <literal>default</literal>
> 	and <literal>pg0</literal> is that with
> 	<literal>default</literal>, target discovery is always denied,
> 	while with <literal>pg0</literal>, it is always
> 	allowed.</para>
> 
>       <para>The second entry defines a single target.  Target has two
> 	possible meanings: a machine serving <acronym>iSCSI</acronym>
> 	or a named group of <acronym>LUNs</acronym>.  This example
> 	uses the latter meaning, where
> 	<literal>iqn.2012-06.com.example:target0</literal> is the
> 	target name.  This target name is suitable for testing
> 	purposes.  For actual use, change
> 	<literal>com.example</literal> to the real domain name,
> 	reversed.  The <literal>2012-06</literal> represents the year
> 	and month of acquiring control of that domain name, and
> 	<literal>target0</literal> can be any value.  Any number of
> 	targets can be defined in this configuration file.</para>
> 
>       <para>The <literal>auth-group no-authentication</literal> line
> 	allows all initiators to connect to the specified target and
> 	<literal>portal-group pg0</literal> makes the target reachable
> 	through the <literal>pg0</literal> portal group.</para>
> 
>       <para>The next section defines the <acronym>LUN</acronym>.  To
> 	the initiator, each <acronym>LUN</acronym> will be visible as
> 	a separate disk device.  Multiple <acronym>LUNs</acronym> can
> 	be defined for each target.  Each <acronym>LUN</acronym> is
> 	identified by a number, where <acronym>LUN</acronym> 0 is
> 	mandatory.  The <literal>path /data/target0-0</literal> line
> 	defines the full path to a file or zvol backing the
> 	<acronym>LUN</acronym>.  That path must exist before starting
> 	&man.ctld.8;.  The second line is optional and specifies the
> 	size of the <acronym>LUN</acronym>.</para>
> 
>       <para>Next, to make sure the &man.ctld.8; daemon is started at
> 	boot, add this line to
> 	<filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>ctld_enable="YES"</programlisting>
> 
>       <para>To start &man.ctld.8; now, run this command:</para>
> 
>       <screen>&prompt.root; <userinput>service ctld start</userinput></screen>
> 
>       <para>As the &man.ctld.8; daemon is started, it reads
> 	<filename>/etc/ctl.conf</filename>.  If this file is edited
> 	after the daemon starts, use this command so that the changes
> 	take effect immediately:</para>
> 
>       <screen>&prompt.root; <userinput>service ctld reload</userinput></screen>
> 
>       <sect3>
> 	<title>Authentication</title>
> 
> 	<para>The previous example is inherently insecure as it uses
> 	  no authentication, granting anyone full access to all
> 	  targets.  To require a username and password to access
> 	  targets, modify the configuration as follows:</para>
> 
> 	<programlisting>auth-group ag0 {
> 	chap username1 secretsecret
> 	chap username2 anothersecret
> }
> 
> portal-group pg0 {
> 	discovery-auth-group no-authentication
> 	listen 0.0.0.0
> 	listen [::]
> }
> 
> target iqn.2012-06.com.example:target0 {
> 	auth-group ag0
> 	portal-group pg0
> 	lun 0 {
> 		path /data/target0-0
> 		size 4G
> 	}
> }</programlisting>
> 
> 	<para>The <literal>auth-group</literal> section defines
> 	  username and password pairs.  An initiator trying to connect
> 	  to <literal>iqn.2012-06.com.example:target0</literal> must
> 	  first specify a defined username and secret.  However,
> 	  target discovery is still permitted without authentication.
> 	  To require target discovery authentication, set
> 	  <literal>discovery-auth-group</literal> to a defined
> 	  <literal>auth-group</literal> name instead of
> 	  <literal>no-authentication</literal>.</para>
> 
> 	<para>It is common to define a single exported target for
> 	  every initiator.  As a shorthand for the syntax above, the
> 	  username and password can be specified directly in the
> 	  target entry:</para>
> 
> 	<programlisting>target iqn.2012-06.com.example:target0 {
> 	portal-group pg0
> 	chap username1 secretsecret
> 
> 	lun 0 {
> 		path /data/target0-0
> 		size 4G
> 	}
> }</programlisting>
>       </sect3>
>     </sect2>
> 
>     <sect2 xml:id="network-iscsi-initiator">
>       <title>Configuring an <acronym>iSCSI</acronym> Initiator</title>
> 
>       <note>
> 	<para>The <acronym>iSCSI</acronym> initiator described in this
> 	  section is supported starting with &os; 10.0-RELEASE.  To
> 	  use the <acronym>iSCSI</acronym> initiator available in
> 	  older versions, refer to &man.iscontrol.8;.</para>
>       </note>
> 
>       <para>The <acronym>iSCSI</acronym> initiator requires that the
> 	&man.iscsid.8; daemon is running.  This daemon does not use a
> 	configuration file.  To start it automatically at boot, add
> 	this line to <filename>/etc/rc.conf</filename>:</para>
> 
>       <programlisting>iscsid_enable="YES"</programlisting>
> 
>       <para>To start &man.iscsid.8; now, run this command:</para>
> 
>       <screen>&prompt.root; <userinput>service iscsid start</userinput></screen>
> 
>       <para>Connecting to a target can be done with or without an
> 	<filename>/etc/iscsi.conf</filename> configuration file.  This
> 	section demonstrates both types of connections.</para>
> 
>       <sect3>
> 	<title>Connecting to a Target Without a Configuration
> 	  File</title>
> 
> 	<para>To connect an initiator to a single target, specify the
> 	  <acronym>IP</acronym> address of the portal and the name of
> 	  the target:</para>
> 
> 	<screen>&prompt.root; <userinput>iscsictl -A -p <replaceable>10.10.10.10</replaceable> -t <replaceable>iqn.2012-06.com.example:target0</replaceable></userinput></screen>
> 
> 	<para>To verify if the connection succeeded, run
> 	  <command>iscsictl</command> without any arguments.  The
> 	  output should look similar to this:</para>
> 
> 	<programlisting>Target name                                     Target portal   State
> iqn.2012-06.com.example:target0                 10.10.10.10     Connected: da0</programlisting>
> 
> 	<para>In this example, the <acronym>iSCSI</acronym> session
> 	  was successfully established, with
> 	  <filename>/dev/da0</filename> representing the attached
> 	  <acronym>LUN</acronym>.  If the
> 	  <literal>iqn.2012-06.com.example:target0</literal> target
> 	  exports more than one <acronym>LUN</acronym>, multiple
> 	  device nodes will be shown in that section of the
> 	  output:</para>
> 
> 	<screen>Connected: da0 da1 da2.</screen>
> 
> 	<para>Any errors will be reported in the output, as well as
> 	  the system logs.  For example, this message usually means
> 	  that the &man.iscsid.8; daemon is not running:</para>
> 
> 	<programlisting>Target name                                     Target portal   State
> iqn.2012-06.com.example:target0                 10.10.10.10     Waiting for iscsid(8)</programlisting>
> 
> 	<para>The following message suggests a networking problem,
> 	  such as a wrong <acronym>IP</acronym> address or
> 	  port:</para>
> 
> 	<programlisting>Target name                                     Target portal   State
> iqn.2012-06.com.example:target0                 10.10.10.11     Connection refused</programlisting>
> 
> 	<para>This message means that the specified target name is
> 	  wrong:</para>
> 
> 	<programlisting>Target name                                     Target portal   State
> iqn.2012-06.com.example:target0                 10.10.10.10     Not found</programlisting>
> 
> 	<para>This message means that the target requires
> 	  authentication:</para>
> 
> 	<programlisting>Target name                                     Target portal   State
> iqn.2012-06.com.example:target0                 10.10.10.10     Authentication failed</programlisting>
> 
> 	<para>To specify a <acronym>CHAP</acronym> username and
> 	  secret, use this syntax:</para>
> 
> 	<screen>&prompt.root; <userinput>iscsictl -A -p <replaceable>10.10.10.10</replaceable> -t <replaceable>iqn.2012-06.com.example:target0</replaceable> -u <replaceable>user</replaceable> -s <replaceable>secretsecret</replaceable></userinput></screen>
>       </sect3>
> 
>       <sect3>
> 	<title>Connecting to a Target with a Configuration
> 	  File</title>
> 
> 	<para>To connect using a configuration file, create
> 	  <filename>/etc/iscsi.conf</filename> with contents like
> 	  this:</para>
> 
> 	<programlisting>t0 {
> 	TargetAddress   = 10.10.10.10
> 	TargetName      = iqn.2012-06.com.example:target0
> 	AuthMethod      = CHAP
> 	chapIName       = user
> 	chapSecret      = secretsecret
> }</programlisting>
> 
> 	<para>The <literal>t0</literal> specifies a nickname for the
> 	  configuration file section.  It will be used by the
> 	  initiator to specify which configuration to use.  The other
> 	  lines specify the parameters to use during connection.  The
> 	  <literal>TargetAddress</literal> and
> 	  <literal>TargetName</literal> are mandatory, whereas the
> 	  other options are optional.  In this example, the
> 	  <acronym>CHAP</acronym> username and secret are
> 	  shown.</para>
> 
> 	<para>To connect to the defined target, specify the
> 	  nickname:</para>
> 
> 	<screen>&prompt.root; <userinput>iscsictl -An <replaceable>t0</replaceable></userinput></screen>
> 
> 	<para>Alternately, to connect to all targets defined in the
> 	  configuration file, use:</para>
> 
> 	<screen>&prompt.root; <userinput>iscsictl -Aa</userinput></screen>
> 
> 	<para>To make the initiator automatically connect to all
> 	  targets in <filename>/etc/iscsi.conf</filename>, add the
> 	  following to <filename>/etc/rc.conf</filename>:</para>
> 
> 	<programlisting>iscsictl_enable="YES"
> iscsictl_flags="-Aa"</programlisting>
> 
>       </sect3>
>     </sect2>
>   </sect1>
> 
> </chapter>

Actions: View | Diff

Attachments on bug 219142: 182399