1dhcpd(8)                    System Manager's Manual                   dhcpd(8)
2
3
4

NAME

6       dhcpd - Dynamic Host Configuration Protocol Server
7

SYNOPSIS

9       dhcpd  [ -p port ] [ -f ] [ -d ] [ -q ] [ -t | -T ] [ -cf config-file ]
10       [ -lf lease-file ] [ -pf pid-file ] [ -tf trace-output-file ]  [  -play
11       trace-playback-file ] [ if0 [ ...ifN ] ]
12

DESCRIPTION

14       The  Internet  Systems  Consortium  DHCP  Server, dhcpd, implements the
15       Dynamic Host Configuration Protocol (DHCP) and the  Internet  Bootstrap
16       Protocol (BOOTP).  DHCP allows hosts on a TCP/IP network to request and
17       be assigned IP addresses, and also to discover  information  about  the
18       network to which they are attached.  BOOTP provides similar functional‐
19       ity, with certain restrictions.
20

CONTRIBUTIONS

22       This software is free software.  At various times its  development  has
23       been underwritten by various organizations, including the ISC and Vixie
24       Enterprises.  The development of 3.0 has been funded almost entirely by
25       Nominum, Inc.
26
27       At  this point development is being shepherded by Ted Lemon, and hosted
28       by the ISC, but the future of this project depends on you.  If you have
29       features you want, please consider implementing them.
30

OPERATION

32       The  DHCP protocol allows a host which is unknown to the network admin‐
33       istrator to be automatically assigned a new IP address out of a pool of
34       IP  addresses for its network.   In order for this to work, the network
35       administrator allocates address pools in each subnet  and  enters  them
36       into the dhcpd.conf(5) file.
37
38       On startup, dhcpd reads the dhcpd.conf file and stores a list of avail‐
39       able addresses on each subnet in memory.  When  a  client  requests  an
40       address  using  the  DHCP  protocol, dhcpd allocates an address for it.
41       Each client is assigned a lease, which expires after an amount of  time
42       chosen  by  the  administrator  (by  default,  one day).  Before leases
43       expire, the clients to which leases are assigned are expected to  renew
44       them  in  order  to  continue  to  use the addresses.  Once a lease has
45       expired, the client to which that lease was assigned is no longer  per‐
46       mitted to use the leased IP address.
47
48       In  order  to  keep  track  of  leases across system reboots and server
49       restarts, dhcpd  keeps  a  list  of  leases  it  has  assigned  in  the
50       dhcpd.leases(5)  file.    Before  dhcpd  grants  a  lease to a host, it
51       records the lease in this file and makes sure that the contents of  the
52       file  are  flushed  to disk.   This ensures that even in the event of a
53       system crash, dhcpd will not forget about a lease that it has assigned.
54       On  startup,  after  reading  the  dhcpd.conf  file,  dhcpd  reads  the
55       dhcpd.leases file to refresh its memory about  what  leases  have  been
56       assigned.
57
58       New leases are appended to the end of the dhcpd.leases file.   In order
59       to prevent the file from becoming arbitrarily large, from time to  time
60       dhcpd  creates a new dhcpd.leases file from its in-core lease database.
61       Once this file has been written  to  disk,  the  old  file  is  renamed
62       dhcpd.leases~,  and the new file is renamed dhcpd.leases.   If the sys‐
63       tem crashes in the middle of this process, whichever dhcpd.leases  file
64       remains will contain all the lease information, so there is no need for
65       a special crash recovery process.
66
67       BOOTP support is also provided by this server.  Unlike DHCP, the  BOOTP
68       protocol  does  not  provide  a  protocol  for  recovering dynamically-
69       assigned addresses once they are no longer needed.   It is still possi‐
70       ble to dynamically assign addresses to BOOTP clients, but some adminis‐
71       trative process for reclaiming addresses  is  required.    By  default,
72       leases are granted to BOOTP clients in perpetuity, although the network
73       administrator may set an earlier cutoff date or a shorter lease  length
74       for BOOTP leases if that makes sense.
75
76       BOOTP  clients  may also be served in the old standard way, which is to
77       simply provide a declaration in the  dhcpd.conf  file  for  each  BOOTP
78       client, permanently assigning an address to each client.
79
80       Whenever  changes  are  made  to  the  dhcpd.conf  file,  dhcpd must be
81       restarted.   To restart dhcpd,  send  a  SIGTERM  (signal  15)  to  the
82       process  ID  contained in /var/run/dhcpd.pid, and then re-invoke dhcpd.
83       Because the DHCP server database is not as lightweight as a BOOTP data‐
84       base, dhcpd does not automatically restart itself when it sees a change
85       to the dhcpd.conf file.
86
87       Note: We get a lot of complaints about this.   We realize that it would
88       be nice if one could send a SIGHUP to the server and have it reload the
89       database.   This is not technically impossible, but it would require  a
90       great  deal  of work, our resources are extremely limited, and they can
91       be better spent elsewhere.   So please don't complain about this on the
92       mailing list unless you're prepared to fund a project to implement this
93       feature, or prepared to do it yourself.
94

