1dhcpd(8) System Manager's Manual dhcpd(8)
2
6 dhcpd - Dynamic Host Configuration Protocol Server
7
9 dhcpd [ -p port ] [ -f ] [ -d ] [ -q ] [ -t | -T ] [ -4 | -6 ] [ -s
10 server ] [ -cf config-file ] [ -lf lease-file ] [ -pf pid-file ] [ -tf
11 trace-output-file ] [ -user user ] [ -group group ] [ -chroot dir ] [
12 -play trace-playback-file ] [ if0 [ ...ifN ] ]
13 dhcpd --version
15
17 The Internet Systems Consortium DHCP Server, dhcpd, implements the
18 Dynamic Host Configuration Protocol (DHCP) and the Internet Bootstrap
19 Protocol (BOOTP). DHCP allows hosts on a TCP/IP network to request and
20 be assigned IP addresses, and also to discover information about the
21 network to which they are attached. BOOTP provides similar functional‐
22 ity, with certain restrictions.
23
25 This software is free software. At various times its development has
26 been underwritten by various organizations, including the ISC and Vixie
27 Enterprises. The development of 3.0 has been funded almost entirely by
28 Nominum, Inc.
29 At this point development is being shepherded by Ted Lemon, and hosted
31 by the ISC, but the future of this project depends on you. If you have
32 features you want, please consider implementing them.
33
35 The DHCP protocol allows a host which is unknown to the network admin‐
36 istrator to be automatically assigned a new IP address out of a pool of
37 IP addresses for its network. In order for this to work, the network
38 administrator allocates address pools in each subnet and enters them
39 into the dhcpd.conf(5) file.
40 On startup, dhcpd reads the dhcpd.conf file and stores a list of avail‐
42 able addresses on each subnet in memory. When a client requests an
43 address using the DHCP protocol, dhcpd allocates an address for it.
44 Each client is assigned a lease, which expires after an amount of time
45 chosen by the administrator (by default, one day). Before leases
46 expire, the clients to which leases are assigned are expected to renew
47 them in order to continue to use the addresses. Once a lease has
48 expired, the client to which that lease was assigned is no longer per‐
49 mitted to use the leased IP address.
50 In order to keep track of leases across system reboots and server
52 restarts, dhcpd keeps a list of leases it has assigned in the
53 dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it
54 records the lease in this file and makes sure that the contents of the
55 file are flushed to disk. This ensures that even in the event of a
56 system crash, dhcpd will not forget about a lease that it has assigned.
57 On startup, after reading the dhcpd.conf file, dhcpd reads the
58 dhcpd.leases file to refresh its memory about what leases have been
59 assigned.
60 New leases are appended to the end of the dhcpd.leases file. In order
62 to prevent the file from becoming arbitrarily large, from time to time
63 dhcpd creates a new dhcpd.leases file from its in-core lease database.
64 Once this file has been written to disk, the old file is renamed
65 dhcpd.leases~, and the new file is renamed dhcpd.leases. If the sys‐
66 tem crashes in the middle of this process, whichever dhcpd.leases file
67 remains will contain all the lease information, so there is no need for
68 a special crash recovery process.
69 BOOTP support is also provided by this server. Unlike DHCP, the BOOTP
71 protocol does not provide a protocol for recovering dynamically-
72 assigned addresses once they are no longer needed. It is still possi‐
73 ble to dynamically assign addresses to BOOTP clients, but some adminis‐
74 trative process for reclaiming addresses is required. By default,
75 leases are granted to BOOTP clients in perpetuity, although the network
76 administrator may set an earlier cutoff date or a shorter lease length
77 for BOOTP leases if that makes sense.
78 BOOTP clients may also be served in the old standard way, which is to
80 simply provide a declaration in the dhcpd.conf file for each BOOTP
81 client, permanently assigning an address to each client.
82 Whenever changes are made to the dhcpd.conf file, dhcpd must be
84 restarted. To restart dhcpd, send a SIGTERM (signal 15) to the
85 process ID contained in /var/run/dhcpd.pid, and then re-invoke dhcpd.
86 Because the DHCP server database is not as lightweight as a BOOTP data‐
87 base, dhcpd does not automatically restart itself when it sees a change
88 to the dhcpd.conf file.
89 Note: We get a lot of complaints about this. We realize that it would
91 be nice if one could send a SIGHUP to the server and have it reload the
92 database. This is not technically impossible, but it would require a
93 great deal of work, our resources are extremely limited, and they can
94 be better spent elsewhere. So please don't complain about this on the
95 mailing list unless you're prepared to fund a project to implement this
96 feature, or prepared to do it yourself.
97
99 The names of the network interfaces on which dhcpd should listen for
100 broadcasts may be specified on the command line. This should be done
101 on systems where dhcpd is unable to identify non-broadcast interfaces,
102 but should not be required on other systems. If no interface names are
103 specified on the command line dhcpd will identify all network inter‐
104 faces which are up, eliminating non-broadcast interfaces if possible,
105 and listen for DHCP broadcasts on each interface.
106 The server either operates as a DHCPv6 server or a DHCP server, but not
108 both at the same time. To run as a DHCPv6 server, use the -6 flag. To
109 run as a DHCP server, use the -4 flag. If neither is used, the default
110 is to run as a DHCPv6 server.
111 If dhcpd should listen on a port other than the standard (port 67), the
113 -p flag may used. It should be followed by the udp port number on
114 which dhcpd should listen. This is mostly useful for debugging pur‐
115 poses.
116 If dhcpd should send replies to an address other than the broadcast
118 address (255.255.255.255), the -s flag may be used. It is followed by
119 either the IP address or the host name to send replies to. This option
120 is only supported in IPv4.
121 To run dhcpd as a foreground process, rather than allowing it to run as
123 a daemon in the background, the -f flag should be specified. This is
124 useful when running dhcpd under a debugger, or when running it out of
125 inittab on System V systems.
126 To have dhcpd log to the standard error descriptor, specify the -d
128 flag. This can be useful for debugging, and also at sites where a com‐
129 plete log of all dhcp activity must be kept but syslogd is not reliable
130 or otherwise cannot be used. Normally, dhcpd will log all output
131 using the syslog(3) function with the log facility set to LOG_DAEMON.
132 Note that -d implies -f (the daemon will not fork itself into the back‐
133 ground).
134 Dhcpd can be made to use an alternate configuration file with the -cf
136 flag, an alternate lease file with the -lf flag, or an alternate pid
137 file with the -pf flag. Because of the importance of using the same
138 lease database at all times when running dhcpd in production, these
139 options should be used only for testing lease files or database files
140 in a non-production environment.
141 When starting dhcpd up from a system startup script (e.g., /etc/rc), it
143 may not be desirable to print out the entire copyright message on
144 startup. To avoid printing this message, the -q flag may be speci‐
145 fied.
146 The DHCP server reads two files on startup: a configuration file, and a
148 lease database. If the -t flag is specified, the server will simply
149 test the configuration file for correct syntax, but will not attempt to
150 perform any network operations. This can be used to test the a new
151 configuration file automatically before installing it.
152 The -T flag can be used to test the lease database file in a similar
154 way.
155 The -tf and -play options allow you to specify a file into which the
157 entire startup state of the server and all the transactions it pro‐
158 cesses are either logged or played back from. This can be useful in
159 submitting bug reports - if you are getting a core dump every so often,
160 you can start the server with the -tf option and then, when the server
161 dumps core, the trace file will contain all the transactions that led
162 up to it dumping core, so that the problem can be easily debugged with
163 -play.
164 The -play option must be specified with an alternate lease file, using
166 the -lf switch, so that the DHCP server doesn't wipe out your existing
167 lease file with its test data. The DHCP server will refuse to operate
168 in playback mode unless you specify an alternate lease file.
169 To find the version of dhcpd that will run, use the --version argument.
171 Instead of running, the version will be printed.
172 -user user
174 Setuid to user after completing privileged operations, such as
175 creating sockets that listen on privileged ports.
176 -group group
178 Setgid to group after completing privileged operations, such as
179 creating sockets that listen on privileged ports.
180 -chroot dir
182 Chroot to directory after processing the command line arguments,
183 but before reading the configuration file.
184
186 The syntax of the dhcpd.conf(5) file is discussed separately. This
187 section should be used as an overview of the configuration process, and
188 the dhcpd.conf(5) documentation should be consulted for detailed refer‐
189 ence information.
190
192 dhcpd needs to know the subnet numbers and netmasks of all subnets for
193 which it will be providing service. In addition, in order to dynami‐
194 cally allocate addresses, it must be assigned one or more ranges of
195 addresses on each subnet which it can in turn assign to client hosts as
196 they boot. Thus, a very simple configuration providing DHCP support
197 might look like this:
198 subnet 239.252.197.0 netmask 255.255.255.0 {
200 range 239.252.197.10 239.252.197.250;
201 }
202 Multiple address ranges may be specified like this:
204 subnet 239.252.197.0 netmask 255.255.255.0 {
206 range 239.252.197.10 239.252.197.107;
207 range 239.252.197.113 239.252.197.250;
208 }
209 If a subnet will only be provided with BOOTP service and no dynamic
211 address assignment, the range clause can be left out entirely, but the
212 subnet statement must appear.
213
215 DHCP leases can be assigned almost any length from zero seconds to
216 infinity. What lease length makes sense for any given subnet, or for
217 any given installation, will vary depending on the kinds of hosts being
218 served.
219 For example, in an office environment where systems are added from time
221 to time and removed from time to time, but move relatively infre‐
222 quently, it might make sense to allow lease times of a month of more.
223 In a final test environment on a manufacturing floor, it may make more
224 sense to assign a maximum lease length of 30 minutes - enough time to
225 go through a simple test procedure on a network appliance before pack‐
226 aging it up for delivery.
227 It is possible to specify two lease lengths: the default length that
229 will be assigned if a client doesn't ask for any particular lease
230 length, and a maximum lease length. These are specified as clauses to
231 the subnet command:
232 subnet 239.252.197.0 netmask 255.255.255.0 {
234 range 239.252.197.10 239.252.197.107;
235 default-lease-time 600;
236 max-lease-time 7200;
237 }
238 This particular subnet declaration specifies a default lease time of
240 600 seconds (ten minutes), and a maximum lease time of 7200 seconds
241 (two hours). Other common values would be 86400 (one day), 604800
242 (one week) and 2592000 (30 days).
243 Each subnet need not have the same lease—in the case of an office envi‐
245 ronment and a manufacturing environment served by the same DHCP server,
246 it might make sense to have widely disparate values for default and
247 maximum lease times on each subnet.
248
250 Each BOOTP client must be explicitly declared in the dhcpd.conf file.
251 A very basic client declaration will specify the client network inter‐
252 face's hardware address and the IP address to assign to that client.
253 If the client needs to be able to load a boot file from the server,
254 that file's name must be specified. A simple bootp client declaration
255 might look like this:
256 host haagen {
258 hardware ethernet 08:00:2b:4c:59:23;
259 fixed-address 239.252.197.9;
260 filename "/tftpboot/haagen.boot";
261 }
262
264 DHCP (and also BOOTP with Vendor Extensions) provide a mechanism
265 whereby the server can provide the client with information about how to
266 configure its network interface (e.g., subnet mask), and also how the
267 client can access various network services (e.g., DNS, IP routers, and
268 so on).
269 These options can be specified on a per-subnet basis, and, for BOOTP
271 clients, also on a per-client basis. In the event that a BOOTP client
272 declaration specifies options that are also specified in its subnet
273 declaration, the options specified in the client declaration take
274 precedence. A reasonably complete DHCP configuration might look some‐
275 thing like this:
276 subnet 239.252.197.0 netmask 255.255.255.0 {
278 range 239.252.197.10 239.252.197.250;
279 default-lease-time 600 max-lease-time 7200;
280 option subnet-mask 255.255.255.0;
281 option broadcast-address 239.252.197.255;
282 option routers 239.252.197.1;
283 option domain-name-servers 239.252.197.2, 239.252.197.3;
284 option domain-name "isc.org";
285 }
286 A bootp host on that subnet that needs to be in a different domain and
288 use a different name server might be declared as follows:
289 host haagen {
291 hardware ethernet 08:00:2b:4c:59:23;
292 fixed-address 239.252.197.9;
293 filename "/tftpboot/haagen.boot";
294 option domain-name-servers 192.5.5.1;
295 option domain-name "vix.com";
296 }
297 A more complete description of the dhcpd.conf file syntax is provided
299 in dhcpd.conf(5).
300
302 The DHCP server provides the capability to modify some of its configu‐
303 ration while it is running, without stopping it, modifying its database
304 files, and restarting it. This capability is currently provided using
305 OMAPI - an API for manipulating remote objects. OMAPI clients connect
306 to the server using TCP/IP, authenticate, and can then examine the
307 server's current status and make changes to it.
308 Rather than implementing the underlying OMAPI protocol directly, user
310 programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a
311 wrapper that handles some of the housekeeping chores that OMAPI does
312 not do automatically. Dhcpctl and OMAPI are documented in dhcpctl(3)
313 and omapi(3).
314 OMAPI exports objects, which can then be examined and modified. The
316 DHCP server exports the following objects: lease, host, failover-state
317 and group. Each object has a number of methods that are provided:
318 lookup, create, and destroy. In addition, it is possible to look at
319 attributes that are stored on objects, and in some cases to modify
320 those attributes.
321
323 Leases can't currently be created or destroyed, but they can be looked
324 up to examine and modify their state.
325 Leases have the following attributes:
327 state integer lookup, examine
329 1 = free
330 2 = active
331 3 = expired
332 4 = released
333 5 = abandoned
334 6 = reset
335 7 = backup
336 8 = reserved
337 9 = bootp
338 ip-address data lookup, examine
340 The IP address of the lease.
341 dhcp-client-identifier data lookup, examine, update
343 The client identifier that the client used when it acquired the
344 lease. Not all clients send client identifiers, so this may be
345 empty.
346 client-hostname data examine, update
348 The value the client sent in the host-name option.
349 host handle examine
351 the host declaration associated with this lease, if any.
352 subnet handle examine
354 the subnet object associated with this lease (the subnet object is
355 not currently supported).
356 pool handle examine
358 the pool object associated with this lease (the pool object is not
359 currently supported).
360 billing-class handle examine
362 the handle to the class to which this lease is currently billed,
363 if any (the class object is not currently supported).
364 hardware-address data examine, update
366 the hardware address (chaddr) field sent by the client when it
367 acquired its lease.
368 hardware-type integer examine, update
370 the type of the network interface that the client reported when it
371 acquired its lease.
372 ends time examine
374 the time when the lease's current state ends, as understood by the
375 client.
376 tstp time examine
378 the time when the lease's current state ends, as understood by the
379 server.
380 tsfp time examine
381 the adjusted time when the lease's current state ends, as under‐
382 stood by the failover peer (if there is no failover peer, this
383 value is undefined). Generally this value is only adjusted for
384 expired, released, or reset leases while the server is operating
385 in partner-down state, and otherwise is simply the value supplied
386 by the peer.
387 atsfp time examine
388 the actual tsfp value sent from the peer. This value is forgotten
389 when a lease binding state change is made, to facilitate retrans‐
390 mission logic.
391 cltt time examine
393 The time of the last transaction with the client on this lease.
394
396 Hosts can be created, destroyed, looked up, examined and modified. If
397 a host declaration is created or deleted using OMAPI, that information
398 will be recorded in the dhcpd.leases file. It is permissible to
399 delete host declarations that are declared in the dhcpd.conf file.
400 Hosts have the following attributes:
402 name data lookup, examine, modify
404 the name of the host declaration. This name must be unique among
405 all host declarations.
406 group handle examine, modify
408 the named group associated with the host declaration, if there is
409 one.
410 hardware-address data lookup, examine, modify
412 the link-layer address that will be used to match the client, if
413 any. Only valid if hardware-type is also present.
414 hardware-type integer lookup, examine, modify
416 the type of the network interface that will be used to match the
417 client, if any. Only valid if hardware-address is also present.
418 dhcp-client-identifier data lookup, examine, modify
420 the dhcp-client-identifier option that will be used to match the
421 client, if any.
422 ip-address data examine, modify
424 a fixed IP address which is reserved for a DHCP client that
425 matches this host declaration. The IP address will only be
426 assigned to the client if it is valid for the network segment to
427 which the client is connected.
428 statements data modify
430 a list of statements in the format of the dhcpd.conf file that
431 will be executed whenever a message from the client is being pro‐
432 cessed.
433 known integer examine, modify
435 if nonzero, indicates that a client matching this host declaration
436 will be treated as known in pool permit lists. If zero, the
437 client will not be treated as known.
438
440 Named groups can be created, destroyed, looked up, examined and modi‐
441 fied. If a group declaration is created or deleted using OMAPI, that
442 information will be recorded in the dhcpd.leases file. It is permissi‐
443 ble to delete group declarations that are declared in the dhcpd.conf
444 file.
445 Named groups currently can only be associated with hosts - this allows
447 one set of statements to be efficiently attached to more than one host
448 declaration.
449 Groups have the following attributes:
451 name data
453 the name of the group. All groups that are created using OMAPI
454 must have names, and the names must be unique among all groups.
455 statements data
457 a list of statements in the format of the dhcpd.conf file that
458 will be executed whenever a message from a client whose host dec‐
459 laration references this group is processed.
460
462 The control object allows you to shut the server down. If the server
463 is doing failover with another peer, it will make a clean transition
464 into the shutdown state and notify its peer, so that the peer can go
465 into partner down, and then record the "recover" state in the lease
466 file so that when the server is restarted, it will automatically resyn‐
467 chronize with its peer.
468 On shutdown the server will also attempt to cleanly shut down all OMAPI
470 connections. If these connections do not go down cleanly after five
471 seconds, they are shut down preemptively. It can take as much as 25
472 seconds from the beginning of the shutdown process to the time that the
473 server actually exits.
474 To shut the server down, open its control object and set the state
476 attribute to 2.
477
479 The failover-state object is the object that tracks the state of the
480 failover protocol as it is being managed for a given failover peer.
481 The failover object has the following attributes (please see dhcpd.conf
482 [1m(5) for explanations about what these attributes mean):
483 name data examine
485 Indicates the name of the failover peer relationship, as described
486 in the server's dhcpd.conf file.
487 partner-address data examine
489 Indicates the failover partner's IP address.
490 local-address data examine
492 Indicates the IP address that is being used by the DHCP server for
493 this failover pair.
494 partner-port data examine
496 Indicates the TCP port on which the failover partner is listening
497 for failover protocol connections.
498 local-port data examine
500 Indicates the TCP port on which the DHCP server is listening for
501 failover protocol connections for this failover pair.
502 max-outstanding-updates integer examine
504 Indicates the number of updates that can be outstanding and unac‐
505 knowledged at any given time, in this failover relationship.
506 mclt integer examine
508 Indicates the maximum client lead time in this failover relation‐
509 ship.
510 load-balance-max-secs integer examine
512 Indicates the maximum value for the secs field in a client request
513 before load balancing is bypassed.
514 load-balance-hba data examine
516 Indicates the load balancing hash bucket array for this failover
517 relationship.
518 local-state integer examine, modify
520 Indicates the present state of the DHCP server in this failover
521 relationship. Possible values for state are:
522 1 - startup
524 2 - normal
525 3 - communications interrupted
526 4 - partner down
527 5 - potential conflict
528 6 - recover
529 7 - paused
530 8 - shutdown
531 9 - recover done
532 10 - resolution interrupted
533 11 - conflict done
534 254 - recover wait
535 (Note that some of the above values have changed since DHCP
537 3.0.x.)
538 In general it is not a good idea to make changes to this state.
540 However, in the case that the failover partner is known to be
541 down, it can be useful to set the DHCP server's failover state to
542 partner down. At this point the DHCP server will take over ser‐
543 vice of the failover partner's leases as soon as possible, and
544 will give out normal leases, not leases that are restricted by
545 MCLT. If you do put the DHCP server into the partner-down when
546 the other DHCP server is not in the partner-down state, but is not
547 reachable, IP address assignment conflicts are possible, even
548 likely. Once a server has been put into partner-down mode, its
549 failover partner must not be brought back online until communica‐
550 tion is possible between the two servers.
551 partner-state integer examine
553 Indicates the present state of the failover partner.
554 local-stos integer examine
556 Indicates the time at which the DHCP server entered its present
557 state in this failover relationship.
558 partner-stos integer examine
560 Indicates the time at which the failover partner entered its
561 present state.
562 hierarchy integer examine
564 Indicates whether the DHCP server is primary (0) or secondary (1)
565 in this failover relationship.
566 last-packet-sent integer examine
568 Indicates the time at which the most recent failover packet was
569 sent by this DHCP server to its failover partner.
570 last-timestamp-received integer examine
572 Indicates the timestamp that was on the failover message most
573 recently received from the failover partner.
574 skew integer examine
576 Indicates the skew between the failover partner's clock and this
577 DHCP server's clock
578 max-response-delay integer examine
580 Indicates the time in seconds after which, if no message is
581 received from the failover partner, the partner is assumed to be
582 out of communication.
583 cur-unacked-updates integer examine
585 Indicates the number of update messages that have been received
586 from the failover partner but not yet processed.
587
589 /etc/dhcp/dhcpd.conf, /var/lib/dhcpd/dhcpd.leases, /var/run/dhcpd.pid,
590 /var/lib/dhcpd/dhcpd.leases~.
591
593 dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5)
594
596 dhcpd(8) was originally written by Ted Lemon under a contract with
597 Vixie Labs. Funding for this project was provided by Internet Systems
598 Consortium. Version 3 of the DHCP server was funded by Nominum, Inc.
599 Information about Internet Systems Consortium is available at
600 https://www.isc.org/. Information about Nominum can be found at
601 http://www.nominum.com/.
602 dhcpd(8)