From murray@amd.stokely.org  Fri Nov 23 08:00:22 2001
Return-Path: <murray@amd.stokely.org>
Received: from amd.stokely.org (mao.stokely.org [65.84.64.228])
	by hub.freebsd.org (Postfix) with ESMTP id 375AE37B405
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 23 Nov 2001 08:00:22 -0800 (PST)
Received: (from murray@localhost)
	by amd.stokely.org (8.11.6/8.11.6) id fANG0L951427;
	Fri, 23 Nov 2001 16:00:21 GMT
	(envelope-from murray)
Message-Id: <200111231600.fANG0L951427@amd.stokely.org>
Date: Fri, 23 Nov 2001 16:00:21 GMT
From: murray@freebsd.org
Reply-To: murray@freebsd.org
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Omission from Handbook Chapter 17.8 (DHCP)
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         32229
>Category:       docs
>Synopsis:       Omission from Handbook Chapter 17.8 (DHCP)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    ceri
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Nov 23 08:10:00 PST 2001
>Closed-Date:    Sat Mar 23 15:51:57 PST 2002
>Last-Modified:  Sat Mar 23 15:51:57 PST 2002
>Originator:     
>Release:        FreeBSD 4.4-STABLE i386
>Organization:
WRS
>Environment:
System: FreeBSD amd.stokely.org 4.4-STABLE FreeBSD 4.4-STABLE #1: Wed Oct 10 04:30:17 PDT 2001 murray@amd.stokely.org:/.amd_mnt/mao/host/a/4/src/sys/compile/AMD i386

>Description:

The DHCP section of the Handbook just talks about setting up a FreeBSD
system as a DHCP client, which is very easy and not as useful as a
section on setting up a DHCP server.  Both should be covered in this
section.

>How-To-Repeat:

>Fix:

Someone could write up a small section on running a DHCP server on
FreeBSD.
>Release-Note:
>Audit-Trail:

From: setantae <setantae@submonkey.net>
To: murray@freebsd.org
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/32229: Omission from Handbook Chapter 17.8 (DHCP)
Date: Sun, 25 Nov 2001 12:20:38 +0000

 On Fri, Nov 23, 2001 at 04:00:21PM +0000, murray@freebsd.org wrote:
 > 
 > Someone could write up a small section on running a DHCP server on
 > FreeBSD.
 
 I'm in the process of doing this.
 
 Ceri
 
 -- 
 keep a mild groove on