COMMAND LINE

96       The names of the network interfaces on which dhcpd  should  listen  for
97       broadcasts  may  be specified on the command line.  This should be done
98       on systems where dhcpd is unable to identify non-broadcast  interfaces,
99       but should not be required on other systems.  If no interface names are
100       specified on the command line dhcpd will identify  all  network  inter‐
101       faces  which  are up, eliminating non-broadcast interfaces if possible,
102       and listen for DHCP broadcasts on each interface.
103
104       If dhcpd should listen on a port other than the standard (port 67), the
105       -p  flag  may  used.   It  should be followed by the udp port number on
106       which dhcpd should listen.  This is mostly useful  for  debugging  pur‐
107       poses.
108
109       To run dhcpd as a foreground process, rather than allowing it to run as
110       a daemon in the background, the -f flag should be specified.   This  is
111       useful  when  running dhcpd under a debugger, or when running it out of
112       inittab on System V systems.
113
114       To have dhcpd log to the standard  error  descriptor,  specify  the  -d
115       flag.  This can be useful for debugging, and also at sites where a com‐
116       plete log of all dhcp activity must be kept but syslogd is not reliable
117       or  otherwise  cannot  be  used.    Normally, dhcpd will log all output
118       using the syslog(3) function with the log facility set  to  LOG_DAEMON.
119       Note that -d implies -f (the daemon will not fork itself into the back‐
120       ground).
121
122       Dhcpd can be made to use an alternate configuration file with  the  -cf
123       flag,  an  alternate  lease file with the -lf flag, or an alternate pid
124       file with the -pf flag.   Because of the importance of using  the  same
125       lease  database  at  all  times when running dhcpd in production, these
126       options should be used only for testing lease files or  database  files
127       in a non-production environment.
128
129       When starting dhcpd up from a system startup script (e.g., /etc/rc), it
130       may not be desirable to print  out  the  entire  copyright  message  on
131       startup.    To  avoid  printing this message, the -q flag may be speci‐
132       fied.
133
134       The DHCP server reads two files on startup: a configuration file, and a
135       lease  database.    If the -t flag is specified, the server will simply
136       test the configuration file for correct syntax, but will not attempt to
137       perform  any  network  operations.   This can be used to test the a new
138       configuration file automatically before installing it.
139
140       The -T flag can be used to test the lease database file  in  a  similar
141       way.
142
143       The  -tf  and  -play options allow you to specify a file into which the
144       entire startup state of the server and all  the  transactions  it  pro‐
145       cesses  are  either  logged or played back from.  This can be useful in
146       submitting bug reports - if you are getting a core dump every so often,
147       you  can start the server with the -tf option and then, when the server
148       dumps core, the trace file will contain all the transactions  that  led
149       up  to it dumping core, so that the problem can be easily debugged with
150       -play.
151
152       The -play option must be specified with an alternate lease file,  using
153       the  -lf switch, so that the DHCP server doesn't wipe out your existing
154       lease file with its test data.  The DHCP server will refuse to  operate
155       in playback mode unless you specify an alternate lease file.
156

