]>
Commit | Line | Data |
---|---|---|
08fe7cdb TL |
1 | .\" dhcpd.8 |
2 | .\" | |
98311e4b DH |
3 | .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC") |
4 | .\" Copyright (c) 1996-2003 by Internet Software Consortium | |
08fe7cdb | 5 | .\" |
98311e4b DH |
6 | .\" Permission to use, copy, modify, and distribute this software for any |
7 | .\" purpose with or without fee is hereby granted, provided that the above | |
8 | .\" copyright notice and this permission notice appear in all copies. | |
08fe7cdb | 9 | .\" |
98311e4b DH |
10 | .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES |
11 | .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
12 | .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR | |
13 | .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
14 | .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
15 | .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT | |
16 | .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
08fe7cdb | 17 | .\" |
98311e4b DH |
18 | .\" Internet Systems Consortium, Inc. |
19 | .\" 950 Charter Street | |
20 | .\" Redwood City, CA 94063 | |
21 | .\" <info@isc.org> | |
22 | .\" http://www.isc.org/ | |
23 | .\" | |
24 | .\" This software has been written for Internet Systems Consortium | |
69c620f2 | 25 | .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc. |
98311e4b | 26 | .\" To learn more about Internet Systems Consortium, see |
69c620f2 TL |
27 | .\" ``http://www.isc.org/''. To learn more about Vixie Enterprises, |
28 | .\" see ``http://www.vix.com''. To learn more about Nominum, Inc., see | |
29 | .\" ``http://www.nominum.com''. | |
f49473ba | 30 | .\" |
98311e4b | 31 | .\" $Id: dhcpd.8,v 1.22 2005/03/17 20:15:27 dhankins Exp $ |
f49473ba | 32 | .\" |
ee0cda4d TL |
33 | .TH dhcpd 8 |
34 | .SH NAME | |
5e6b52dc | 35 | dhcpd - Dynamic Host Configuration Protocol Server |
ee0cda4d TL |
36 | .SH SYNOPSIS |
37 | .B dhcpd | |
38 | [ | |
39 | .B -p | |
40 | .I port | |
41 | ] | |
d27562c7 TL |
42 | [ |
43 | .B -f | |
44 | ] | |
45 | [ | |
5e6b52dc TL |
46 | .B -d |
47 | ] | |
48 | [ | |
6edb572b TL |
49 | .B -q |
50 | ] | |
51 | [ | |
897065dc TL |
52 | .B -t |
53 | | | |
54 | .B -T | |
55 | ] | |
56 | [ | |
e2ac5814 TL |
57 | .B -cf |
58 | .I config-file | |
59 | ] | |
60 | [ | |
61 | .B -lf | |
62 | .I lease-file | |
63 | ] | |
64 | [ | |
51fe0cce TL |
65 | .B -tf |
66 | .I trace-output-file | |
67 | ] | |
68 | [ | |
69 | .B -play | |
70 | .I trace-playback-file | |
71 | ] | |
72 | [ | |
d27562c7 TL |
73 | .I if0 |
74 | [ | |
75 | .I ...ifN | |
76 | ] | |
77 | ] | |
ee0cda4d | 78 | .SH DESCRIPTION |
98311e4b | 79 | The Internet Systems Consortium DHCP Server, dhcpd, implements the |
5e6b52dc TL |
80 | Dynamic Host Configuration Protocol (DHCP) and the Internet Bootstrap |
81 | Protocol (BOOTP). DHCP allows hosts on a TCP/IP network to request | |
82 | and be assigned IP addresses, and also to discover information about | |
83 | the network to which they are attached. BOOTP provides similar | |
84 | functionality, with certain restrictions. | |
f21a7b4a TL |
85 | .SH CONTRIBUTIONS |
86 | .PP | |
46a65180 TL |
87 | This software is free software. At various times its development has |
88 | been underwritten by various organizations, including the ISC and | |
89 | Vixie Enterprises. The development of 3.0 has been funded almost | |
90 | entirely by Nominum, Inc. | |
91 | .PP | |
92 | At this point development is being shepherded by Ted Lemon, and hosted | |
93 | by the ISC, but the future of this project depends on you. If you | |
94 | have features you want, please consider implementing them. | |
ee0cda4d TL |
95 | .SH OPERATION |
96 | .PP | |
08fe7cdb TL |
97 | The DHCP protocol allows a host which is unknown to the network |
98 | administrator to be automatically assigned a new IP address out of a | |
99 | pool of IP addresses for its network. In order for this to work, the | |
100 | network administrator allocates address pools in each subnet and | |
ee0cda4d TL |
101 | enters them into the dhcpd.conf(5) file. |
102 | .PP | |
08fe7cdb | 103 | On startup, dhcpd reads the |
ee0cda4d | 104 | .IR dhcpd.conf |
5e6b52dc TL |
105 | file and stores a list of available addresses on each subnet in |
106 | memory. When a client requests an address using the DHCP protocol, | |
107 | dhcpd allocates an address for it. Each client is assigned a lease, | |
108 | which expires after an amount of time chosen by the administrator (by | |
109 | default, one day). Before leases expire, the clients to which leases | |
110 | are assigned are expected to renew them in order to continue to use | |
111 | the addresses. Once a lease has expired, the client to which that | |
112 | lease was assigned is no longer permitted to use the leased IP | |
113 | address. | |
ee0cda4d | 114 | .PP |
08fe7cdb | 115 | In order to keep track of leases across system reboots and server |
ee0cda4d TL |
116 | restarts, dhcpd keeps a list of leases it has assigned in the |
117 | dhcpd.leases(5) file. Before dhcpd grants a lease to a host, it | |
118 | records the lease in this file and makes sure that the contents of the | |
119 | file are flushed to disk. This ensures that even in the event of a | |
120 | system crash, dhcpd will not forget about a lease that it has | |
121 | assigned. On startup, after reading the dhcpd.conf file, dhcpd | |
122 | reads the dhcpd.leases file to refresh its memory about what leases | |
123 | have been assigned. | |
124 | .PP | |
125 | New leases are appended to the end of the dhcpd.leases | |
08fe7cdb | 126 | file. In order to prevent the file from becoming arbitrarily large, |
ee0cda4d TL |
127 | from time to time dhcpd creates a new dhcpd.leases file from its |
128 | in-core lease database. Once this file has been written to disk, the | |
129 | old file is renamed | |
130 | .IR dhcpd.leases~ , | |
131 | and the new file is renamed dhcpd.leases. If the system crashes in | |
132 | the middle of this process, whichever dhcpd.leases file remains will | |
133 | contain all the lease information, so there is no need for a special | |
134 | crash recovery process. | |
135 | .PP | |
5e6b52dc TL |
136 | BOOTP support is also provided by this server. Unlike DHCP, the BOOTP |
137 | protocol does not provide a protocol for recovering | |
138 | dynamically-assigned addresses once they are no longer needed. It is | |
139 | still possible to dynamically assign addresses to BOOTP clients, but | |
140 | some administrative process for reclaiming addresses is required. By | |
141 | default, leases are granted to BOOTP clients in perpetuity, although | |
142 | the network administrator may set an earlier cutoff date or a shorter | |
143 | lease length for BOOTP leases if that makes sense. | |
144 | .PP | |
145 | BOOTP clients may also be served in the old standard way, which is to | |
146 | simply provide a declaration in the dhcpd.conf file for each | |
147 | BOOTP client, permanently assigning an address to each client. | |
ee0cda4d TL |
148 | .PP |
149 | Whenever changes are made to the dhcpd.conf file, dhcpd must be | |
150 | restarted. To restart dhcpd, send a SIGTERM (signal 15) to the | |
151 | process ID contained in | |
5e6b52dc TL |
152 | .IR RUNDIR/dhcpd.pid , |
153 | and then re-invoke dhcpd. Because the DHCP server database is not as | |
154 | lightweight as a BOOTP database, dhcpd does not automatically restart | |
155 | itself when it sees a change to the dhcpd.conf file. | |
4e19a6df TL |
156 | .PP |
157 | Note: We get a lot of complaints about this. We realize that it would | |
158 | be nice if one could send a SIGHUP to the server and have it reload | |
159 | the database. This is not technically impossible, but it would | |
160 | require a great deal of work, our resources are extremely limited, and | |
161 | they can be better spent elsewhere. So please don't complain about | |
162 | this on the mailing list unless you're prepared to fund a project to | |
163 | implement this feature, or prepared to do it yourself. | |
d27562c7 TL |
164 | .SH COMMAND LINE |
165 | .PP | |
5e6b52dc TL |
166 | The names of the network interfaces on which dhcpd should listen for |
167 | broadcasts may be specified on the command line. This should be done | |
168 | on systems where dhcpd is unable to identify non-broadcast interfaces, | |
169 | but should not be required on other systems. If no interface names | |
170 | are specified on the command line dhcpd will identify all network | |
98311e4b | 171 | interfaces which are up, eliminating non-broadcast interfaces if |
5e6b52dc | 172 | possible, and listen for DHCP broadcasts on each interface. |
d27562c7 | 173 | .PP |
5e6b52dc TL |
174 | If dhcpd should listen on a port other than the standard (port 67), |
175 | the | |
d27562c7 | 176 | .B -p |
5e6b52dc TL |
177 | flag may used. It should be followed by the udp port number on which |
178 | dhcpd should listen. This is mostly useful for debugging purposes. | |
d27562c7 | 179 | .PP |
5e6b52dc TL |
180 | To run dhcpd as a foreground process, rather than allowing it to run |
181 | as a daemon in the background, the | |
d27562c7 | 182 | .B -f |
5e6b52dc TL |
183 | flag should be specified. This is useful when running dhcpd under a |
184 | debugger, or when running it out of inittab on System V systems. | |
185 | .PP | |
186 | To have dhcpd log to the standard error descriptor, specify the | |
187 | .B -d | |
188 | flag. This can be useful for debugging, and also at sites where a | |
189 | complete log of all dhcp activity must be kept but syslogd is not | |
190 | reliable or otherwise cannot be used. Normally, dhcpd will log all | |
191 | output using the syslog(3) function with the log facility set to | |
192 | LOG_DAEMON. | |
e2ac5814 TL |
193 | .PP |
194 | Dhcpd can be made to use an alternate configuration file with the | |
195 | .B -cf | |
196 | flag, or an alternate lease file with the | |
197 | .B -lf | |
198 | flag. Because of the importance of using the same lease database at | |
199 | all times when running dhcpd in production, these options should be | |
200 | used \fBonly\fR for testing lease files or database files in a | |
201 | non-production environment. | |
6edb572b TL |
202 | .PP |
203 | When starting dhcpd up from a system startup script (e.g., /etc/rc), | |
204 | it may not be desirable to print out the entire copyright message on | |
205 | startup. To avoid printing this message, the | |
206 | .B -q | |
207 | flag may be specified. | |
897065dc TL |
208 | .PP |
209 | The DHCP server reads two files on startup: a configuration file, and | |
210 | a lease database. If the | |
211 | .B -t | |
212 | flag is specified, the server will simply test the configuration file | |
213 | for correct syntax, but will not attempt to perform any network | |
214 | operations. This can be used to test the a new configuration file | |
215 | automatically before installing it. | |
216 | .PP | |
217 | The | |
218 | .B -T | |
219 | flag can be used to test the lease database file in a similar way. | |
51fe0cce TL |
220 | .PP |
221 | The \fB-tf\fR and \fB-play\fR options allow you to specify a file into | |
222 | which the entire startup state of the server and all the transactions | |
223 | it processes are either logged or played back from. This can be | |
224 | useful in submitting bug reports - if you are getting a core dump | |
225 | every so often, you can start the server with the \fB-tf\fR option and | |
226 | then, when the server dumps core, the trace file will contain all the | |
227 | transactions that led up to it dumping core, so that the problem can | |
228 | be easily debugged with \fB-play\fR. | |
229 | .PP | |
230 | The \fB-play\fR option must be specified with an alternate lease file, | |
231 | using the \fB-lf\fR switch, so that the DHCP server doesn't wipe out | |
232 | your existing lease file with its test data. The DHCP server will | |
233 | refuse to operate in playback mode unless you specify an alternate | |
234 | lease file. | |
ee0cda4d | 235 | .SH CONFIGURATION |
98311e4b | 236 | The syntax of the dhcpd.conf(5) file is discussed separately. This |
ee0cda4d | 237 | section should be used as an overview of the configuration process, |
ba7ed239 | 238 | and the dhcpd.conf(5) documentation should be consulted for detailed |
ee0cda4d TL |
239 | reference information. |
240 | .PP | |
241 | .SH Subnets | |
242 | dhcpd needs to know the subnet numbers and netmasks of all subnets for | |
243 | which it will be providing service. In addition, in order to | |
244 | dynamically allocate addresses, it must be assigned one or more ranges | |
245 | of addresses on each subnet which it can in turn assign to client | |
246 | hosts as they boot. Thus, a very simple configuration providing DHCP | |
08fe7cdb TL |
247 | support might look like this: |
248 | .nf | |
249 | .sp 1 | |
5e6b52dc | 250 | subnet 239.252.197.0 netmask 255.255.255.0 { |
08fe7cdb | 251 | range 239.252.197.10 239.252.197.250; |
98311e4b | 252 | } |
08fe7cdb | 253 | .fi |
ee0cda4d | 254 | .PP |
08fe7cdb TL |
255 | Multiple address ranges may be specified like this: |
256 | .nf | |
257 | .sp 1 | |
5e6b52dc TL |
258 | subnet 239.252.197.0 netmask 255.255.255.0 { |
259 | range 239.252.197.10 239.252.197.107; | |
08fe7cdb | 260 | range 239.252.197.113 239.252.197.250; |
5e6b52dc | 261 | } |
08fe7cdb | 262 | .fi |
ee0cda4d | 263 | .PP |
08fe7cdb TL |
264 | If a subnet will only be provided with BOOTP service and no dynamic |
265 | address assignment, the range clause can be left out entirely, but the | |
266 | subnet statement must appear. | |
ee0cda4d TL |
267 | .PP |
268 | .SH Lease Lengths | |
08fe7cdb TL |
269 | DHCP leases can be assigned almost any length from zero seconds to |
270 | infinity. What lease length makes sense for any given subnet, or for | |
271 | any given installation, will vary depending on the kinds of hosts | |
272 | being served. | |
ee0cda4d | 273 | .PP |
08fe7cdb TL |
274 | For example, in an office environment where systems are added from |
275 | time to time and removed from time to time, but move relatively | |
276 | infrequently, it might make sense to allow lease times of a month of | |
277 | more. In a final test environment on a manufacturing floor, it may | |
278 | make more sense to assign a maximum lease length of 30 minutes - | |
279 | enough time to go through a simple test procedure on a network | |
280 | appliance before packaging it up for delivery. | |
ee0cda4d | 281 | .PP |
08fe7cdb TL |
282 | It is possible to specify two lease lengths: the default length that |
283 | will be assigned if a client doesn't ask for any particular lease | |
284 | length, and a maximum lease length. These are specified as clauses | |
285 | to the subnet command: | |
286 | .nf | |
287 | .sp 1 | |
5e6b52dc TL |
288 | subnet 239.252.197.0 netmask 255.255.255.0 { |
289 | range 239.252.197.10 239.252.197.107; | |
290 | default-lease-time 600; | |
08fe7cdb | 291 | max-lease-time 7200; |
98311e4b | 292 | } |
08fe7cdb | 293 | .fi |
ee0cda4d | 294 | .PP |
08fe7cdb TL |
295 | This particular subnet declaration specifies a default lease time of |
296 | 600 seconds (ten minutes), and a maximum lease time of 7200 seconds | |
297 | (two hours). Other common values would be 86400 (one day), 604800 | |
298 | (one week) and 2592000 (30 days). | |
ee0cda4d | 299 | .PP |
08fe7cdb TL |
300 | Each subnet need not have the same lease\(emin the case of an office |
301 | environment and a manufacturing environment served by the same DHCP | |
302 | server, it might make sense to have widely disparate values for | |
303 | default and maximum lease times on each subnet. | |
ee0cda4d TL |
304 | .SH BOOTP Support |
305 | Each BOOTP client must be explicitly declared in the dhcpd.conf | |
08fe7cdb TL |
306 | file. A very basic client declaration will specify the client |
307 | network interface's hardware address and the IP address to assign to | |
308 | that client. If the client needs to be able to load a boot file from | |
309 | the server, that file's name must be specified. A simple bootp | |
310 | client declaration might look like this: | |
311 | .nf | |
312 | .sp 1 | |
fc5aedc9 TL |
313 | host haagen { |
314 | hardware ethernet 08:00:2b:4c:59:23; | |
5e6b52dc | 315 | fixed-address 239.252.197.9; |
08fe7cdb | 316 | filename "/tftpboot/haagen.boot"; |
5e6b52dc | 317 | } |
08fe7cdb | 318 | .fi |
ee0cda4d | 319 | .SH Options |
08fe7cdb TL |
320 | DHCP (and also BOOTP with Vendor Extensions) provide a mechanism |
321 | whereby the server can provide the client with information about how | |
322 | to configure its network interface (e.g., subnet mask), and also how | |
323 | the client can access various network services (e.g., DNS, IP routers, | |
324 | and so on). | |
ee0cda4d | 325 | .PP |
08fe7cdb TL |
326 | These options can be specified on a per-subnet basis, and, for BOOTP |
327 | clients, also on a per-client basis. In the event that a BOOTP | |
328 | client declaration specifies options that are also specified in its | |
329 | subnet declaration, the options specified in the client declaration | |
98311e4b | 330 | take precedence. A reasonably complete DHCP configuration might |
08fe7cdb TL |
331 | look something like this: |
332 | .nf | |
333 | .sp 1 | |
5e6b52dc TL |
334 | subnet 239.252.197.0 netmask 255.255.255.0 { |
335 | range 239.252.197.10 239.252.197.250; | |
336 | default-lease-time 600 max-lease-time 7200; | |
337 | option subnet-mask 255.255.255.0; | |
338 | option broadcast-address 239.252.197.255; | |
339 | option routers 239.252.197.1; | |
340 | option domain-name-servers 239.252.197.2, 239.252.197.3; | |
08fe7cdb | 341 | option domain-name "isc.org"; |
5e6b52dc | 342 | } |
08fe7cdb | 343 | .fi |
ee0cda4d | 344 | .PP |
08fe7cdb TL |
345 | A bootp host on that subnet that needs to be in a different domain and |
346 | use a different name server might be declared as follows: | |
347 | .nf | |
348 | .sp 1 | |
ba7ed239 TL |
349 | host haagen { |
350 | hardware ethernet 08:00:2b:4c:59:23; | |
5e6b52dc TL |
351 | fixed-address 239.252.197.9; |
352 | filename "/tftpboot/haagen.boot"; | |
353 | option domain-name-servers 192.5.5.1; | |
08fe7cdb | 354 | option domain-name "vix.com"; |
5e6b52dc | 355 | } |
08fe7cdb | 356 | .fi |
ee0cda4d | 357 | .PP |
5e6b52dc TL |
358 | A more complete description of the dhcpd.conf file syntax is provided |
359 | in dhcpd.conf(5). | |
90e0ef94 TL |
360 | .SH OMAPI |
361 | The DHCP server provides the capability to modify some of its | |
362 | configuration while it is running, without stopping it, modifying its | |
363 | database files, and restarting it. This capability is currently | |
364 | provided using OMAPI - an API for manipulating remote objects. OMAPI | |
365 | clients connect to the server using TCP/IP, authenticate, and can then | |
366 | examine the server's current status and make changes to it. | |
367 | .PP | |
368 | Rather than implementing the underlying OMAPI protocol directly, user | |
369 | programs should use the dhcpctl API or OMAPI itself. Dhcpctl is a | |
370 | wrapper that handles some of the housekeeping chores that OMAPI does | |
371 | not do automatically. Dhcpctl and OMAPI are documented in \fBdhcpctl(3)\fR | |
372 | and \fBomapi(3)\fR. | |
373 | .PP | |
374 | OMAPI exports objects, which can then be examined and modified. The | |
375 | DHCP server exports the following objects: lease, host, | |
376 | failover-state and group. Each object has a number of methods that | |
377 | are provided: lookup, create, and destroy. In addition, it is | |
378 | possible to look at attributes that are stored on objects, and in some | |
379 | cases to modify those attributes. | |
380 | .SH THE LEASE OBJECT | |
381 | Leases can't currently be created or destroyed, but they can be looked | |
382 | up to examine and modify their state. | |
383 | .PP | |
384 | Leases have the following attributes: | |
385 | .PP | |
386 | .B state \fIinteger\fR lookup, examine | |
387 | .RS 0.5i | |
388 | .nf | |
389 | 1 = free | |
390 | 2 = active | |
391 | 3 = expired | |
392 | 4 = released | |
393 | 5 = abandoned | |
394 | 6 = reset | |
395 | 7 = backup | |
396 | 8 = reserved | |
397 | 9 = bootp | |
398 | .fi | |
399 | .RE | |
400 | .PP | |
401 | .B ip-address \fIdata\fR lookup, examine | |
402 | .RS 0.5i | |
403 | The IP address of the lease. | |
404 | .RE | |
405 | .PP | |
406 | .B dhcp-client-identifier \fIdata\fR lookup, examine, update | |
407 | .RS 0.5i | |
408 | The | |
409 | client identifier that the client used when it acquired the lease. | |
410 | Not all clients send client identifiers, so this may be empty. | |
411 | .RE | |
412 | .PP | |
413 | .B client-hostname \fIdata\fR examine, update | |
414 | .RS 0.5i | |
415 | The value the client sent in the host-name option. | |
416 | .RE | |
417 | .PP | |
418 | .B host \fIhandle\fR examine | |
419 | .RS 0.5i | |
420 | the host declaration associated with this lease, if any. | |
421 | .RE | |
422 | .PP | |
423 | .B subnet \fIhandle\fR examine | |
424 | .RS 0.5i | |
425 | the subnet object associated with this lease (the subnet object is not | |
426 | currently supported). | |
427 | .RE | |
428 | .PP | |
429 | .B pool \fIhandle\fR examine | |
430 | .RS 0.5i | |
431 | the pool object associted with this lease (the pool object is not | |
432 | currently supported). | |
433 | .RE | |
434 | .PP | |
435 | .B billing-class \fIhandle\fR examine | |
436 | .RS 0.5i | |
437 | the handle to the class to which this lease is currently billed, if | |
438 | any (the class object is not currently supported). | |
439 | .RE | |
440 | .PP | |
441 | .B hardware-address \fIdata\fR examine, update | |
442 | .RS 0.5i | |
443 | the hardware address (chaddr) field sent by the client when it | |
444 | acquired its lease. | |
445 | .RE | |
446 | .PP | |
447 | .B hardware-type \fIinteger\fR examine, update | |
448 | .RS 0.5i | |
449 | the type of the network interface that the client reported when it | |
450 | acquired its lease. | |
451 | .RE | |
452 | .PP | |
453 | .B ends \fItime\fR examine | |
454 | .RS 0.5i | |
455 | the time when the lease's current state ends, as understood by the | |
456 | client. | |
457 | .RE | |
458 | .PP | |
459 | .B tstp \fItime\fR examine | |
460 | .RS 0.5i | |
461 | the time when the lease's current state ends, as understood by the | |
462 | server. | |
463 | .RE | |
464 | .B tsfp \fItime\fR examine | |
465 | .RS 0.5i | |
466 | the time when the lease's current state ends, as understood by the | |
467 | failover peer (if there is no failover peer, this value is | |
468 | undefined). | |
469 | .RE | |
470 | .PP | |
471 | .B cltt \fItime\fR examine | |
472 | .RS 0.5i | |
473 | The time of the last transaction with the client on this lease. | |
474 | .RE | |
475 | .SH THE HOST OBJECT | |
476 | Hosts can be created, destroyed, looked up, examined and modified. | |
477 | If a host declaration is created or deleted using OMAPI, that | |
478 | information will be recorded in the dhcpd.leases file. It is | |
479 | permissible to delete host declarations that are declared in the | |
480 | dhcpd.conf file. | |
481 | .PP | |
482 | Hosts have the following attributes: | |
483 | .PP | |
484 | .B name \fIdata\fR lookup, examine, modify | |
485 | .RS 0.5i | |
486 | the name of the host declaration. This name must be unique among all | |
487 | host declarations. | |
488 | .RE | |
489 | .PP | |
490 | .B group \fIhandle\fR examine, modify | |
491 | .RS 0.5i | |
492 | the named group associated with the host declaration, if there is one. | |
493 | .RE | |
494 | .PP | |
495 | .B hardware-address \fIdata\fR lookup, examine, modify | |
496 | .RS 0.5i | |
497 | the link-layer address that will be used to match the client, if any. | |
498 | Only valid if hardware-type is also present. | |
499 | .RE | |
500 | .PP | |
501 | .B hardware-type \fIinteger\fR lookup, examine, modify | |
502 | .RS 0.5i | |
503 | the type of the network interface that will be used to match the | |
504 | client, if any. Only valid if hardware-address is also present. | |
505 | .RE | |
506 | .PP | |
507 | .B dhcp-client-identifier \fIdata\fR lookup, examine, modify | |
508 | .RS 0.5i | |
509 | the dhcp-client-identifier option that will be used to match the | |
510 | client, if any. | |
511 | .RE | |
512 | .PP | |
513 | .B ip-address \fIdata\fR examine, modify | |
514 | .RS 0.5i | |
515 | a fixed IP address which is reserved for a DHCP client that matches | |
516 | this host declaration. The IP address will only be assigned to the | |
517 | client if it is valid for the network segment to which the client is | |
518 | connected. | |
519 | .RE | |
520 | .PP | |
521 | .B statements \fIdata\fR modify | |
522 | .RS 0.5i | |
523 | a list of statements in the format of the dhcpd.conf file that will be | |
524 | executed whenever a message from the client is being processed. | |
525 | .RE | |
526 | .PP | |
527 | .B known \fIinteger\fR examine, modify | |
528 | .RS 0.5i | |
529 | if nonzero, indicates that a client matching this host declaration | |
530 | will be treated as \fIknown\fR in pool permit lists. If zero, the | |
531 | client will not be treated as known. | |
532 | .RE | |
533 | .SH THE GROUP OBJECT | |
534 | Named groups can be created, destroyed, looked up, examined and | |
535 | modified. If a group declaration is created or deleted using OMAPI, | |
536 | that information will be recorded in the dhcpd.leases file. It is | |
537 | permissible to delete group declarations that are declared in the | |
538 | dhcpd.conf file. | |
539 | .PP | |
540 | Named groups currently can only be associated with | |
541 | hosts - this allows one set of statements to be efficiently attached | |
542 | to more than one host declaration. | |
543 | .PP | |
544 | Groups have the following attributes: | |
545 | .PP | |
546 | .B name \fIdata\fR | |
547 | .RS 0.5i | |
548 | the name of the group. All groups that are created using OMAPI must | |
549 | have names, and the names must be unique among all groups. | |
550 | .RE | |
551 | .PP | |
552 | .B statements \fIdata\fR | |
553 | .RS 0.5i | |
554 | a list of statements in the format of the dhcpd.conf file that will be | |
555 | executed whenever a message from a client whose host declaration | |
556 | references this group is processed. | |
557 | .RE | |
d758ad8c TL |
558 | .SH THE CONTROL OBJECT |
559 | The control object allows you to shut the server down. If the server | |
560 | is doing failover with another peer, it will make a clean transition | |
561 | into the shutdown state and notify its peer, so that the peer can go | |
562 | into partner down, and then record the "recover" state in the lease | |
563 | file so that when the server is restarted, it will automatically | |
564 | resynchronize with its peer. | |
565 | .PP | |
566 | On shutdown the server will also attempt to cleanly shut down all | |
567 | OMAPI connections. If these connections do not go down cleanly after | |
568 | five seconds, they are shut down pre-emptively. It can take as much | |
569 | as 25 seconds from the beginning of the shutdown process to the time | |
570 | that the server actually exits. | |
571 | .PP | |
572 | To shut the server down, open its control object and set the state | |
573 | attribute to 2. | |
0db87765 TL |
574 | .SH THE FAILOVER-STATE OBJECT |
575 | The failover-state object is the object that tracks the state of the | |
576 | failover protocol as it is being managed for a given failover peer. | |
577 | The failover object has the following attributes (please see | |
578 | .B dhcpd.conf (5) | |
579 | for explanations about what these attributes mean): | |
580 | .PP | |
581 | .B name \fIdata\fR examine | |
582 | .RS 0.5i | |
583 | Indicates the name of the failover peer relationship, as described in | |
584 | the server's \fBdhcpd.conf\fR file. | |
585 | .RE | |
586 | .PP | |
587 | .B partner-address \fIdata\fR examine | |
588 | .RS 0.5i | |
589 | Indicates the failover partner's IP address. | |
590 | .RE | |
591 | .PP | |
592 | .B local-address \fIdata\fR examine | |
593 | .RS 0.5i | |
594 | Indicates the IP address that is being used by the DHCP server for | |
595 | this failover pair. | |
596 | .RE | |
597 | .PP | |
598 | .B partner-port \fIdata\fR examine | |
599 | .RS 0.5i | |
600 | Indicates the TCP port on which the failover partner is listening for | |
601 | failover protocol connections. | |
602 | .RE | |
603 | .PP | |
604 | .B local-port \fIdata\fR examine | |
605 | .RS 0.5i | |
606 | Indicates the TCP port on which the DHCP server is listening for | |
607 | failover protocol connections for this failover pair. | |
608 | .RE | |
609 | .PP | |
610 | .B max-outstanding-updates \fIinteger\fR examine | |
611 | .RS 0.5i | |
612 | Indicates the number of updates that can be outstanding and | |
613 | unacknowledged at any given time, in this failover relationship. | |
614 | .RE | |
615 | .PP | |
616 | .B mclt \fIinteger\fR examine | |
617 | .RS 0.5i | |
618 | Indicates the maximum client lead time in this failover relationship. | |
619 | .RE | |
620 | .PP | |
621 | .B load-balance-max-secs \fIinteger\fR examine | |
622 | .RS 0.5i | |
623 | Indicates the maximum value for the secs field in a client request | |
624 | before load balancing is bypassed. | |
625 | .RE | |
626 | .PP | |
627 | .B load-balance-hba \fIdata\fR examine | |
628 | .RS 0.5i | |
629 | Indicates the load balancing hash bucket array for this failover | |
630 | relationship. | |
631 | .RE | |
632 | .PP | |
633 | .B local-state \fIinteger\fR examine, modify | |
634 | .RS 0.5i | |
635 | Indicates the present state of the DHCP server in this failover | |
636 | relationship. Possible values for state are: | |
637 | .RE | |
638 | .RS 1i | |
639 | .PP | |
640 | .nf | |
641 | 1 - partner down | |
642 | 2 - normal | |
643 | 3 - communications interrupted | |
644 | 4 - resolution interrupted | |
645 | 5 - potential conflict | |
646 | 6 - recover | |
647 | 7 - recover done | |
648 | 8 - shutdown | |
649 | 9 - paused | |
650 | 10 - startup | |
651 | 11 - recover wait | |
652 | .fi | |
653 | .RE | |
654 | .PP | |
655 | .RS 0.5i | |
656 | In general it is not a good idea to make changes to this state. | |
657 | However, in the case that the failover partner is known to be down, it | |
658 | can be useful to set the DHCP server's failover state to partner | |
659 | down. At this point the DHCP server will take over service of the | |
660 | failover partner's leases as soon as possible, and will give out | |
661 | normal leases, not leases that are restricted by MCLT. If you do put | |
662 | the DHCP server into the partner-down when the other DHCP server is | |
663 | not in the partner-down state, but is not reachable, IP address | |
664 | assignment conflicts are possible, even likely. Once a server has | |
665 | been put into partner-down mode, its failover partner must not be | |
666 | brought back online until communication is possible between the two | |
667 | servers. | |
668 | .RE | |
669 | .PP | |
670 | .B partner-state \fIinteger\fR examine | |
671 | .RS 0.5i | |
672 | Indicates the present state of the failover partner. | |
673 | .RE | |
674 | .PP | |
675 | .B local-stos \fIinteger\fR examine | |
676 | .RS 0.5i | |
677 | Indicates the time at which the DHCP server entered its present state | |
678 | in this failover relationship. | |
679 | .RE | |
680 | .PP | |
681 | .B partner-stos \fIinteger\fR examine | |
682 | .RS 0.5i | |
683 | Indicates the time at which the failover partner entered its present state. | |
684 | .RE | |
685 | .PP | |
686 | .B hierarchy \fIinteger\fR examine | |
687 | .RS 0.5i | |
688 | Indicates whether the DHCP server is primary (0) or secondary (1) in | |
689 | this failover relationship. | |
690 | .RE | |
691 | .PP | |
692 | .B last-packet-sent \fIinteger\fR examine | |
693 | .RS 0.5i | |
694 | Indicates the time at which the most recent failover packet was sent | |
695 | by this DHCP server to its failover partner. | |
696 | .RE | |
697 | .PP | |
698 | .B last-timestamp-received \fIinteger\fR examine | |
699 | .RS 0.5i | |
700 | Indicates the timestamp that was on the failover message most recently | |
701 | received from the failover partner. | |
702 | .RE | |
703 | .PP | |
704 | .B skew \fIinteger\fR examine | |
705 | .RS 0.5i | |
706 | Indicates the skew between the failover partner's clock and this DHCP | |
707 | server's clock | |
708 | .RE | |
709 | .PP | |
710 | .B max-response-delay \fIinteger\fR examine | |
711 | .RS 0.5i | |
712 | Indicates the time in seconds after which, if no message is received | |
713 | from the failover partner, the partner is assumed to be out of | |
714 | communication. | |
715 | .RE | |
716 | .PP | |
717 | .B cur-unacked-updates \fIinteger\fR examine | |
718 | .RS 0.5i | |
719 | Indicates the number of update messages that have been received from | |
720 | the failover partner but not yet processed. | |
721 | .RE | |
ee0cda4d TL |
722 | .SH FILES |
723 | .B ETCDIR/dhcpd.conf, DBDIR/dhcpd.leases, RUNDIR/dhcpd.pid, | |
724 | .B DBDIR/dhcpd.leases~. | |
725 | .SH SEE ALSO | |
66b01364 | 726 | dhclient(8), dhcrelay(8), dhcpd.conf(5), dhcpd.leases(5) |
ee0cda4d TL |
727 | .SH AUTHOR |
728 | .B dhcpd(8) | |
90e0ef94 | 729 | was originally written by Ted Lemon under a contract with Vixie Labs. |
98311e4b | 730 | Funding for this project was provided by Internet Systems |
90e0ef94 | 731 | Consortium. Version 3 of the DHCP server was funded by Nominum, Inc. |
98311e4b DH |
732 | Information about Internet Systems Consortium is available at |
733 | .B http://www.isc.org/\fR. | |
734 | Information about Nominum can be found at \fBhttp://www.nominum.com/\fR. |