Provided by: isc-dhcp-server_4.3.3-5ubuntu12.10_amd64 bug

NAME

       dhcpd - Dynamic Host Configuration Protocol Server

SYNOPSIS

       dhcpd [ -p port ] [ -f ] [ -d ] [ -q ] [ -t | -T ] [ -4 | -6 ] [ -s server ] [ -cf config-
       file ] [ -lf lease-file ] [ -pf pid-file ] [ --no-pid ] [ -user user ] [ -group group ]  [
       -chroot dir ] [ -tf trace-output-file ] [ -play trace-playback-file ] [ if0 [ ...ifN ] ]

       dhcpd --version

DESCRIPTION

       The   Internet  Systems  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  network  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 allocates address pools in each subnet
       and enters them into the dhcpd.conf(5) file.

       There are two versions of the DHCP protocol DHCPv4 and DHCPv6.  At startup the server  may
       be started for one or the other via the -4 or -6 arguments.

       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 arbitrarily 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 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 perpetuity, 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  /var/run/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.

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, eliminating non-broadcast interfaces if possible, and listen  for
       DHCP broadcasts on each interface.

COMMAND LINE OPTIONS

       -4     Run as a DHCP server. This is the default and cannot be combined with -6.

       -6     Run as a DHCPv6 server. This cannot be combined with -4.

       -p port
              The  udp  port  number on which dhcpd should listen.  If unspecified dhcpd uses the
              default port of 67.  This is mostly useful for debugging purposes.

       -s address
              Specify an address or host name to which dhcpd should send replies rather than  the
              broadcast address (255.255.255.255).  This option is only supported in IPv4.

       -f     Force  dhcpd  to  run  as  a  foreground  process  instead  of  as  a daemon in the
              background.  This is useful when running dhcpd under a debugger, or when running it
              out of inittab on System V systems.

       -d     Send  log  messages  to  the  standard  error  descriptor.   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 cannot be used.  Normally, dhcpd will log
              all output using the syslog(3) function with the log facility  set  to  LOG_DAEMON.
              Note that -d implies -f (the daemon will not fork itself into the background).

       -q     Be  quiet at startup.  This suppresses the printing of the entire copyright message
              during startup.  This might be desirable when starting dhcpd from a system  startup
              script (e.g., /etc/rc).

       -t     Test  the  configuration file.  The server tests the configuration file for correct
              syntax, but will not attempt to perform any network operations.  This can  be  used
              to test a new configuration file automatically before installing it.

       -T     Test  the lease file.  The server tests the lease file for correct syntax, but will
              not attempt to perform any network operations.  This can be  used  to  test  a  new
              lease file automatically before installing it.

       -user user
              Setuid  to  user  after  completing privileged operations, such as creating sockets
              that listen on privileged ports.  This also causes the lease file to  be  owned  by
              user.   This  option  is  only available if the code was compiled with the PARANOIA
              patch (./configure --enable-paranoia).

       -group group
              Setgid to group after completing privileged operations, such  as  creating  sockets
              that  listen  on  privileged  ports.  This also causes the lease file to use group.
              This option is only available if the code was  compiled  with  the  PARANOIA  patch
              (./configure --enable-paranoia).

       -chroot dir
              Chroot  to  directory.   This  may  occur before or after reading the configuration
              files depending on whether the code  was  compiled  with  the  EARLY_CHROOT  option
              enabled  (./configure --enable-early-chroot).  This option is only available if the
              code was compiled with the PARANOIA patch (./configure --enable-paranoia).

       -tf tracefile
              Specify a file into which the entire startup  state  of  the  server  and  all  the
              transactions it processes are logged.  This can be useful in submitting bug reports
              - if you are getting a core dump every so often, you can start the server with  the
              -tf  option  and  then, when the server dumps core, the trace file will contain all
              the transactions that led up to it dumping core, so that the problem can be  easily
              debugged with -play.

       -play playfile
              Specify  a  file  from  which  the  entire  startup state of the server and all the
              transactions it processed are read.  The -play option must  be  specified  with  an
              alternate  lease  file,  using the -lf switch, so that the DHCP server doesn't wipe
              out your existing lease file with its test data.  The DHCP server  will  refuse  to
              operate in playback mode unless you specify an alternate lease file.

       --version
              Print version number and exit.

       Modifying  default  file  locations:  The  following  options  can  be  used to modify the
       locations dhcpd uses for its files.  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.

       -cf config-file
              Path to alternate configuration file.

       -lf lease-file
              Path to alternate lease file.

       -pf pid-file
              Path to alternate pid file.

       --no-pid
              Option to disable writing pid files.  By default the program will write a pid file.
              If the program is invoked with this option it will not check for an existing server
              process.