CONFIGURATION

158       The  syntax  of  the dhcpd.conf(5) file is discussed separately.   This
159       section should be used as an overview of the configuration process, and
160       the dhcpd.conf(5) documentation should be consulted for detailed refer‐
161       ence information.
162

Subnets

164       dhcpd needs to know the subnet numbers and netmasks of all subnets  for
165       which  it will be providing service.   In addition, in order to dynami‐
166       cally allocate addresses, it must be assigned one  or  more  ranges  of
167       addresses on each subnet which it can in turn assign to client hosts as
168       they boot.   Thus, a very simple configuration providing  DHCP  support
169       might look like this:
170
171            subnet 239.252.197.0 netmask 255.255.255.0 {
172              range 239.252.197.10 239.252.197.250;
173            }
174
175       Multiple address ranges may be specified like this:
176
177            subnet 239.252.197.0 netmask 255.255.255.0 {
178              range 239.252.197.10 239.252.197.107;
179              range 239.252.197.113 239.252.197.250;
180            }
181
182       If  a  subnet  will  only be provided with BOOTP service and no dynamic
183       address assignment, the range clause can be left out entirely, but  the
184       subnet statement must appear.
185

Lease Lengths

187       DHCP  leases  can  be  assigned  almost any length from zero seconds to
188       infinity.   What lease length makes sense for any given subnet, or  for
189       any given installation, will vary depending on the kinds of hosts being
190       served.
191
192       For example, in an office environment where systems are added from time
193       to  time  and  removed  from  time  to time, but move relatively infre‐
194       quently, it might make sense to allow lease times of a month  of  more.
195       In  a final test environment on a manufacturing floor, it may make more
196       sense to assign a maximum lease length of 30 minutes - enough  time  to
197       go  through a simple test procedure on a network appliance before pack‐
198       aging it up for delivery.
199
200       It is possible to specify two lease lengths: the  default  length  that
201       will  be  assigned  if  a  client  doesn't ask for any particular lease
202       length, and a maximum lease length.   These are specified as clauses to
203       the subnet command:
204
205            subnet 239.252.197.0 netmask 255.255.255.0 {
206              range 239.252.197.10 239.252.197.107;
207              default-lease-time 600;
208              max-lease-time 7200;
209            }
210
211       This  particular  subnet  declaration specifies a default lease time of
212       600 seconds (ten minutes), and a maximum lease  time  of  7200  seconds
213       (two  hours).    Other  common  values would be 86400 (one day), 604800
214       (one week) and 2592000 (30 days).
215
216       Each subnet need not have the same lease—in the case of an office envi‐
217       ronment and a manufacturing environment served by the same DHCP server,
218       it might make sense to have widely disparate  values  for  default  and
219       maximum lease times on each subnet.
220

BOOTP Support

222       Each  BOOTP  client must be explicitly declared in the dhcpd.conf file.
223       A very basic client declaration will specify the client network  inter‐
224       face's  hardware  address  and the IP address to assign to that client.
225       If the client needs to be able to load a boot  file  from  the  server,
226       that file's name must be specified.   A simple bootp client declaration
227       might look like this:
228
229            host haagen {
230              hardware ethernet 08:00:2b:4c:59:23;
231              fixed-address 239.252.197.9;
232              filename "/tftpboot/haagen.boot";
233            }
234

Options

