


dhcpd(8)                                                 dhcpd(8)


NAME
       dhcpd - Dynamic Host Configuration Protocol Server

SYNOPSIS
       dhcpd [ -p port ] [ -f ] [ -d ] [ -q ] [ -cf config-file ]
       [ -lf lease-file ] [ if0 [ ...ifN ] ]

DESCRIPTION
       The  Internet  Software  Consortium  DHCP  Server,  dhcpd,
       implements  the Dynamic Host Configuration Protocol (DHCP)
       and the Internet Bootstrap Protocol (BOOTP).  DHCP  allows
       hosts  on  a  TCP/IP network to request and be assigned IP
       addresses, and also to discover information about the net-
       work  to  which they are attached.  BOOTP provides similar
       functionality, with certain restrictions.

OPERATION
       The DHCP protocol allows a host which is  unknown  to  the
       network  administrator  to be automatically assigned a new
       IP address out of a pool of IP addresses for its  network.
       In order for this to work, the network administrator allo-
       cates address pools in each subnet and  enters  them  into
       the dhcpd.conf(5) file.

       On  startup,  dhcpd reads the dhcpd.conf file and stores a
       list of available addresses  on  each  subnet  in  memory.
       When a client requests an address using the DHCP protocol,
       dhcpd  allocates  an  address  for  it.   Each  client  is
       assigned  a  lease,  which expires after an amount of time
       chosen by the administrator (by default, one day).  Before
       leases  expire,  the  clients to which leases are assigned
       are expected to renew them in order to continue to use the
       addresses.   Once a lease has expired, the client to which
       that lease was assigned is no longer permitted to use  the
       leased IP address.

       In order to keep track of leases across system reboots and
       server restarts, dhcpd keeps  a  list  of  leases  it  has
       assigned  in  the  dhcpd.leases(5)  file.    Before  dhcpd
       grants a lease to a host, it records  the  lease  in  this
       file  and  makes  sure  that  the contents of the file are
       flushed to disk.   This ensures that even in the event  of
       a  system  crash, dhcpd will not forget about a lease that
       it  has  assigned.    On  startup,   after   reading   the
       dhcpd.conf  file,  dhcpd  reads  the  dhcpd.leases file to
       refresh its memory about what leases have been assigned.

       New leases are appended to the  end  of  the  dhcpd.leases
       file.    In  order to prevent the file from becoming arbi-
       trarily large, from time  to  time  dhcpd  creates  a  new
       dhcpd.leases  file  from its in-core lease database.  Once
       this file has been  written  to  disk,  the  old  file  is
       renamed   dhcpd.leases~,  and  the  new  file  is  renamed
       dhcpd.leases.   If the system crashes  in  the  middle  of



                                                                1





dhcpd(8)                                                 dhcpd(8)


       this  process,  whichever  dhcpd.leases  file remains will
       contain all the lease information, so there is no need for
       a special crash recovery process.

       BOOTP  support  is  also  provided by this server.  Unlike
       DHCP, the BOOTP protocol does not provide a  protocol  for
       recovering dynamically-assigned addresses once they are no
       longer needed.    It  is  still  possible  to  dynamically
       assign addresses to BOOTP clients, but some administrative
       process  for  reclaiming  addresses  is   required.     By
       default,  leases  are granted to BOOTP clients in perpetu-
       ity, although the network administrator may set an earlier
       cutoff  date or a shorter lease length for BOOTP leases if
       that makes sense.

       BOOTP clients may also be served in the old standard  way,
       which is to simply provide a declaration in the dhcpd.conf
       file for  each  BOOTP  client,  permanently  assigning  an
       address to each client.

       Whenever  changes  are  made to the dhcpd.conf file, dhcpd
       must be restarted.   To  restart  dhcpd,  send  a  SIGTERM
       (signal    15)    to   the   process   ID   contained   in
       RUNDIR/dhcpd.pid, and then re-invoke dhcpd.   Because  the
       DHCP  server  database  is  not  as lightweight as a BOOTP
       database, dhcpd does not automatically restart itself when
       it sees a change to the dhcpd.conf file.

       Note:  We get a lot of complaints about this.   We realize
       that it would be nice if one could send a  SIGHUP  to  the
       server  and  have  it  reload  the database.   This is not
       technically impossible, but it would require a great  deal
       of work, our resources are extremely limited, and they can
       be better spent  elsewhere.    So  please  don't  complain
       about  this  on the mailing list unless you're prepared to
       fund a project to implement this feature, or  prepared  to
       do it yourself.

       DHCP traffic always bypass IPsec, otherwise there can come
       up situations when a  server  has  an  IPsec  SA  for  the
       client,  and  sends replies over that, which a potentially
       newly booted client cannot grasp.

