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