236       DHCP (and also  BOOTP  with  Vendor  Extensions)  provide  a  mechanism
237       whereby the server can provide the client with information about how to
238       configure its network interface (e.g., subnet mask), and also  how  the
239       client  can access various network services (e.g., DNS, IP routers, and
240       so on).
241
242       These options can be specified on a per-subnet basis,  and,  for  BOOTP
243       clients, also on a per-client basis.   In the event that a BOOTP client
244       declaration specifies options that are also  specified  in  its  subnet
245       declaration,  the  options  specified  in  the  client declaration take
246       precedence.   A reasonably complete DHCP configuration might look some‐
247       thing like this:
248
249            subnet 239.252.197.0 netmask 255.255.255.0 {
250              range 239.252.197.10 239.252.197.250;
251              default-lease-time 600 max-lease-time 7200;
252              option subnet-mask 255.255.255.0;
253              option broadcast-address 239.252.197.255;
254              option routers 239.252.197.1;
255              option domain-name-servers 239.252.197.2, 239.252.197.3;
256              option domain-name "isc.org";
257            }
258
259       A  bootp host on that subnet that needs to be in a different domain and
260       use a different name server might be declared as follows:
261
262            host haagen {
263              hardware ethernet 08:00:2b:4c:59:23;
264              fixed-address 239.252.197.9;
265              filename "/tftpboot/haagen.boot";
266              option domain-name-servers 192.5.5.1;
267              option domain-name "vix.com";
268            }
269
270       A more complete description of the dhcpd.conf file syntax  is  provided
271       in dhcpd.conf(5).
272

OMAPI

274       The  DHCP server provides the capability to modify some of its configu‐
275       ration while it is running, without stopping it, modifying its database
276       files,  and restarting it.  This capability is currently provided using
277       OMAPI - an API for manipulating remote objects.  OMAPI clients  connect
278       to  the  server  using  TCP/IP,  authenticate, and can then examine the
279       server's current status and make changes to it.
280
281       Rather than implementing the underlying OMAPI protocol  directly,  user
282       programs  should  use  the  dhcpctl API or OMAPI itself.   Dhcpctl is a
283       wrapper that handles some of the housekeeping chores  that  OMAPI  does
284       not  do automatically.   Dhcpctl and OMAPI are documented in dhcpctl(3)
285       and omapi(3).
286
287       OMAPI exports objects, which can then be examined and  modified.    The
288       DHCP  server exports the following objects: lease, host, failover-state
289       and group.   Each object has a number of  methods  that  are  provided:
290       lookup,  create,  and destroy.   In addition, it is possible to look at
291       attributes that are stored on objects, and  in  some  cases  to  modify
292       those attributes.
293

THE LEASE OBJECT

295       Leases  can't currently be created or destroyed, but they can be looked
296       up to examine and modify their state.
297
298       Leases have the following attributes:
299
300       state integer lookup, examine
301            1 = free
302            2 = active
303            3 = expired
304            4 = released
305            5 = abandoned
306            6 = reset
307            7 = backup
308            8 = reserved
309            9 = bootp
310
311       ip-address data lookup, examine
312            The IP address of the lease.
313
314       dhcp-client-identifier data lookup, examine, update
315            The client identifier that the client used when  it  acquired  the
316            lease.   Not  all  clients send client identifiers, so this may be
317            empty.
318
319       client-hostname data examine, update
320            The value the client sent in the host-name option.
321
322       host handle examine
323            the host declaration associated with this lease, if any.
324
325       subnet handle examine
326            the subnet object associated with this lease (the subnet object is
327            not currently supported).
328
329       pool handle examine
330            the  pool object associted with this lease (the pool object is not
331            currently supported).
332
333       billing-class handle examine
334            the handle to the class to which this lease is  currently  billed,
335            if any (the class object is not currently supported).
336
337       hardware-address data examine, update
338            the  hardware  address  (chaddr)  field sent by the client when it
339            acquired its lease.
340
341       hardware-type integer examine, update
342            the type of the network interface that the client reported when it
343            acquired its lease.
344
345       ends time examine
346            the time when the lease's current state ends, as understood by the
347            client.
348
349       tstp time examine
350            the time when the lease's current state ends, as understood by the
351            server.
352       tsfp time examine
353            the  adjusted  time when the lease's current state ends, as under‐
354            stood by the failover peer (if there is  no  failover  peer,  this
355            value  is  undefined).   Generally this value is only adjusted for
356            expired, released, or reset leases while the server  is  operating
357            in  partner-down state, and otherwise is simply the value supplied
358            by the peer.
359       atsfp time examine
360            the actual tsfp value sent from the peer.  This value is forgotten
361            when a lease binding state change is made, to facillitate retrans‐
362            mission logic.
363
364       cltt time examine
365            The time of the last transaction with the client on this lease.
366