COMMAND LINE
       The names of the network interfaces on which dhcpd  should
       listen  for  broadcasts  may  be  specified on the command
       line.  This should be  done  on  systems  where  dhcpd  is
       unable  to  identify  non-broadcast interfaces, but should
       not be required on other systems.  If no  interface  names
       are  specified on the command line dhcpd will identify all
       network interfaces which are up, elimininating  non-broad-
       cast  interfaces  if  possible, and listen for DHCP broad-
       casts on each interface.




                                                                2





dhcpd(8)                                                 dhcpd(8)


       If dhcpd should listen on a port other than  the  standard
       (port 67), the -p flag may used.  It should be followed by
       the udp port number on which dhcpd should listen.  This is
       mostly  useful  for debugging purposes.  If the -p flag is
       specified, the server will transmit responses  to  clients
       at  a  port number that is one greater than the one speci-
       fied - i.e., if you specify -p 67, then  the  server  will
       listen on port 67 and transmit to port 68.  Datagrams that
       must go through relay agents are sent to the  port  number
       specified  with the -p flag - if you wish to use alternate
       port numbers, you must configure any relay agents you  are
       using to use the same alternate port numbers.

       To run dhcpd as a foreground process, rather than allowing
       it to run as a daemon  in  the  background,  the  -f  flag
       should  be  specified.   This is useful when running dhcpd
       under a debugger, or when running it  out  of  inittab  on
       System V systems.

       To  have dhcpd log to the standard error descriptor, spec-
       ify the -d flag.  This can be useful  for  debugging,  and
       also  at  sites  where a complete log of all dhcp activity
       must be kept but syslogd is not reliable or otherwise can-
       not  be  used.   Normally, dhcpd will log all output using
       the syslog(3)  function  with  the  log  facility  set  to
       LOG_DAEMON.

       Dhcpd  can  be made to use an alternate configuration file
       with the -cf flag, or an alternate lease file with the -lf
       flag.    Because of the importance of using the same lease
       database at all times when running  dhcpd  in  production,
       these  options should be used only for testing lease files
       or database files in a non-production environment.

       When starting dhcpd up from a system startup script (e.g.,
       /etc/rc),  it may not be desirable to print out the entire
       copyright message on startup.    To  avoid  printing  this
       message, the -q flag may be specified.

CONFIGURATION
       The  syntax  of the dhcpd.conf(5) file is discussed seper-
       ately.   This section should be used as an overview of the
       configuration process, and the dhcpd.conf(5) documentation
       should be consulted for detailed reference information.


Subnets
       dhcpd needs to know the subnet numbers and netmasks of all
       subnets for which it will be providing service.   In addi-
       tion, in order to dynamically allocate addresses, it  must
       be assigned one or more ranges of addresses on each subnet
       which it can in turn assign to client hosts as they  boot.
       Thus,  a  very simple configuration providing DHCP support
       might look like this:



                                                                3





dhcpd(8)                                                 dhcpd(8)


            subnet 239.252.197.0 netmask 255.255.255.0 {
              range 239.252.197.10 239.252.197.250;
               }

       Multiple address ranges may be specified like this:

            subnet 239.252.197.0 netmask 255.255.255.0 {
              range 239.252.197.10 239.252.197.107;
              range 239.252.197.113 239.252.197.250;
            }

       If a subnet will only be provided with BOOTP  service  and
       no  dynamic  address  assignment,  the range clause can be
       left out entirely, but the subnet statement must appear.