From: setantae <setantae@submonkey.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:  
Subject: Re: docs/32229: Omission from Handbook Chapter 17.8 (DHCP)
Date: Mon, 26 Nov 2001 18:50:05 +0000

 OK, how about this ?
 
 All feedback more than welcome.
 
 Ceri
 
 
   <sect1 id="dhcp-server">
     <sect1info>
       <authorgroup>
         <author>
           <firstname>Ceri</firstname>
       	  <surname>Davies</surname>
 	  <contrib>Written by </contrib>
         </author>
       </authorgroup>
     </sect1info>
     <title>DHCP</title>
 
     <sect2>
       <title>What Is DHCP?</title>
       <indexterm>
         <primary>Dynamic Host Configuration Protocol</primary>
         <see>DHCP</see>
       </indexterm>
       <indexterm>
         <primary>Internet Software Consortium (ISC)</primary>
       </indexterm>
 
       <para>DHCP, the Dynamic Host Configuration Protocol, is used to
         provide information to a system on how to connect to a network and
 	for a system to request that information.</para>
     </sect2>
 
     <sect2>
       <title>What this Section Covers</title>
 
       <para>This section provides information on how to configure
 	a FreeBSD system to act as a DHCP server using the ISC
 	(Internet Software Consortium) implementation of the DHCP suite.</para>
 
       <para>The server portion of the suite is not provided as part of
 	FreeBSD, and so you will need to install the <port>net/isc-dhcp2</port>
 	port to provide this service.  See <xref linkend="ports"></xref> for more
 	information on using the ports collection.</para>
     </sect2>
 
     <sect2>
       <title>How It Works</title>
       <indexterm><primary>UDP</primary></indexterm>
       <para>When the server daemon <command>dhcpd</command> starts up,
 	it sleeps and listens for broadcast requests for network
 	configuration information. By default, it will listen on UDP port 67.
 	When such a request is received, then the server will reply to
 	the client machine on UDP port 68, providing details required to
 	connect to the network such as IP address, subnet mask, default
 	gateway and DNS servers.</para>
 
       <para>Also included with this reply is a length of time for which
 	this information can be used by that particular client. This is
 	known as a DHCP "lease" and a new lease must be acquired by the
 	client when it expires.  The length of time for which a lease is
 	valid is decided by the administrator of the DHCP server.</para>
 
       <para>DHCP clients can obtain a great deal of information from 
         the server.  An exhaustive list may be found in
         &man.dhcp-options.5;.</para>
     </sect2>
 
     <sect2>
       <title>DHCP Server Installation</title>
 	<indexterm>
 	  <primary>DHCP</primary>
 	  <secondary>installation</secondary>
 	</indexterm>
       <para>In order to configure your FreeBSD system as a DHCP server,
 	you will need to ensure that the <devicename>bpf</devicename>
 	device is compiled into your kernel.  To do this, add
 	<literal>pseudo-device bpf</literal> to your kernel
 	configuration file, and rebuild the kernel.  For more
 	information about building kernels, see <xref
 	linkend="kernelconfig"></xref>.</para>
 
       <para>The <devicename>bpf</devicename> device is already
 	part of the <filename>GENERIC</filename> kernel that is
 	supplied with FreeBSD, so if you do not have a custom
 	kernel, you should not need to create one in order to get
 	DHCP working.</para>
 
 	    <note>
 	      <para>For those who are particularly security conscious,
 	        you should be warned that <devicename>bpf</devicename>
 		is also the device that allows packet sniffers to work
 		correctly (although they still have to be run as
 		root).  <devicename>bpf</devicename>
 		<emphasis>is</emphasis> required to use DHCP, but if
 		you are very sensitive about security, you probably
 		should not add <devicename>bpf</devicename> to your
 		kernel in the expectation that at some point in the
 		future you will be using DHCP.</para>
 	    </note>
 
       <para>The next thing that you will need to do is edit the file
 	<filename>dhcpd.conf</filename> that was installed by the
 	<port>net/isc-dhcp2</port> port. By default, this will be
 	<filename>/usr/local/etc/dhcpd.conf</filename>.</para>
     </sect2>
 
     <sect2>
       <title>Configuring the DHCP Server</title>
       <indexterm>
 	<primary>DHCP</primary>
 	<secondary>configuration</secondary>
       </indexterm>
       <para>The file <filename>/usr/local/etc/dhcpd.conf</filename> is
 	comprised of declarations regarding subnets and hosts, and is
 	perhaps most easily explained using an example :</para>
 
       <programlisting>
 	option domain-name "example.com";<co id="domain-name"></co>
 	option domain-name-servers 192.168.4.100;<co id="domain-name-servers"></co>
 	option subnet-mask 255.255.255.0;<co id="subnet-mask"></co>
 
 	default-lease-time 3600;<co id="default-lease-time"></co>
 	max-lease-time 86400;<co id="max-lease-time"></co>
 
 	subnet 192.168.4.0 netmask 255.255.255.0 {
 	  range 192.168.4.129 192.168.4.254;<co id="range"></co>
 	  option routers 192.168.4.1;<co id="routers"></co>
 	}
 
 	host mailhost {
 	  hardware ethernet 02:03:04:05:06:07;<co id="hardware"></co>
 	  fixed-address mailhost.example.com;<co id="fixed-address"></co>
 	}
 	</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="domain-name">
 	  <para>This option specifies the domain that will be provided
 	    to clients as the default search domain.  See &man.resolv.conf.5;
 	    for more information on what this means.</para>
 	  </callout>
 
 	  <callout arearefs="domain-name-servers">
 	  <para>This option specifies a comma seperated list of DNS
 	    servers that the client should use.</para>
 	  </callout>
 
 	  <callout arearefs="subnet-mask">
 	  <para>The netmask that will be provided to clients.</para>
 	  </callout>
 
 	  <callout arearefs="default-lease-time">
 	  <para>A client may request a specific length of time that a
 	    lease will be valid. If it doesn't, then the server will assign
 	    a lease with this expiry value (in seconds).</para>
 	  </callout>
 
 	  <callout arearefs="max-lease-time">
 	  <para>This is the maximum length of time that the server will
 	    lease for.  Should a client request a longer lease, a lease
 	    will be issued, although it will only be valid for
 	    <literal>max-lease-time</literal> seconds.</para>
 	  </callout>
 
 	  <callout arearefs="range">
 	  <para>This denotes which IP addresses should be used in the
 	    pool reserved for allocating to clients.  IP addresses between,
 	    and including, the ones stated are handed out to clients.</para>
 	  </callout>
 
 	  <callout arearefs="routers">
 	  <para>Declares the default gateway that will be provided to
 	    clients.</para>
 	  </callout>
 
 	  <callout arearefs="hardware">
 	  <para>The hardware MAC address of a host (so that the DHCP server
 	    can recognise a host when it makes a request).</para>
 	  </callout>
 
 	  <callout arearefs="fixed-address">
 	  <para>Specifies that the host should always be given the same
 	    IP address.  Note that a hostname is OK here, since the DHCP
 	    server will resolve the hostname itself before returning the
 	    lease information.</para>
 	  </callout
 	</calloutlist>
 
 	<para>Once you have finished writing your <filename>dhcpd.conf</filename>,
 	  you can proceed to start the server by issuing the command:</para>
 
 	<screen>
 	  &prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd.sh start</userinput>
 	</screen>
 
 	<para>Should you need to make changes to the configuration of your
 	  server in the future, it's important to note that sending a 
 	  <literal>SIGHUP</literal> signal to <application>dhcpd</application>
 	  does not result in the configuration being reloaded, as it does with
 	  most daemons. You will need to send a  <literal>SIGTERM</literal>
 	  signal to stop the process, and then restart it using the command above.</para>
     </sect2>
 
     <sect2>
       <title>Files</title>
       <indexterm>
         <primary>DHCP</primary>
         <secondary>configuration files</secondary>
       </indexterm>	  
       <itemizedlist>
         <listitem><para><filename>/usr/local/sbin/dhcpd</filename></para>
           <para><command>dhcpd</command> is statically linked and
             resides in <filename>/usr/local/sbin</filename>.  The &man.dhcpd.8;
             manual page gives more information about
             <command>dhcpd</command>.</para>
         </listitem>
 
         <listitem><para><filename>/usr/local/etc/dhcpd.conf</filename></para>
           <para><command>dhcpd</command> requires a configuration file,
             <filename>/usr/local/etc/dhcpd.conf</filename> before it will
 	    start providing service to clients.  This file needs to contain
 	    all the information that should be provided to clients that are
 	    being serviced, along with information regarding the operation of
 	    the server. This configuration file is described by the
 	    &man.dhcpd.conf.5; manual page.</para>
         </listitem>
 
         <listitem><para><filename>/var/db/dhcpd.leases</filename></para>
           <para>The DHCP server keeps a database of leases it has issued
 	    in this file, which is written as a log.  &man.dhcpd.leases.5;
             gives a slightly longer description.</para>
         </listitem>
 
         <listitem><para><filename>/usr/local/sbin/dhcrelay</filename></para>
           <para><command>dhcrelay</command> is used in advanced environments
 	    where one DHCP server forwards a request from a client to
 	    another DHCP server on a separate network. The &man.dhcrelay.8;
 	    manual page provides more information.</para>
         </listitem>
       </itemizedlist>
     </sect2>
 
     <sect2>
       <title>Further Reading</title>
 
       <para>The DHCP protocol is fully described in
         <ulink url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>.
         An informational resource has also been set up at
         <ulink url="http://www.dhcp.org/">dhcp.org</ulink>.</para>
     </sect2>
   </sect1>

