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