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