THE HOST OBJECT

368       Hosts can be created, destroyed, looked up, examined and modified.   If
369       a  host declaration is created or deleted using OMAPI, that information
370       will be recorded in the  dhcpd.leases  file.    It  is  permissible  to
371       delete host declarations that are declared in the dhcpd.conf file.
372
373       Hosts have the following attributes:
374
375       name data lookup, examine, modify
376            the name of the host declaration.   This name must be unique among
377            all host declarations.
378
379       group handle examine, modify
380            the named group associated with the host declaration, if there  is
381            one.
382
383       hardware-address data lookup, examine, modify
384            the  link-layer  address that will be used to match the client, if
385            any.  Only valid if hardware-type is also present.
386
387       hardware-type integer lookup, examine, modify
388            the type of the network interface that will be used to  match  the
389            client, if any.   Only valid if hardware-address is also present.
390
391       dhcp-client-identifier data lookup, examine, modify
392            the  dhcp-client-identifier  option that will be used to match the
393            client, if any.
394
395       ip-address data examine, modify
396            a fixed IP address which  is  reserved  for  a  DHCP  client  that
397            matches  this  host  declaration.    The  IP  address will only be
398            assigned to the client if it is valid for the network  segment  to
399            which the client is connected.
400
401       statements data modify
402            a  list  of  statements  in the format of the dhcpd.conf file that
403            will be executed whenever a message from the client is being  pro‐
404            cessed.
405
406       known integer examine, modify
407            if nonzero, indicates that a client matching this host declaration
408            will be treated as known in pool  permit  lists.    If  zero,  the
409            client will not be treated as known.
410

THE GROUP OBJECT

412       Named  groups  can be created, destroyed, looked up, examined and modi‐
413       fied.  If a group declaration is created or deleted using  OMAPI,  that
414       information will be recorded in the dhcpd.leases file.  It is permissi‐
415       ble to delete group declarations that are declared  in  the  dhcpd.conf
416       file.
417
418       Named  groups currently can only be associated with hosts - this allows
419       one set of statements to be efficiently attached to more than one  host
420       declaration.
421
422       Groups have the following attributes:
423
424       name data
425            the  name  of  the group.  All groups that are created using OMAPI
426            must have names, and the names must be unique among all groups.
427
428       statements data
429            a list of statements in the format of  the  dhcpd.conf  file  that
430            will  be executed whenever a message from a client whose host dec‐
431            laration references this group is processed.
432

THE CONTROL OBJECT

434       The control object allows you to shut the server down.   If the  server
435       is  doing  failover  with another peer, it will make a clean transition
436       into the shutdown state and notify its peer, so that the  peer  can  go
437       into  partner  down,  and  then record the "recover" state in the lease
438       file so that when the server is restarted, it will automatically resyn‐
439       chronize with its peer.
440
441       On shutdown the server will also attempt to cleanly shut down all OMAPI
442       connections.  If these connections do not go down  cleanly  after  five
443       seconds,  they  are shut down pre-emptively.  It can take as much as 25
444       seconds from the beginning of the shutdown process to the time that the
445       server actually exits.
446
447       To  shut  the  server  down,  open its control object and set the state
448       attribute to 2.
449

THE FAILOVER-STATE OBJECT

