This chapter finishes up the DHCP section. It does the following:

- moves the bpf warning higher as it applies to both
- reduces some headings
- removes redundancy and does general tightening
- clarifies some sections
- modernizes the server config file and expands on the descriptions

This chapter would benefit from extra callouts describing declarations and multiple subnets.

A subsequent patch will fix the white space.

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

@@ -2646,14 +2646,29 @@ result: 0 Success
     <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>Those who are security conscious should
+	  note that <devicename>bpf</devicename> also
+	  allows packet sniffers to function correctly.</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 system to
+	&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.</para>
+	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
@@ -2668,78 +2683,48 @@ result: 0 Success
 	<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.</para>
+	reused.  <acronym>DHCP</acronym> clients can obtain a great deal of
-
-      <para><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>The <devicename>bpf</devicename> device is already
+      <para>By default, when a &os; system boots, its <acronym>DHCP</acronym> client
-	part of the <filename>GENERIC</filename> kernel that is
-	supplied with &os;, thus there is no need to build a
-	custom kernel for <acronym>DHCP</acronym>.  In the case of
-	a custom kernel configuration file, this device must be
-	present for <acronym>DHCP</acronym> to function
-	properly.</para>
-
-      <note>
-	<para>For those who are particularly security conscious,
-	  take note that <devicename>bpf</devicename> is also the
-	  device that allows packet sniffers to work correctly
-	  (although they still have to be run as
-	  <username>root</username>).
-	  <devicename>bpf</devicename> <emphasis>is</emphasis>
-	  required to use <acronym>DHCP</acronym>; however, the
-	  security sensitive types should probably not add
-	  <devicename>bpf</devicename> to the kernel in the
-	  expectation that at some point in the future the system
-	  will be using <acronym>DHCP</acronym>.</para>
-      </note>
-
-      <para>By default, <acronym>DHCP</acronym> configuration on &os;
 	runs in the background, or
 	<firstterm>asynchronously</firstterm>.  Other startup scripts
-	continue to run while <acronym>DHCP</acronym> completes,
+	continue to run while the <acronym>DHCP</acronym> process completes,
-	speeding up system startup.</para>
+	which speeds up system startup.</para>
 
       <para>Background <acronym>DHCP</acronym> works well when the
-	<acronym>DHCP</acronym> server responds quickly to requests
+	<acronym>DHCP</acronym> server responds quickly to the client's requests.
-	and the <acronym>DHCP</acronym> configuration process goes
+	However, <acronym>DHCP</acronym> may take a long
-	quickly.  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 completed, they will
+	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 the problem,
+	<firstterm>synchronous</firstterm> mode prevents this problem as it
-	pausing startup until <acronym>DHCP</acronym> configuration
+	pauses startup until the <acronym>DHCP</acronym> configuration
 	has completed.</para>
 
-      <para>To connect to a <acronym>DHCP</acronym> server in the
+      <para>This line in <filename>/etc/rc.conf</filename> is used to
-	background while other startup continues (asynchronous mode),
+	configure
-	use the <quote><literal>DHCP</literal></quote> value in
+	background or asynchronous mode:</para>
-	<filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>ifconfig_<replaceable>fxp0</replaceable>="DHCP"</programlisting>
 
-      <para>To pause startup while <acronym>DHCP</acronym> completes,
+      <para>This line may already exist if the system was configured 
-	use synchronous mode with the
+	to use <acronym>DHCP</acronym> during installation.  Replace 
-	<quote><literal>SYNCDHCP</literal></quote> value:</para>
+	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>
 
-      <note>
+      <para>Additional client options are available.  Search for
-	<para>Replace the <replaceable>fxp0</replaceable> shown
+	<literal>dhclient</literal> in &man.rc.conf.5; for details.</para>
-	  in these examples with the name of the interface to be
-	  dynamically configured, as described in
-	  <xref linkend="config-network-setup"/>.</para>
-      </note>
-
-      <para>When using a different file system location for
-	<command>dhclient</command>, or if additional flags must
-	be passed to <command>dhclient</command>, include (editing
-	as necessary):</para>
-
-      <programlisting>dhclient_program="/sbin/dhclient"
-dhclient_flags=""</programlisting>
 
       <indexterm>
 	<primary><acronym>DHCP</acronym></primary>
@@ -2753,24 +2738,23 @@ dhclient_flags=""</programlisting>
 	<listitem>
 	  <para><filename>/etc/dhclient.conf</filename></para>
 