PORTS

       During operations the server may use multiple UDP  and  TCP  ports  to  provide  different
       functions.   Which ports are opened depends on both the way you compiled your code and the
       configuration you supply.  The following should provide you an idea of what ports  may  be
       in use.

       Normally  a  DHCPv4  server  will  open  a  raw UDP socket to receive and send most DHCPv4
       packets.  It also opens a  fallback  UDP  socket  for  use  in  sending  unicast  packets.
       Normally these will both use the well known port number for BOOTPS.

       For  each  DHCPv4  failover  peer  you  list in the configuartion file there will be a TCP
       socket listening for connections on the ports specififed in the configuration file.   When
       the  peer  connects  there will be another socket for the established connection.  For the
       established connection the side (primary or secondary) opening the connection will  use  a
       random port.

       For DHCPv6 the server opens a UDP socket on the well known dhcpv6-server port.

       The server opens an icmp socket for doing ping requests to check if addresses are in use.

       If  you  have  included an omapi-port statement in your configuration file then the server
       will open a TCP socket on that port to  listen  for  OMPAI  connections.   When  something
       connects another port will be used for the established connection.

       When  DDNS is enabled at compile time (see includes/site.h) the server will open both a v4
       and a v6 UDP socket on random ports.  These ports are opened even if DDNS is  disabled  in
       the configuration file.

CONFIGURATION

       The syntax of the dhcpd.conf(5) file is discussed separately.  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 addition, 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:

            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 or more.  In a final test environment 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  appliance  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.

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) provide 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 precedence.  A 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 different 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 is provided in dhcpd.conf(5).

OMAPI

       The DHCP server provides the capability to modify some of its configuration  while  it  is
       running,  without  stopping  it,  modifying  its  database files, and restarting it.  This
       capability is currently provided using OMAPI - an API  for  manipulating  remote  objects.
       OMAPI  clients  connect to the server using TCP/IP, authenticate, and can then examine the
       server's current status and make changes to it.

       Rather than implementing the underlying OMAPI protocol directly, user programs should  use
       the  dhcpctl  API  or  OMAPI  itself.   Dhcpctl  is  a  wrapper  that  handles some of the
       housekeeping chores  that  OMAPI  does  not  do  automatically.   Dhcpctl  and  OMAPI  are
       documented in dhcpctl(3) and omapi(3).

       OMAPI  exports  objects, which can then be examined and modified.  The DHCP server exports
       the following objects: lease, host, failover-state and group.  Each object has a number of
       methods  that  are  provided: lookup, create, and destroy.  In addition, it is possible to
       look at attributes that are  stored  on  objects,  and  in  some  cases  to  modify  those
       attributes.