451       The failover-state object is the object that tracks the  state  of  the
452       failover  protocol  as  it  is being managed for a given failover peer.
453       The failover object has the following attributes (please see dhcpd.conf
454       (5) for explanations about what these attributes mean):
455
456       name data examine
457            Indicates the name of the failover peer relationship, as described
458            in the server's dhcpd.conf file.
459
460       partner-address data examine
461            Indicates the failover partner's IP address.
462
463       local-address data examine
464            Indicates the IP address that is being used by the DHCP server for
465            this failover pair.
466
467       partner-port data examine
468            Indicates  the TCP port on which the failover partner is listening
469            for failover protocol connections.
470
471       local-port data examine
472            Indicates the TCP port on which the DHCP server is  listening  for
473            failover protocol connections for this failover pair.
474
475       max-outstanding-updates integer examine
476            Indicates  the number of updates that can be outstanding and unac‐
477            knowledged at any given time, in this failover relationship.
478
479       mclt integer examine
480            Indicates the maximum client lead time in this failover  relation‐
481            ship.
482
483       load-balance-max-secs integer examine
484            Indicates the maximum value for the secs field in a client request
485            before load balancing is bypassed.
486
487       load-balance-hba data examine
488            Indicates the load balancing hash bucket array for  this  failover
489            relationship.
490
491       local-state integer examine, modify
492            Indicates  the  present  state of the DHCP server in this failover
493            relationship.   Possible values for state are:
494
495                 1  - partner down
496                 2  - normal
497                 3  - communications interrupted
498                 4  - resolution interrupted
499                 5  - potential conflict
500                 6  - recover
501                 7  - recover done
502                 8  - shutdown
503                 9  - paused
504                 10 - startup
505                 11 - recover wait
506
507            In general it is not a good idea to make changes  to  this  state.
508            However,  in  the  case  that  the failover partner is known to be
509            down, it can be useful to set the DHCP server's failover state  to
510            partner  down.   At this point the DHCP server will take over ser‐
511            vice of the failover partner's leases as  soon  as  possible,  and
512            will  give  out  normal  leases, not leases that are restricted by
513            MCLT.   If you do put the DHCP server into the  partner-down  when
514            the other DHCP server is not in the partner-down state, but is not
515            reachable, IP address  assignment  conflicts  are  possible,  even
516            likely.    Once  a server has been put into partner-down mode, its
517            failover partner must not be brought back online until  communica‐
518            tion is possible between the two servers.
519
520       partner-state integer examine
521            Indicates the present state of the failover partner.
522
523       local-stos integer examine
524            Indicates  the  time  at which the DHCP server entered its present
525            state in this failover relationship.
526
527       partner-stos integer examine
528            Indicates the time at  which  the  failover  partner  entered  its
529            present state.
530
531       hierarchy integer examine
532            Indicates  whether the DHCP server is primary (0) or secondary (1)
533            in this failover relationship.
534
535       last-packet-sent integer examine
536            Indicates the time at which the most recent  failover  packet  was
537            sent by this DHCP server to its failover partner.
538
539       last-timestamp-received integer examine
540            Indicates  the  timestamp  that  was  on the failover message most
541            recently received from the failover partner.
542
543       skew integer examine
544            Indicates the skew between the failover partner's clock  and  this
545            DHCP server's clock
546
547       max-response-delay integer examine
548            Indicates  the  time  in  seconds  after  which,  if no message is
549            received from the failover partner, the partner is assumed  to  be
550            out of communication.
551
552       cur-unacked-updates integer examine
553            Indicates  the  number  of update messages that have been received
554            from the failover partner but not yet processed.
555

FILES

557       /etc/dhcpd.conf,    /var/lib/dhcpd/dhcpd.leases,    /var/run/dhcpd.pid,
558       /var/lib/dhcpd/dhcpd.leases~.
559

SEE ALSO

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

AUTHOR

564       dhcpd(8)  was  originally  written  by  Ted Lemon under a contract with
565       Vixie Labs.  Funding for this project was provided by Internet  Systems
566       Consortium.    Version 3 of the DHCP server was funded by Nominum, Inc.
567       Information  about  Internet  Systems  Consortium   is   available   at
568       http://www.isc.org/.    Information  about  Nominum  can  be  found  at
569       http://www.nominum.com/.
570
571
572
573                                                                      dhcpd(8)
Impressum