-	  <para><command>dhclient</command> requires a configuration
+	  <para>The configuration file used by <command>dhclient</command>.  Typically,
-	    file, <filename>/etc/dhclient.conf</filename>.  Typically
+	    this file contains only comments as the defaults are suitable for most clients.
-	    the file contains only comments, the defaults being
+	    This configuration file is described in
-	    reasonably sane.  This configuration file is described in
 	    &man.dhclient.conf.5;.</para>
 	</listitem>
 
 	<listitem>
 	  <para><filename>/sbin/dhclient</filename></para>
 
-	  <para>More information about <command>dhclient</command> can
+	  <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><command>dhclient-script</command> is the
+	  <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
@@ -2781,12 +2765,8 @@ dhclient_flags=""</programlisting>
 	  <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.
+	    valid leases in this file, which is written as a log and is described in
-	    &man.dhclient.leases.5; gives a slightly longer
+	    &man.dhclient.leases.5;.</para>
-	    description.  Refer to &man.dhclient.8;,
-	    &man.dhcp-options.5;, and &man.dhclient.conf.5;, in
-	    addition to the references below, for more
-	    information.</para>
 	</listitem>
       </itemizedlist>
     </sect2>
@@ -2795,195 +2775,166 @@ dhclient_flags=""</programlisting>
       <title>Installing and Configuring a <acronym>DHCP</acronym>
 	Server</title>
 
-      <para>This section provides information on how to configure a
+      <para>This section demonstrates how to configure a
 	&os; system to act as a <acronym>DHCP</acronym> server using
-	the ISC (Internet Systems Consortium) implementation of the
+	the Internet Systems Consortium (<acronym>ISC</acronym>) implementation of the
-	<acronym>DHCP</acronym> server.</para>
+	<acronym>DHCP</acronym> server.  This implementation and its documentation can be
+	installed using the <filename 
+	  role="package">net/isc-dhcp42-server</filename> package or 
+	port.</para>
 
       <indexterm>
 	<primary><acronym>DHCP</acronym></primary>
 	<secondary>server</secondary>
       </indexterm>
 
-      <para>The <acronym>DHCP</acronym> server,
-	<application>dhcpd</application>, is included as part of the
-	<filename role="package">net/isc-dhcp42-server</filename> port
-	in the ports collection.  This port contains the ISC
-	<acronym>DHCP</acronym> server and documentation.</para>
-
-      <para>The server is not provided as part of &os;, and so the
-	<filename role="package">net/isc-dhcp42-server</filename>
-	port must be installed to provide this service.  See
-	<xref linkend="ports"/> for more information on using the
-	Ports Collection.</para>
-
       <indexterm>
 	<primary><acronym>DHCP</acronym></primary>
 	  <secondary>installation</secondary>
       </indexterm>
 
-      <para>In order to configure the &os; system as a
+      <para>The installation of
-	<acronym>DHCP</acronym> server, first ensure that the
-	&man.bpf.4; device is compiled into the kernel.  To do this,
-	add <literal>device bpf</literal> to the kernel configuration
-	file, and rebuild the kernel.  For more information about
-	building kernels, see <xref linkend="kernelconfig"/>.</para>
-
-      <para>The <devicename>bpf</devicename> device is already part
-	of the <filename>GENERIC</filename> kernel that is supplied
-	with &os;, so there is no need to create a custom kernel in
-	order to get <acronym>DHCP</acronym> working.</para>
-
-      <note>
-	<para>Those who are particularly security conscious should
-	  note that <devicename>bpf</devicename> is also the device
-	  that allows packet sniffers to function correctly
-	  (although such programs still need privileged access).
-	  The <devicename>bpf</devicename> device
-	  <emphasis>is</emphasis> required to use
-	  <acronym>DHCP</acronym>, but if the sensitivity of the
-	  system's security is high, this device should not be
-	  included in the kernel purely because the use of
-	  <acronym>DHCP</acronym> may, at some point in the future, be
-	  desired.</para>
-      </note>
-
-      <para>An example configuration file is installed by the
 	<filename role="package">net/isc-dhcp42-server</filename>
-	port.  Copy the example
+	installs a sample configuration file.  Copy
 	<filename>/usr/local/etc/dhcpd.conf.example</filename>