Lease Lengths
       DHCP leases can be assigned almost any  length  from  zero
       seconds  to  infinity.   What lease length makes sense for
       any given subnet, or for any given installation, will vary
       depending on the kinds of hosts being served.

       For  example,  in  an office environment where systems are
       added from time to time and removed from time to time, but
       move relatively infrequently, it might make sense to allow
       lease times of a month of more.   In a final test environ-
       ment  on  a manufacturing floor, it may make more sense to
       assign a maximum lease length of 30 minutes - enough  time
       to  go through a simple test procedure on a network appli-
       ance before packaging it up for delivery.

       It is possible to specify two lease lengths:  the  default
       length  that  will be assigned if a client doesn't ask for
       any particular lease length, and a maximum  lease  length.
       These are specified as clauses to the subnet command:

            subnet 239.252.197.0 netmask 255.255.255.0 {
              range 239.252.197.10 239.252.197.107;
              default-lease-time 600;
              max-lease-time 7200;
            |

       This  particular  subnet  declaration  specifies a default
       lease time of 600 seconds (ten  minutes),  and  a  maximum
       lease  time  of  7200  seconds (two hours).   Other common
       values would be 86400 (one day),  604800  (one  week)  and
       2592000 (30 days).

       Each  subnet  need not have the same lease--in the case of
       an office  environment  and  a  manufacturing  environment
       served  by  the  same  DHCP server, it might make sense to
       have widely disparate values for default and maximum lease
       times on each subnet.




                                                                4





dhcpd(8)                                                 dhcpd(8)


BOOTP Support
       Each  BOOTP  client  must  be  explicitly  declared in the
       dhcpd.conf file.   A very basic  client  declaration  will
       specify  the  client  network interface's hardware address
       and the IP address to assign  to  that  client.    If  the
       client  needs  to  be  able  to  load a boot file from the
       server, that file's name must  be  specified.    A  simple
       bootp client declaration might look like this:

            host haagen {
              hardware ethernet 08:00:2b:4c:59:23;
              fixed-address 239.252.197.9;
              filename "/tftpboot/haagen.boot";
            }

Options
       DHCP  (and  also  BOOTP with Vendor Extensions) provides a
       mechanism whereby the server can provide the  client  with
       information  about  how to configure its network interface
       (e.g., subnet mask), and also how the  client  can  access
       various  network  services  (e.g., DNS, IP routers, and so
       on).

       These options can be specified on a per-subnet basis, and,
       for  BOOTP  clients,  also on a per-client basis.   In the
       event that a BOOTP client  declaration  specifies  options
       that  are  also  specified  in its subnet declaration, the
       options specified in the client  declaration  take  prece-
       dence.    An  reasonably complete DHCP configuration might
       look something like this:

            subnet 239.252.197.0 netmask 255.255.255.0 {
              range 239.252.197.10 239.252.197.250;
              default-lease-time 600 max-lease-time 7200;
              option subnet-mask 255.255.255.0;
              option broadcast-address 239.252.197.255;
              option routers 239.252.197.1;
              option domain-name-servers 239.252.197.2, 239.252.197.3;
              option domain-name "isc.org";
            }

       A bootp host on that subnet that needs to be in a  differ-
       ent  domain  and  use  a  different  name  server might be
       declared as follows:

            host haagen {
              hardware ethernet 08:00:2b:4c:59:23;
              fixed-address 239.252.197.9;
              filename "/tftpboot/haagen.boot";
              option domain-name-servers 192.5.5.1;
              option domain-name "vix.com";
            }

       A more complete description of the dhcpd.conf file  syntax



                                                                5





dhcpd(8)                                                 dhcpd(8)


       is provided in dhcpd.conf(5).

FILES
       ETCDIR/dhcpd.conf,  DBDIR/dhcpd.leases,  RUNDIR/dhcpd.pid,
       DBDIR/dhcpd.leases~.

SEE ALSO
       dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5)

AUTHOR
       dhcpd(8) was written by Ted Lemon <mellon@vix.com> under a
       contract  with  Vixie Labs.   Funding for this project was
       provided by the Internet Software  Corporation.   Informa-
       tion  about  the Internet Software Consortium can be found
       at http://www.isc.org/.










































                                                                6