THE LEASE OBJECT

       Leases  can't  currently be created or destroyed, but they can be looked up to examine and
       modify their state.

       Leases have the following attributes:

       state integer lookup, examine
            1 = free
            2 = active
            3 = expired
            4 = released
            5 = abandoned
            6 = reset
            7 = backup
            8 = reserved
            9 = bootp

       ip-address data lookup, examine
            The IP address of the lease.

       dhcp-client-identifier data lookup, examine, update
            The client identifier that the client used when  it  acquired  the  lease.   Not  all
            clients send client identifiers, so this may be empty.

       client-hostname data examine, update
            The value the client sent in the host-name option.

       host handle examine
            the host declaration associated with this lease, if any.

       subnet handle examine
            the  subnet  object  associated  with  this lease (the subnet object is not currently
            supported).

       pool handle examine
            the pool object associated  with  this  lease  (the  pool  object  is  not  currently
            supported).

       billing-class handle examine
            the  handle  to  the class to which this lease is currently billed, if any (the class
            object is not currently supported).

       hardware-address data examine, update
            the hardware address (chaddr) field sent by the client when it acquired its lease.

       hardware-type integer examine, update
            the type of the network interface that the  client  reported  when  it  acquired  its
            lease.

       ends time examine
            the time when the lease's current state ends, as understood by the client.

       tstp time examine
            the time when the lease's current state ends, as understood by the server.
       tsfp time examine
            the  adjusted time when the lease's current state ends, as understood by the failover
            peer (if there is no failover peer, this value is undefined).  Generally  this  value
            is only adjusted for expired, released, or reset leases while the server is operating
            in partner-down state, and otherwise is simply the value supplied by the peer.
       atsfp time examine
            the actual tsfp value sent from the peer.  This  value  is  forgotten  when  a  lease
            binding state change is made, to facilitate retransmission logic.

       cltt time examine
            The time of the last transaction with the client on this lease.

THE HOST OBJECT

       Hosts  can be created, destroyed, looked up, examined and modified.  If a host declaration
       is created or deleted using OMAPI, that information will be recorded in  the  dhcpd.leases
       file.   It  is permissible to delete host declarations that are declared in the dhcpd.conf
       file.

       Hosts have the following attributes:

       name data lookup, examine, modify
            the name of  the  host  declaration.   This  name  must  be  unique  among  all  host
            declarations.

       group handle examine, modify
            the named group associated with the host declaration, if there is one.

       hardware-address data lookup, examine, modify
            the  link-layer address that will be used to match the client, if any.  Only valid if
            hardware-type is also present.

       hardware-type integer lookup, examine, modify
            the type of the network interface that will be used to  match  the  client,  if  any.
            Only valid if hardware-address is also present.

       dhcp-client-identifier data lookup, examine, modify
            the dhcp-client-identifier option that will be used to match the client, if any.

       ip-address data examine, modify
            a  fixed  IP  address  which  is  reserved  for  a DHCP client that matches this host
            declaration.  The IP address will only be assigned to the client if it is  valid  for
            the network segment to which the client is connected.

       statements data modify
            a  list  of  statements  in  the  format of the dhcpd.conf file that will be executed
            whenever a message from the client is being processed.

       known integer examine, modify
            if nonzero, indicates that a client matching this host declaration will be treated as
            known in pool permit lists.  If zero, the client will not be treated as known.

THE GROUP OBJECT

       Named  groups  can  be  created,  destroyed, looked up, examined and modified.  If a group
       declaration is created or deleted using OMAPI, that information will be  recorded  in  the
       dhcpd.leases  file.   It  is permissible to delete group declarations that are declared in
       the dhcpd.conf file.

       Named groups currently can only be  associated  with  hosts  -  this  allows  one  set  of
       statements to be efficiently attached to more than one host declaration.

       Groups have the following attributes:

       name data
            the  name of the group.  All groups that are created using OMAPI must have names, and
            the names must be unique among all groups.

       statements data
            a list of statements in the format of the  dhcpd.conf  file  that  will  be  executed
            whenever  a  message  from  a  client whose host declaration references this group is
            processed.

THE CONTROL OBJECT

       The control object allows you to shut the server down.  If the server  is  doing  failover
       with  another peer, it will make a clean transition into the shutdown state and notify its
       peer, so that the peer can go into partner down, and then record the  "recover"  state  in
       the  lease  file so that when the server is restarted, it will automatically resynchronize
       with its peer.

       On shutdown the server will also attempt to cleanly shut down all OMAPI  connections.   If
       these  connections  do  not  go  down  cleanly  after  five  seconds,  they  are shut down
       preemptively.  It can take as much as 25  seconds  from  the  beginning  of  the  shutdown
       process to the time that the server actually exits.

       To shut the server down, open its control object and set the state attribute to 2.