-	to the actual configuration file,
+	to
-	<filename>/usr/local/etc/dhcpd.conf</filename>.  Edits
+	<filename>/usr/local/etc/dhcpd.conf</filename> and make any edits
-	will be made to this new file.</para>
+	to this new file.</para>
-
-      <sect3>
-	<title>Configuring the <acronym>DHCP</acronym> Server</title>
 
 	<indexterm>
 	  <primary><acronym>DHCP</acronym></primary>
 	  <secondary>dhcpd.conf</secondary>
 	</indexterm>
-	<para><filename>dhcpd.conf</filename> is comprised of
+	<para>The configuration file is comprised of
-	  declarations regarding subnets and hosts, and is perhaps
+	  declarations for subnets and hosts which define the 
-	  most easily explained using an example :</para>
+	  information that is provided to <acronym>DHCP</acronym> 
+	  clients.  For example, these 
+	  lines configure the following:</para>
 
-	<programlisting>option domain-name "example.com";<co id="domain-name"/>
+	<programlisting>option domain-name "example.org";<co id="domain-name"/>
-option domain-name-servers 192.168.4.100;<co id="domain-name-servers"/>
+option domain-name-servers ns1.example.org;<co id="domain-name-servers"/>
 option subnet-mask 255.255.255.0;<co id="subnet-mask"/>
 
-default-lease-time 3600;<co id="default-lease-time"/>
+default-lease-time 600;<co id="default-lease-time"/>
-max-lease-time 86400;<co id="max-lease-time"/>
+max-lease-time 72400;<co id="max-lease-time"/>
 ddns-update-style none;<co id="ddns-update-style"/>
 