From: setantae <setantae@submonkey.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:  
Subject: Re: docs/32229: Omission from Handbook Chapter 17.8 (DHCP)
Date: Mon, 26 Nov 2001 19:34:13 +0000

 I don't know how I go about crediting Greg Sutter who I nicked the
 bpf bit from (from his section on DHCP client setup).
 
 I need advise on this bit, or if this gets vaguely near a commit then
 maybe the committer could do this.
 
 Thanks,
 
 Ceri
 

From: setantae <setantae@submonkey.net>
To: Giorgos Keramidas <charon@labs.gr>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: docs/32229: Omission from Handbook Chapter 17.8 (DHCP)
Date: Tue, 27 Nov 2001 13:43:40 +0000

 On Tue, Nov 27, 2001 at 05:49:27AM +0200, Giorgos Keramidas wrote:
 > On 2001-11-26 11:00:03, setantae wrote:
 > >
 > >        <para>The server portion of the suite is not provided as part of
 > >  	FreeBSD, and so you will need to install the <port>net/isc-dhcp2</port>
 > >  	port to provide this service.  See <xref linkend="ports"></xref> for more
 > 
 > 		</xref> is not really necessary, I think.
 
 nsgmls complained about it being missing, so I added it.
 Same story with the </co> bits in the programlisting.
 If it isn't necessary that's great, as I won't have to worry about it in
 the future :)
 
 > >        <para>Also included with this reply is a length of time for which
 > >  	this information can be used by that particular client. This is
 > >  	known as a DHCP "lease" and a new lease must be acquired by the
 > 
 > 		<quote>lease</quote>
 
 Noted.
 
 > >        <para>The <devicename>bpf</devicename> device is already
 > >  	part of the <filename>GENERIC</filename> kernel that is
 > >  	supplied with FreeBSD, so if you do not have a custom
 > >  	kernel, you should not need to create one in order to get
 > >  	DHCP working.</para>
 > 
 > I'd prefer this without the double negative.  Something like:
 > 
 > 	...so, even if you are running the GENERIC kernel, you will
 > 	not need to build a custom kernel to get DHCP working.</para>
 > 
 > >  	    <note>
 > >  	      <para>For those who are particularly security conscious,
 > >  	        you should be warned that <devicename>bpf</devicename>
 > 
 > 	"Those of you who are particularly security consious, should
 > 	bear in mind that..." looks a bit better here.  But this might
 > 	be just me being wrong.
 
 They both suit me.  That's the bit that I nicked from the DHCP client chapter!
 
 > I tend to prefer <programlisting> tags written with the first and last
 > lines having no whitespace/newline characters, as in:
 > 
 > 	<programlisting>Text here...
 > 	  more text
 > 	  end of text</programlisting>
 > 
 > but this and other whitespace changes are easy to make before
 > committing this.
 
 OK, noted.
 
 > >  	  <callout arearefs="domain-name-servers">
 > >  	  <para>This option specifies a comma seperated list of DNS
 > 
 > 					comma separated ?
 
 Whoops.
 
 > Perhaps a paragraph needs to be added to note that the script should
 > be made executable.  I'm not sure if it will be made executable by the
 > installation.
 
 It is, yes.
 
 > >              resides in <filename>/usr/local/sbin</filename>.  The &man.dhcpd.8;
 > 
 > 	My entities do not include a &man.dhcp.8; entry.  Perhaps one
 > 	should be added, even though this is a program installed from
 > 	the ports? :-/
 > 
 > >  	    another DHCP server on a separate network. The &man.dhcrelay.8;
 > 
 > 	Similarly for this entity :-)
 
 Yeah, I was worried about that, but since this is my first effort at docbook,
 had no idea how to deal with referring to manpages that aren't in the base
 system.
 
 > I hope I'm not being too anal-retentive and this discourages you from
 > submitting more stuff like this work.  This looks absolutely
 > marvellous already :-)
 
 Thanks very much.  It's not discouraging at all; I don't really know what
 I'm doing and need the guidance!
 
 Ceri
 
Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Fri Dec 7 20:50:22 PST 2001 
Responsible-Changed-Why:  
I'll make a few changes with Ceri and handle this. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=32229 
Responsible-Changed-From-To: keramida->ceri 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Mon Mar 18 08:23:49 PST 2002 
Responsible-Changed-Why:  
Ceri has interesting work done for this already, 
and notes he will take care of it now. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=32229 

From: Ceri <setantae@submonkey.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:  
Subject: Re: docs/32229: Omission from Handbook Chapter 17.8 (DHCP)
Date: Wed, 20 Mar 2002 11:25:45 +0000

 I'm working on a new patch now.
 
 Ceri
State-Changed-From-To: open->closed 
State-Changed-By: ceri 
State-Changed-When: Sat Mar 23 15:50:41 PST 2002 
State-Changed-Why:  


A section on configuring a DHCP server added in r1.128 


http://www.freebsd.org/cgi/query-pr.cgi?pr=32229 
>Unformatted:
