Date: Wed, 16 Oct 2013 23:41:27 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42978 - head/en_US.ISO8859-1/books/handbook/network-servers Message-ID: <201310162341.r9GNfREq059457@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Wed Oct 16 23:41:26 2013 New Revision: 42978 URL: http://svnweb.freebsd.org/changeset/doc/42978 Log: 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. Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Oct 16 20:19:56 2013 (r42977) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Wed Oct 16 23:41:26 2013 (r42978) @@ -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> - - <para><acronym>DHCP</acronym> clients can obtain a great deal of + 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>The <devicename>bpf</devicename> device is already - 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; + <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 <acronym>DHCP</acronym> completes, - speeding up system startup.</para> + 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 requests - and the <acronym>DHCP</acronym> configuration process goes - quickly. However, <acronym>DHCP</acronym> may take a long + <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 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, - pausing startup until <acronym>DHCP</acronym> configuration + <firstterm>synchronous</firstterm> mode prevents this problem as it + pauses startup until the <acronym>DHCP</acronym> configuration has completed.</para> - <para>To connect to a <acronym>DHCP</acronym> server in the - background while other startup continues (asynchronous mode), - use the <quote><literal>DHCP</literal></quote> value in - <filename>/etc/rc.conf</filename>:</para> + <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>To pause startup while <acronym>DHCP</acronym> completes, - use synchronous mode with the - <quote><literal>SYNCDHCP</literal></quote> value:</para> + <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> - <note> - <para>Replace the <replaceable>fxp0</replaceable> shown - in these examples with the name of the interface to be - dynamically configured, as described in - <xref linkend="config-network-setup"/>.</para> - </note> - - <para>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> + <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> @@ -2753,24 +2738,23 @@ dhclient_flags=""</programlisting> <listitem> <para><filename>/etc/dhclient.conf</filename></para> - <para><command>dhclient</command> requires a configuration - file, <filename>/etc/dhclient.conf</filename>. Typically - the file contains only comments, the defaults being - reasonably sane. This configuration file is described in + <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 <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. - &man.dhclient.leases.5; gives a slightly longer - 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> + valid leases in this file, which is written as a log and is described in + &man.dhclient.leases.5;.</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 - <acronym>DHCP</acronym> server.</para> + the Internet Systems Consortium (<acronym>ISC</acronym>) implementation of the + <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 - <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 + <para>The installation of <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, - <filename>/usr/local/etc/dhcpd.conf</filename>. Edits - will be made to this new file.</para> - - <sect3> - <title>Configuring the <acronym>DHCP</acronym> Server</title> + 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><filename>dhcpd.conf</filename> is comprised of - declarations regarding subnets and hosts, and is perhaps - most easily explained using an example :</para> + <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.com";<co id="domain-name"/> -option domain-name-servers 192.168.4.100;<co id="domain-name-servers"/> + <programlisting>option domain-name "example.org";<co id="domain-name"/> +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"/> -max-lease-time 86400;<co id="max-lease-time"/> +default-lease-time 600;<co id="default-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 { - range 192.168.4.129 192.168.4.254;<co id="range"/> - option routers 192.168.4.1;<co id="routers"/> +subnet 10.254.239.0 netmask 255.255.255.224 { + range 10.254.239.10 10.254.239.20;<co id="range"/> + option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;<co id="routers"/> } -host mailhost { - hardware ethernet 02:03:04:05:06:07;<co id="hardware"/> - fixed-address mailhost.example.com;<co id="fixed-address"/> +host fantasia { + hardware ethernet 08:00:07:26:c0:a5;<co id="hardware"/> + fixed-address fantasia.fugue.com;<co id="fixed-address"/> }</programlisting> <calloutlist> <callout arearefs="domain-name"> - <para>This option specifies the domain that will be - provided to clients as the default search domain. See - &man.resolv.conf.5; for more information on what this - means.</para> + <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.</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 - that a lease will be valid. Otherwise the server will - assign a lease with this expiry value (in - seconds).</para> + <para>The default + lease expiry time in + seconds. A client can be configured to override this + value. </para> </callout> <callout arearefs="max-lease-time"> - <para>This is the maximum length of time that the server - will lease for. Should a client request a longer - lease, a lease will be issued, although it will only - be valid for <literal>max-lease-time</literal> - seconds.</para> + <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>This option specifies whether the - <acronym>DHCP</acronym> server should attempt to update - <acronym>DNS</acronym> when a lease is accepted or - released. In the ISC implementation, this option is - <emphasis>required</emphasis>.</para> + <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 denotes which <acronym>IP</acronym> addresses - should be used in the pool reserved for allocating to - clients. <acronym>IP</acronym> addresses between, and - including, the ones stated are handed out to - clients.</para> + <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 will be provided - to clients.</para> + <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>The hardware MAC address of a host (so that the - <acronym>DHCP</acronym> server can recognize a host when - it makes a request).</para> + <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 the host should always be given the - same <acronym>IP</acronym> address. Note that using a - hostname is correct here, since the + <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 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> - signal to <application>dhcpd</application> rather than a - <literal>SIGHUP</literal>. It is definitely more simple to - use &man.service.8; to completely restart the - service.</para> - </sect3> - - <sect3> - <title>Files</title> + 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> @@ -2993,27 +2944,21 @@ dhcpd_ifaces="dc0"</programlisting> <listitem> <para><filename>/usr/local/sbin/dhcpd</filename></para> - <para><application>dhcpd</application> is statically - linked and resides in - <filename>/usr/local/sbin</filename>. More - information about - <application>dhcpd</application> can be found in - &man.dhcpd.8;.</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><application>dhcpd</application> requires a - configuration file, - <filename>/usr/local/etc/dhcpd.conf</filename> before it - will start providing service to clients. This file + <para>The server configuration 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 - port.</para> + dhcpd.conf(5).</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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201310162341.r9GNfREq059457>