-subnet 192.168.4.0 netmask 255.255.255.0 {
+subnet 10.254.239.0 netmask 255.255.255.224 {
-  range 192.168.4.129 192.168.4.254;<co id="range"/>
+  range 10.254.239.10 10.254.239.20;<co id="range"/>
-  option routers 192.168.4.1;<co id="routers"/>
+  option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;<co id="routers"/>
 }
 
-host mailhost {
+host fantasia {
-  hardware ethernet 02:03:04:05:06:07;<co id="hardware"/>
+  hardware ethernet 08:00:07:26:c0:a5;<co id="hardware"/>
-  fixed-address mailhost.example.com;<co id="fixed-address"/>
+  fixed-address fantasia.fugue.com;<co id="fixed-address"/>
 }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="domain-name">
-	    <para>This option specifies the domain that will be
+	    <para>This option specifies the default search domain that will be
-	      provided to clients as the default search domain.  See
+	      provided to clients.  Refer to
-	      &man.resolv.conf.5; for more information on what this
+	      &man.resolv.conf.5; for more information.</para>
-	      means.</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.</para>
+	      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 netmask that will be provided to
+	    <para>The subnet mask that will be provided to
 	      clients.</para>
 	  </callout>
 
 	  <callout arearefs="default-lease-time">
-	    <para>A client may request a specific length of time
+	    <para>The default
-	      that a lease will be valid.  Otherwise the server will
+	      lease expiry time in
-	      assign a lease with this expiry value (in
+	      seconds.  A client can be configured to override this
-	      seconds).</para>
+	      value.  </para>
 	  </callout>
 
 	  <callout arearefs="max-lease-time">
-	    <para>This is the maximum length of time that the server
+	    <para>The maximum allowed length of time, in seconds, for a
-	      will lease for.  Should a client request a longer
+	      lease.  Should a client request a longer
-	      lease, a lease will be issued, although it will only
+	      lease, a lease will still be issued, but it will only
-	      be valid for <literal>max-lease-time</literal>
+	      be valid for <literal>max-lease-time</literal>.</para>
-	      seconds.</para>
 	  </callout>
 
 	  <callout arearefs="ddns-update-style">
-	    <para>This option specifies whether the
+	    <para>The default of <option>none</option> disables dynamic DNS updates.
-	      <acronym>DHCP</acronym> server should attempt to update
+	      Changing this to <option>interim</option> configures the 
-	      <acronym>DNS</acronym> when a lease is accepted or
+	      <acronym>DHCP</acronym> server to update a 
-	      released.  In the ISC implementation, this option is
+	      <acronym>DNS</acronym> server whenever it hands out a 
-	      <emphasis>required</emphasis>.</para>
+	      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 denotes which <acronym>IP</acronym> addresses
+	    <para>This line creates a pool of available <acronym>IP</acronym> addresses
-	      should be used in the pool reserved for allocating to
+	      which are reserved for allocation to <acronym>DHCP</acronym>
-	      clients.  <acronym>IP</acronym> addresses between, and
+	      clients.  The range of addresses must be valid for the
-	      including, the ones stated are handed out to
+	      network or subnet specified in the previous line.</para>
-	      clients.</para>
 	  </callout>
 
 	  <callout arearefs="routers">
-	    <para>Declares the default gateway that will be provided
+	    <para>Declares the default gateway that is valid for the
-	      to clients.</para>
+	      network or subnet specified before the opening 
+	      <literal>{</literal> bracket.</para>
 	  </callout>
 
 	  <callout arearefs="hardware">
-	    <para>The hardware MAC address of a host (so that the
+	    <para>Specifies the hardware <acronym>MAC</acronym> address of a client so that the
-	      <acronym>DHCP</acronym> server can recognize a host when
+	      <acronym>DHCP</acronym> server can recognize the client when
-	      it makes a request).</para>
+	      it makes a request.</para>
 	  </callout>
 
 	  <callout arearefs="fixed-address">
-	    <para>Specifies that the host should always be given the
+	    <para>Specifies that this host should always be given the
-	      same <acronym>IP</acronym> address.  Note that using a
+	      same <acronym>IP</acronym> address.  Using the
-	      hostname is correct here, since the
+	      hostname is correct, since the
 	      <acronym>DHCP</acronym> server will resolve the
-	      hostname itself before returning the lease
+	      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> has been completed,
+	  <filename>dhcpd.conf</filename> is complete,
 	  enable the <acronym>DHCP</acronym> server in
-	  <filename>/etc/rc.conf</filename>, i.e., by adding:</para>
+	  <filename>/etc/rc.conf</filename>:</para>
 
 	<programlisting>dhcpd_enable="YES"
 dhcpd_ifaces="dc0"</programlisting>
 
-	<para>Replace the <literal>dc0</literal> interface name with
+	<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>Proceed to start the server by issuing
+	<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 sending of a <literal>SIGTERM</literal>
+	  will require the
-	  signal to <application>dhcpd</application> rather than a
+	  <application>dhcpd</application> service to be stopped and then started using
-	  <literal>SIGHUP</literal>.  It is definitely more simple to
+	  &man.service.8;.</para>
-	  use &man.service.8; to completely restart the
-	  service.</para>
-      </sect3>
 
-      <sect3>
+      <para>The <acronym>DHCP</acronym> server uses the following
-	<title>Files</title>
+	files.  Note that the manual pages are installed with the 
+	server software.</para>
 
 	<indexterm>
 	  <primary><acronym>DHCP</acronym></primary>
@@ -2993,27 +2944,21 @@ dhcpd_ifaces="dc0"</programlisting>
 	  <listitem>
 	    <para><filename>/usr/local/sbin/dhcpd</filename></para>
 
-	    <para><application>dhcpd</application> is statically
+	    <para>More
-	      linked and resides in
+	      information about the
-	      <filename>/usr/local/sbin</filename>.   More
+	      <application>dhcpd</application> server can be found in
-	      information about
+	      dhcpd(8).</para>
-	      <application>dhcpd</application> can be found in
-	      &man.dhcpd.8;.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><filename>/usr/local/etc/dhcpd.conf</filename></para>
 
-	    <para><application>dhcpd</application> requires a
+	    <para>The server configuration file
-	      configuration file,
-	      <filename>/usr/local/etc/dhcpd.conf</filename> before it
-	      will start providing service to clients.  This file
 	      needs to contain all the information that should be
-	      provided to clients that are being serviced, along with
+	      provided to clients, along with
 	      information regarding the operation of the server.  This
 	      configuration file is described in
-	      &man.dhcpd.conf.5;, which is installed by the
+	      dhcpd.conf(5).</para>
-	      port.</para>
 	  </listitem>
 
 	  <listitem>
@@ -3021,24 +2966,23 @@ dhcpd_ifaces="dc0"</programlisting>
 
 	    <para>The <acronym>DHCP</acronym> server keeps a database
 	      of leases it has issued in this file, which is written
-	      as a log.  The port installs &man.dhcpd.leases.5;, which
+	      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><application>dhcrelay</application> is used in
+	    <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, then install the
+	      If this functionality is required, install the
 	      <filename role="package">net/isc-dhcp42-relay</filename>
-	      port.  The port installs &man.dhcrelay.8;, which
+	      package or port.  The installation includes dhcrelay(8) which
 	      provides more detail.</para>
 	  </listitem>
 	</itemizedlist>
-      </sect3>
     </sect2>
   </sect1>