THE FAILOVER-STATE OBJECT

       The  failover-state object is the object that tracks the state of the failover protocol as
       it is being managed for a given failover peer.  The  failover  object  has  the  following
       attributes (please see dhcpd.conf (5) for explanations about what these attributes mean):

       name data examine
            Indicates  the  name  of the failover peer relationship, as described in the server's
            dhcpd.conf file.

       partner-address data examine
            Indicates the failover partner's IP address.

       local-address data examine
            Indicates the IP address that is being used by the  DHCP  server  for  this  failover
            pair.

       partner-port data examine
            Indicates  the  TCP  port  on  which  the  failover partner is listening for failover
            protocol connections.

       local-port data examine
            Indicates the TCP port on which the DHCP server is listening  for  failover  protocol
            connections for this failover pair.

       max-outstanding-updates integer examine
            Indicates  the  number  of  updates that can be outstanding and unacknowledged at any
            given time, in this failover relationship.

       mclt integer examine
            Indicates the maximum client lead time in this failover relationship.

       load-balance-max-secs integer examine
            Indicates the maximum value for the secs  field  in  a  client  request  before  load
            balancing is bypassed.

       load-balance-hba data examine
            Indicates the load balancing hash bucket array for this failover relationship.

       local-state integer examine, modify
            Indicates  the  present  state  of  the  DHCP  server  in this failover relationship.
            Possible values for state are:

                 1   - startup
                 2   - normal
                 3   - communications interrupted
                 4   - partner down
                 5   - potential conflict
                 6   - recover
                 7   - paused
                 8   - shutdown
                 9   - recover done
                 10  - resolution interrupted
                 11  - conflict done
                 254 - recover wait

            (Note that some of the above values have changed since DHCP 3.0.x.)

            In general it is not a good idea to make changes to this state.  However, in the case
            that  the  failover  partner  is  known  to be down, it can be useful to set the DHCP
            server's failover state to partner down.  At this point the  DHCP  server  will  take
            over  service of the failover partner's leases as soon as possible, and will give out
            normal leases, not leases that are restricted by MCLT.  If you do put the DHCP server
            into  the  partner-down  when the other DHCP server is not in the partner-down state,
            but is not reachable, IP address assignment  conflicts  are  possible,  even  likely.
            Once  a  server has been put into partner-down mode, its failover partner must not be
            brought back online until communication is possible between the two servers.

       partner-state integer examine
            Indicates the present state of the failover partner.

       local-stos integer examine
            Indicates the time at which the  DHCP  server  entered  its  present  state  in  this
            failover relationship.

       partner-stos integer examine
            Indicates the time at which the failover partner entered its present state.

       hierarchy integer examine
            Indicates  whether  the  DHCP server is primary (0) or secondary (1) in this failover
            relationship.

       last-packet-sent integer examine
            Indicates the time at which the most recent failover packet was  sent  by  this  DHCP
            server to its failover partner.

       last-timestamp-received integer examine
            Indicates  the timestamp that was on the failover message most recently received from
            the failover partner.

       skew integer examine
            Indicates the skew between the failover partner's clock and this DHCP server's clock

       max-response-delay integer examine
            Indicates the time in seconds after  which,  if  no  message  is  received  from  the
            failover partner, the partner is assumed to be out of communication.

       cur-unacked-updates integer examine
            Indicates  the  number  of  update messages that have been received from the failover
            partner but not yet processed.

FILES

       /etc/dhcp/dhcpd.conf,           /var/lib/dhcp/dhcpd.leases,            /var/run/dhcpd.pid,
       /var/lib/dhcp/dhcpd.leases~.

SEE ALSO

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

AUTHOR

       dhcpd(8)  was  originally  written by Ted Lemon under a contract with Vixie Labs.  Funding
       for this project was provided by Internet Systems  Consortium.   Version  3  of  the  DHCP
       server  was  funded  by  Nominum,  Inc.   Information about Internet Systems Consortium is
       available at https://www.isc.org/.

                                                                                         dhcpd(8)