From owner-svn-doc-all@FreeBSD.ORG Wed Oct 16 23:41:27 2013 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 4F44F845; Wed, 16 Oct 2013 23:41:27 +0000 (UTC) (envelope-from dru@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 2DE2D22EA; Wed, 16 Oct 2013 23:41:27 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r9GNfR1U059458; Wed, 16 Oct 2013 23:41:27 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r9GNfREq059457; Wed, 16 Oct 2013 23:41:27 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201310162341.r9GNfREq059457@svn.freebsd.org> From: Dru Lavigne Date: Wed, 16 Oct 2013 23:41:27 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 16 Oct 2013 23:41:27 -0000 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 This section describes how to use the built-in DHCP client. It then describes how to install and configure a DHCP server. + + + In &os;, the &man.bpf.4; device is needed by both the + DHCP server and DHCP client. + This device is included in the GENERIC + kernel that is installed with &os;. Users who prefer to create + a custom kernel need to keep this device if + DHCP is used. + + Those who are security conscious should + note that bpf also + allows packet sniffers to function correctly. + Configuring a <acronym>DHCP</acronym> Client DHCP 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 DHCP server. + from an existing DHCP server. Refer to + for examples of network + configuration. UDP When dhclient is executed on the client @@ -2668,78 +2683,48 @@ result: 0 Success lease and is valid for a configurable time. This allows stale IP addresses for clients no longer connected to the network to automatically be - reused. - - DHCP clients can obtain a great deal of + reused. DHCP clients can obtain a great deal of information from the server. An exhaustive list may be found in &man.dhcp-options.5;. - The bpf device is already - part of the GENERIC kernel that is - supplied with &os;, thus there is no need to build a - custom kernel for DHCP. In the case of - a custom kernel configuration file, this device must be - present for DHCP to function - properly. - - - For those who are particularly security conscious, - take note that bpf is also the - device that allows packet sniffers to work correctly - (although they still have to be run as - root). - bpf is - required to use DHCP; however, the - security sensitive types should probably not add - bpf to the kernel in the - expectation that at some point in the future the system - will be using DHCP. - - - By default, DHCP configuration on &os; + By default, when a &os; system boots, its DHCP client runs in the background, or asynchronously. Other startup scripts - continue to run while DHCP completes, - speeding up system startup. + continue to run while the DHCP process completes, + which speeds up system startup. Background DHCP works well when the - DHCP server responds quickly to requests - and the DHCP configuration process goes - quickly. However, DHCP may take a long + DHCP server responds quickly to the client's requests. + However, DHCP may take a long time to complete on some systems. If network services attempt - to run before DHCP has completed, they will + to run before DHCP has assigned the network addressing information, they will fail. Using DHCP in - synchronous mode prevents the problem, - pausing startup until DHCP configuration + synchronous mode prevents this problem as it + pauses startup until the DHCP configuration has completed. - To connect to a DHCP server in the - background while other startup continues (asynchronous mode), - use the DHCP value in - /etc/rc.conf: + This line in /etc/rc.conf is used to + configure + background or asynchronous mode: ifconfig_fxp0="DHCP" - To pause startup while DHCP completes, - use synchronous mode with the - SYNCDHCP value: + This line may already exist if the system was configured + to use DHCP during installation. Replace + the fxp0 shown + in these examples with the name of the interface to be + dynamically configured, as described in + . + + To instead configure the system to use synchronous mode, + and to pause during startup while DHCP completes, + use + SYNCDHCP: ifconfig_fxp0="SYNCDHCP" - - Replace the fxp0 shown - in these examples with the name of the interface to be - dynamically configured, as described in - . - - - When using a different file system location for - dhclient, or if additional flags must - be passed to dhclient, include (editing - as necessary): - - dhclient_program="/sbin/dhclient" -dhclient_flags="" + Additional client options are available. Search for + dhclient in &man.rc.conf.5; for details. DHCP @@ -2753,24 +2738,23 @@ dhclient_flags="" /etc/dhclient.conf - dhclient requires a configuration - file, /etc/dhclient.conf. Typically - the file contains only comments, the defaults being - reasonably sane. This configuration file is described in + The configuration file used by dhclient. Typically, + this file contains only comments as the defaults are suitable for most clients. + This configuration file is described in &man.dhclient.conf.5;. /sbin/dhclient - More information about dhclient can + More information about the command itself can be found in &man.dhclient.8;. /sbin/dhclient-script - dhclient-script is the + The &os;-specific DHCP 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="" /var/db/dhclient.leases.interface The DHCP client keeps a database of - valid leases in this file, which is written as a log. - &man.dhclient.leases.5; gives a slightly longer - description. Refer to &man.dhclient.8;, - &man.dhcp-options.5;, and &man.dhclient.conf.5;, in - addition to the references below, for more - information. + valid leases in this file, which is written as a log and is described in + &man.dhclient.leases.5;. @@ -2795,195 +2775,166 @@ dhclient_flags="" Installing and Configuring a <acronym>DHCP</acronym> Server - This section provides information on how to configure a + This section demonstrates how to configure a &os; system to act as a DHCP server using - the ISC (Internet Systems Consortium) implementation of the - DHCP server. + the Internet Systems Consortium (ISC) implementation of the + DHCP server. This implementation and its documentation can be + installed using the net/isc-dhcp42-server package or + port. DHCP server - The DHCP server, - dhcpd, is included as part of the - net/isc-dhcp42-server port - in the ports collection. This port contains the ISC - DHCP server and documentation. - - The server is not provided as part of &os;, and so the - net/isc-dhcp42-server - port must be installed to provide this service. See - for more information on using the - Ports Collection. - DHCP installation - In order to configure the &os; system as a - DHCP server, first ensure that the - &man.bpf.4; device is compiled into the kernel. To do this, - add device bpf to the kernel configuration - file, and rebuild the kernel. For more information about - building kernels, see . - - The bpf device is already part - of the GENERIC kernel that is supplied - with &os;, so there is no need to create a custom kernel in - order to get DHCP working. - - - Those who are particularly security conscious should - note that bpf is also the device - that allows packet sniffers to function correctly - (although such programs still need privileged access). - The bpf device - is required to use - DHCP, 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 - DHCP may, at some point in the future, be - desired. - - - An example configuration file is installed by the + The installation of net/isc-dhcp42-server - port. Copy the example + installs a sample configuration file. Copy /usr/local/etc/dhcpd.conf.example - to the actual configuration file, - /usr/local/etc/dhcpd.conf. Edits - will be made to this new file. - - - Configuring the <acronym>DHCP</acronym> Server + to + /usr/local/etc/dhcpd.conf and make any edits + to this new file. DHCP dhcpd.conf - dhcpd.conf is comprised of - declarations regarding subnets and hosts, and is perhaps - most easily explained using an example : + The configuration file is comprised of + declarations for subnets and hosts which define the + information that is provided to DHCP + clients. For example, these + lines configure the following: - option domain-name "example.com"; -option domain-name-servers 192.168.4.100; + option domain-name "example.org"; +option domain-name-servers ns1.example.org; option subnet-mask 255.255.255.0; -default-lease-time 3600; -max-lease-time 86400; +default-lease-time 600; +max-lease-time 72400; ddns-update-style none; -subnet 192.168.4.0 netmask 255.255.255.0 { - range 192.168.4.129 192.168.4.254; - option routers 192.168.4.1; +subnet 10.254.239.0 netmask 255.255.255.224 { + range 10.254.239.10 10.254.239.20; + option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org; } -host mailhost { - hardware ethernet 02:03:04:05:06:07; - fixed-address mailhost.example.com; +host fantasia { + hardware ethernet 08:00:07:26:c0:a5; + fixed-address fantasia.fugue.com; } - 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. + This option specifies the default search domain that will be + provided to clients. Refer to + &man.resolv.conf.5; for more information. This option specifies a comma separated list of DNS servers that the client should - use. + use. They can be listed by their Fully Qualified Domain + Names (FQDN), as seen in the example, + or by their IP addresses. - The netmask that will be provided to + The subnet mask that will be provided to clients. - 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). + The default + lease expiry time in + seconds. A client can be configured to override this + value. - 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 max-lease-time - seconds. + 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 max-lease-time. - This option specifies whether the - DHCP server should attempt to update - DNS when a lease is accepted or - released. In the ISC implementation, this option is - required. + The default of disables dynamic DNS updates. + Changing this to configures the + DHCP server to update a + DNS server whenever it hands out a + lease so that the DNS server knows + which IP addresses are associated + with which computers in the network. Do not change the default + setting unless the DNS server has + been configured to support dynamic + DNS. - This denotes which IP addresses - should be used in the pool reserved for allocating to - clients. IP addresses between, and - including, the ones stated are handed out to - clients. + This line creates a pool of available IP addresses + which are reserved for allocation to DHCP + clients. The range of addresses must be valid for the + network or subnet specified in the previous line. - Declares the default gateway that will be provided - to clients. + Declares the default gateway that is valid for the + network or subnet specified before the opening + { bracket. - The hardware MAC address of a host (so that the - DHCP server can recognize a host when - it makes a request). + Specifies the hardware MAC address of a client so that the + DHCP server can recognize the client when + it makes a request. - Specifies that the host should always be given the - same IP address. Note that using a - hostname is correct here, since the + Specifies that this host should always be given the + same IP address. Using the + hostname is correct, since the DHCP server will resolve the - hostname itself before returning the lease + hostname before returning the lease information. + This configuration file supports many more options. Refer + to dhcpd.conf(5), installed with the server, for details and + examples. + Once the configuration of - dhcpd.conf has been completed, + dhcpd.conf is complete, enable the DHCP server in - /etc/rc.conf, i.e., by adding: + /etc/rc.conf: dhcpd_enable="YES" dhcpd_ifaces="dc0" - Replace the dc0 interface name with + Replace the dc0 with the interface (or interfaces, separated by whitespace) that the DHCP server should listen on for DHCP client requests. - Proceed to start the server by issuing + Start the server by issuing the following command: &prompt.root; service isc-dhcpd start Any future changes to the configuration of the server - will require the sending of a SIGTERM - signal to dhcpd rather than a - SIGHUP. It is definitely more simple to - use &man.service.8; to completely restart the - service. - - - - Files + will require the + dhcpd service to be stopped and then started using + &man.service.8;. + + The DHCP server uses the following + files. Note that the manual pages are installed with the + server software. DHCP @@ -2993,27 +2944,21 @@ dhcpd_ifaces="dc0" /usr/local/sbin/dhcpd - dhcpd is statically - linked and resides in - /usr/local/sbin. More - information about - dhcpd can be found in - &man.dhcpd.8;. + More + information about the + dhcpd server can be found in + dhcpd(8). /usr/local/etc/dhcpd.conf - dhcpd requires a - configuration file, - /usr/local/etc/dhcpd.conf before it - will start providing service to clients. This file + 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. + dhcpd.conf(5). @@ -3021,24 +2966,23 @@ dhcpd_ifaces="dc0" The DHCP 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. /usr/local/sbin/dhcrelay - dhcrelay is used in + This daemon is used in advanced environments where one DHCP server forwards a request from a client to another DHCP server on a separate network. - If this functionality is required, then install the + If this functionality is required, install the net/isc-dhcp42-relay - port. The port installs &man.dhcrelay.8;, which + package or port. The installation includes dhcrelay(8) which provides more detail. -