]>
Commit | Line | Data |
---|---|---|
08fe7cdb TL |
1 | .\" dhcpd.conf.5 |
2 | .\" | |
f39b6e00 TL |
3 | .\" Copyright (c) 1996-1999 Internet Software Consortium. |
4 | .\" Use is subject to license terms which appear in the file named | |
5 | .\" ISC-LICENSE that should have accompanied this file when you | |
6 | .\" received it. If a file named ISC-LICENSE did not accompany this | |
7 | .\" file, or you are not sure the one you have is correct, you may | |
8 | .\" obtain an applicable copy of the license at: | |
08fe7cdb | 9 | .\" |
f39b6e00 | 10 | .\" http://www.isc.org/isc-license-1.0.html. |
08fe7cdb | 11 | .\" |
f39b6e00 TL |
12 | .\" This file is part of the ISC DHCP distribution. The documentation |
13 | .\" associated with this file is listed in the file DOCUMENTATION, | |
14 | .\" included in the top-level directory of this release. | |
08fe7cdb | 15 | .\" |
f39b6e00 TL |
16 | .\" Support and other services are available for ISC products - see |
17 | .\" http://www.isc.org for more information. | |
5e6b52dc | 18 | .TH dhcpd.conf 5 |
d250c5b9 TL |
19 | .SH NAME |
20 | dhcpd.conf - dhcpd configuration file | |
21 | .SH DESCRIPTION | |
22 | The dhcpd.conf file contains configuration information for | |
5e6b52dc TL |
23 | .IR dhcpd, |
24 | the Internet Software Consortium DHCP Server. | |
25 | .PP | |
26 | The dhcpd.conf file is a free-form ASCII text file. It is parsed by | |
27 | the recursive-descent parser built into dhcpd. The file may contain | |
28 | extra tabs and newlines for formatting purposes. Keywords in the file | |
29 | are case-insensitive. Comments may be placed anywhere within the | |
30 | file (except within quotes). Comments begin with the # character and | |
31 | end at the end of the line. | |
32 | .PP | |
33 | The file essentially consists of a list of statements. Statements | |
34 | fall into two broad categories - parameters and declarations. | |
35 | .PP | |
36 | Parameter statements either say how to do something (e.g., how long a | |
37 | lease to offer), whether to do something (e.g., should dhcpd provide | |
38 | addresses to unknown clients), or what parameters to provide to the | |
39 | client (e.g., use gateway 220.177.244.7). | |
40 | .PP | |
41 | Declarations are used to describe the topology of the | |
42 | network, to describe clients on the network, to provide addresses that | |
43 | can be assigned to clients, or to apply a group of parameters to a | |
44 | group of declarations. In any group of parameters and declarations, | |
45 | all parameters must be specified before any declarations which depend | |
46 | on those parameters may be specified. | |
47 | .PP | |
48 | Declarations about network topology include the | |
612bc350 | 49 | \fIshared-network\fR and the \fIsubnet\fR |
5e6b52dc TL |
50 | declarations. If clients on a subnet are to be assigned addresses |
51 | dynamically, a \fIrange\fR declaration must appear within the | |
52 | \fIsubnet\fR declaration. For clients with statically assigned | |
53 | addresses, or for installations where only known clients will be | |
54 | served, each such client must have a \fIhost\fR declaration. If | |
55 | parameters are to be applied to a group of declarations which are not | |
56 | related strictly on a per-subnet basis, the \fIgroup\fR declaration | |
57 | can be used. | |
58 | .PP | |
612bc350 | 59 | For every subnet which will be served, and for every subnet |
73eaf823 TL |
60 | to which the dhcp server is connected, there must be one \fIsubnet\fR |
61 | declaration, which tells dhcpd how to recognize that an address is on | |
62 | that subnet. A \fIsubnet\fR declaration is required for each subnet | |
63 | even if no addresses will be dynamically allocated on that subnet. | |
5e6b52dc TL |
64 | .PP |
65 | Some installations have physical networks on which more than one IP | |
66 | subnet operates. For example, if there is a site-wide requirement | |
67 | that 8-bit subnet masks be used, but a department with a single | |
68 | physical ethernet network expands to the point where it has more than | |
69 | 254 nodes, it may be necessary to run two 8-bit subnets on the same | |
70 | ethernet until such time as a new physical network can be added. In | |
b8f73859 | 71 | this case, the \fIsubnet\fR declarations for these two networks must be |
5e6b52dc TL |
72 | enclosed in a \fIshared-network\fR declaration. |
73 | .PP | |
74 | Some sites may have departments which have clients on more than one | |
75 | subnet, but it may be desirable to offer those clients a uniform set | |
76 | of parameters which are different than what would be offered to | |
77 | clients from other departments on the same subnet. For clients which | |
78 | will be declared explicitly with \fIhost\fR declarations, these | |
79 | declarations can be enclosed in a \fIgroup\fR declaration along with | |
80 | the parameters which are common to that department. For clients | |
49f6028f TL |
81 | whose addresses will be dynamically assigned, class declarations and |
82 | conditional declarations may be used to group parameter assignments | |
83 | based on information the client sends. | |
5e6b52dc TL |
84 | .PP |
85 | When a client is to be booted, its boot parameters are determined by | |
49f6028f TL |
86 | consulting that client's \fIhost\fR declaration (if any), and then |
87 | consulting the any \fIclass\fR declarations matching the client, | |
88 | followed by the \fIpool\fR, \fIsubnet\fR and \fIshared-network\fR | |
89 | declarations for the IP address assigned to the client. Each of | |
90 | these declarations itself appears within a lexical scope, and all | |
91 | declarations at less specific lexical scopes are also consulted for | |
92 | client option declarations as well. Scopes are never considered | |
93 | twice, and if parameters are declared in more than one scope, the | |
94 | parameter declared in the most specific scope is the one that is | |
95 | used. | |
5e6b52dc TL |
96 | .PP |
97 | When dhcpd tries to find a \fIhost\fR declaration for a client, it | |
98 | first looks for a \fIhost\fR declaration which has a | |
99 | \fIfixed-address\fR parameter which matches the subnet or shared | |
100 | network on which the client is booting. If it doesn't find any such | |
101 | entry, it then tries to find an entry which has no \fIfixed-address\fR | |
e6e1cb3d | 102 | parameter. |
5e6b52dc TL |
103 | .SH EXAMPLES |
104 | .PP | |
105 | A typical dhcpd.conf file will look something like this: | |
106 | .nf | |
107 | ||
5e6b52dc TL |
108 | .I global parameters... |
109 | ||
d9dc2726 TL |
110 | subnet 204.254.239.0 netmask 255.255.255.224 { |
111 | \fIsubnet-specific parameters...\fR | |
112 | range 204.254.239.10 204.254.239.30; | |
113 | } | |
114 | ||
115 | subnet 204.254.239.32 netmask 255.255.255.224 { | |
116 | \fIsubnet-specific parameters...\fR | |
117 | range 204.254.239.42 204.254.239.62; | |
5e6b52dc TL |
118 | } |
119 | ||
120 | subnet 204.254.239.64 netmask 255.255.255.224 { | |
121 | \fIsubnet-specific parameters...\fR | |
122 | range 204.254.239.74 204.254.239.94; | |
123 | } | |
124 | ||
125 | group { | |
126 | \fIgroup-specific parameters...\fR | |
127 | host zappo.test.isc.org { | |
128 | \fIhost-specific parameters...\fR | |
129 | } | |
130 | host beppo.test.isc.org { | |
131 | \fIhost-specific parameters...\fR | |
132 | } | |
133 | host harpo.test.isc.org { | |
134 | \fIhost-specific parameters...\fR | |
135 | } | |
136 | } | |
137 | ||
138 | .ce 1 | |
139 | Figure 1 | |
140 | ||
141 | .fi | |
d250c5b9 | 142 | .PP |
612bc350 | 143 | Notice that at the beginning of the file, there's a place |
5e6b52dc TL |
144 | for global parameters. These might be things like the organization's |
145 | domain name, the addresses of the name servers (if they are common to | |
146 | the entire organization), and so on. So, for example: | |
147 | .nf | |
148 | ||
149 | option domain-name "isc.org"; | |
ee31d992 | 150 | option domain-name-servers ns1.isc.org, ns2.isc.org; |
5e6b52dc TL |
151 | |
152 | .ce 1 | |
153 | Figure 2 | |
154 | .fi | |
d250c5b9 | 155 | .PP |
d9dc2726 TL |
156 | As you can see in Figure 2, you can specify host addresses in |
157 | parameters using their domain names rather than their numeric IP | |
158 | addresses. If a given hostname resolves to more than one IP address | |
159 | (for example, if that host has two ethernet interfaces), then where | |
160 | possible, both addresses are supplied to the client. | |
47c9ea95 | 161 | .PP |
5e6b52dc TL |
162 | The most obvious reason for having subnet-specific parameters as |
163 | shown in Figure 1 is that each subnet, of necessity, has its own | |
164 | router. So for the first subnet, for example, there should be | |
165 | something like: | |
166 | .nf | |
167 | ||
168 | option routers 204.254.239.1; | |
169 | .fi | |
d250c5b9 | 170 | .PP |
5e6b52dc TL |
171 | Note that the address here is specified numerically. This is not |
172 | required - if you have a different domain name for each interface on | |
173 | your router, it's perfectly legitimate to use the domain name for that | |
174 | interface instead of the numeric address. However, in many cases | |
175 | there may be only one domain name for all of a router's IP addresses, and | |
176 | it would not be appropriate to use that name here. | |
177 | .PP | |
178 | In Figure 1 there is also a \fIgroup\fR statement, which provides | |
179 | common parameters for a set of three hosts - zappo, beppo and harpo. | |
180 | As you can see, these hosts are all in the test.isc.org domain, so it | |
181 | might make sense for a group-specific parameter to override the domain | |
182 | name supplied to these hosts: | |
183 | .nf | |
184 | ||
185 | option domain-name "test.isc.org"; | |
186 | .fi | |
187 | .PP | |
188 | Also, given the domain they're in, these are probably test machines. | |
189 | If we wanted to test the DHCP leasing mechanism, we might set the | |
190 | lease timeout somewhat shorter than the default: | |
191 | ||
192 | .nf | |
193 | max-lease-time 120; | |
194 | default-lease-time 120; | |
195 | .fi | |
d250c5b9 | 196 | .PP |
5e6b52dc TL |
197 | You may have noticed that while some parameters start with the |
198 | \fIoption\fR keyword, some do not. Parameters starting with the | |
199 | \fIoption\fR keyword correspond to actual DHCP options, while | |
200 | parameters that do not start with the option keyword either control | |
201 | the behaviour of the DHCP server (e.g., how long a lease dhcpd will | |
202 | give out), or specify client parameters that are not optional in the | |
203 | DHCP protocol (for example, server-name and filename). | |
204 | .PP | |
205 | In Figure 1, each host had \fIhost-specific parameters\fR. These | |
206 | could include such things as the \fIhostname\fR option, the name of a | |
207 | file to upload (the \fIfilename parameter) and the address of the | |
208 | server from which to upload the file (the \fInext-server\fR | |
209 | parameter). In general, any parameter can appear anywhere that | |
210 | parameters are allowed, and will be applied according to the scope in | |
211 | which the parameter appears. | |
212 | .PP | |
213 | Imagine that you have a site with a lot of NCD X-Terminals. These | |
214 | terminals come in a variety of models, and you want to specify the | |
215 | boot files for each models. One way to do this would be to have host | |
216 | declarations for each server and group them by model: | |
217 | .nf | |
218 | ||
219 | group { | |
220 | filename "Xncd19r"; | |
221 | next-server ncd-booter; | |
222 | ||
223 | host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; } | |
224 | host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; } | |
225 | host ncd8 { hardware ethernet 0:c0:c3:22:46:81; } | |
226 | } | |
227 | ||
228 | group { | |
229 | filename "Xncd19c"; | |
230 | next-server ncd-booter; | |
231 | ||
232 | host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; } | |
233 | host ncd3 { hardware ethernet 0:c0:c3:00:14:11; } | |
234 | } | |
235 | ||
236 | group { | |
237 | filename "XncdHMX"; | |
238 | next-server ncd-booter; | |
239 | ||
240 | host ncd1 { hardware ethernet 0:c0:c3:11:90:23; } | |
241 | host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; } | |
242 | host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; } | |
243 | } | |
244 | .fi | |
d9dc2726 TL |
245 | .SH ADDRESS POOLS |
246 | .PP | |
247 | The | |
248 | .B pool | |
249 | declaration can be used to specify a pool of addresses that will be | |
250 | treated differently than another pool of addresses, even on the same | |
251 | network segment or subnet. For example, you may want to provide a | |
252 | large set of addresses that can be assigned to DHCP clients that are | |
253 | registered to your DHCP server, while providing a smaller set of | |
254 | addresses, possibly with short lease times, that are available for | |
255 | unknown clients. If you have a firewall, you may be able to arrange | |
256 | for addresses from one pool to be allowed access to the Internet, | |
257 | while addresses in another pool are not, thus encouraging users to | |
258 | register their DHCP clients. To do this, you would set up a pair of | |
259 | pool declarations: | |
260 | .PP | |
261 | .nf | |
262 | subnet 10.0.0.0 netmask 255.255.255.0 { | |
263 | option routers 10.0.0.254; | |
264 | ||
265 | # Unknown clients get this pool. | |
266 | pool { | |
267 | option domain-name-servers bogus.example.com; | |
268 | max-lease-time 300; | |
269 | range 10.0.0.200 10.0.0.253; | |
270 | allow unknown clients; | |
271 | } | |
272 | ||
273 | # Known clients get this pool. | |
274 | pool { | |
275 | option domain-name-servers ns1.example.com, ns2.example.com; | |
276 | max-lease-time 28800; | |
277 | range 10.0.0.5 10.0.0.199; | |
278 | deny unknown clients; | |
279 | } | |
280 | } | |
281 | .fi | |
282 | .PP | |
283 | It is also possible to set up entirely different subnets for known and | |
284 | unknown clients - address pools exist at the level of shared networks, | |
285 | so address ranges within pool declarations can be on different | |
286 | subnets. | |
1a67a4d7 TL |
287 | .PP |
288 | As you can see in the preceding example, pools can have permit lists | |
289 | that control which clients are allowed access to the pool and which | |
290 | aren't. Each entry in a pool's permit list is introduced with the | |
291 | .I allow | |
292 | or \fIdeny\fR keyword. If a pool has a permit list, then only those | |
293 | clients that match specific entries on the permit list will be | |
294 | elegible to be assigned addresses from the pool. If a pool has a | |
295 | deny list, then only those clients that do not match any entries on | |
296 | the deny list will be elegible. If both permit and deny lists exist | |
297 | for a pool, then only clients that match the permit list and do not | |
298 | match the deny list will be allowed access. | |
299 | .SH ADDRESS ALLOCATION | |
300 | Address allocation is actually only done when a client is in the INIT | |
301 | state and has sent a DHCPDISCOVER message. If the client thinks it | |
302 | has a valid lease and sends a DHCPREQUEST to initiate or renew that | |
303 | lease, the server has only three choices - it can ignore the | |
304 | DHCPREQUEST, send a DHCPNAK to tell the client it should stop using | |
305 | the address, or send a DHCPACK, telling the client to go ahead and use | |
306 | the address for a while. If the server finds the address the client | |
307 | is requesting, and that address is available to the client, the server | |
308 | will send a DHCPACK. If the address is no longer available, or the | |
309 | client isn't permitted to have it, the server will send a DHCPNAK. If | |
310 | the server knows nothing about the, it will remain silent, unless the | |
311 | address is incorrect for the network segment to which the client has | |
312 | been attached and the server is authoritative for that network | |
313 | segment, in which case the server will send a DHCPNAK even though it | |
314 | doesn't know about the address. | |
315 | .PP | |
316 | When the DHCP server allocates a new address for a client (remember, | |
317 | this only happens if the client has sent a DHCPDISCOVER), it first | |
318 | looks to see if the client already has a valid lease on an IP address, | |
319 | or if there is an old IP address the client had before that hasn't yet | |
320 | been reassigned. In that case, the server will take that address and | |
321 | check it to see if the client is still permitted to use it. If the | |
322 | client is no longer permitted to use it, the lease is freed if the | |
323 | server thought it was still in use - the fact that the client has sent | |
324 | a DHCPDISCOVER proves to the server that the client is no longer using | |
325 | the lease. | |
326 | .PP | |
327 | If no existing lease is found, or if the client is forbidden to | |
328 | receive the existing lease, then the server will look in the list of | |
329 | address pools for the network segment to which the client is attached | |
330 | for a lease that is not in use and that the client is permitted to | |
331 | have. It looks through each pool declaration in sequence (all | |
332 | .I range | |
333 | declarations that appear outside of pool declarations are grouped into | |
334 | a single pool with no permit list). If the permit list for the pool | |
335 | allows the client to be allocated an address from that pool, the pool | |
336 | is examined to see if there is an address available. If so, then the | |
337 | client is tentatively assigned that address. Otherwise, the next | |
338 | pool is tested. If no addresses are found that can be assigned to | |
339 | the client, no response is sent to the client. | |
340 | .PP | |
341 | If an address is found that the client is permitted to have, and that | |
342 | has never been assigned to any client before, the address is | |
343 | immediately allocated to the client. If the address is available for | |
344 | allocation but has been previously assigned to a different client, the | |
345 | server will keep looking in hopes of finding an address that has never | |
346 | before been assigned to a client. | |
a25a18d7 TL |
347 | .PP |
348 | The DHCP server checks IP addresses to see if they are in use before | |
349 | allocating them to clients. It does this by sending an ICMP Echo | |
350 | request message to the IP address being allocated. If no ICMP Echo | |
351 | reply is received within a second, the address is assumed to be free. | |
352 | This is only done for leases that have been specified in range | |
353 | statements, and only when the lease is thought by the DHCP server to | |
354 | be free - i.e., the DHCP server or its failover peer has not listed | |
355 | the lease as in use. | |
356 | .PP | |
357 | If a response is received to an ICMP Echo request, the DHCP server | |
358 | assumes that there is a configuration error - the IP address is in use | |
359 | by some host on the network that is not a DHCP client. It marks the | |
360 | address as abandoned, and will not assign it to clients. | |
361 | .PP | |
362 | If a DHCP client tries to get an IP address, but none are available, | |
363 | but there are abandoned IP addresses, then the DHCP server will | |
364 | attempt to reclaim an abandoned IP address. It marks one IP address | |
365 | as free, and then does the same ICMP Echo request check described | |
366 | previously. If there is no answer to the ICMP Echo request, the | |
367 | address is assigned to the client. | |
368 | .PP | |
369 | The DHCP server does not cycle through abandoned IP addresses if the | |
370 | first IP address it tries to reclaim is free. Rather, when the next | |
371 | DHCPDISCOVER comes in from the client, it will attempt a new | |
372 | allocation using the same method described here, and will typically | |
373 | try a new IP address. | |
59d36179 TL |
374 | .SH DHCP FAILOVER |
375 | This version of the ISC DHCP server supports the DHCP failover | |
376 | protocol as documented in draft-ietf-dhc-failover-07.txt. This is | |
377 | not a final protocol document, and we have not done interoperability | |
378 | testing with other vendors' implementations of this protocol, so you | |
379 | must not assume that this implementation conforms to the standard. | |
380 | If you wish to use the failover protocol, make sure that both failover | |
381 | peers are running the same version of the ISC DHCP server. | |
382 | .PP | |
383 | The failover protocol allows two DHCP servers (and no more than two) | |
384 | to share a common address pool. Each server will have about half of | |
385 | the available IP addresses in the pool at any given time for | |
386 | allocation. If one server fails, the other server will continue to | |
387 | renew leases out of the pool, and will allocate new addresses out of | |
388 | the roughly half of available addresses that it had when | |
389 | communications with the other server were lost. | |
390 | .PP | |
391 | It is possible during a prolonged failure to tell the remaining server | |
392 | that the other server is down, in which case the remaining server will | |
393 | (over time) reclaim all the addresses the other server had available | |
394 | for allocation, and begin to reuse them. This is called putting the | |
395 | server into the PARTNER-DOWN state. | |
396 | .PP | |
397 | When the other server comes back online, it should automatically | |
398 | detect that it has been offline and request a complete update from the | |
399 | server that was running in the PARTNER-DOWN state, and then both | |
400 | servers will resume processing together. | |
401 | .PP | |
402 | It is possible to get into a dangerous situation: if you put one | |
403 | server into the PARTNER-DOWN state, and then *that* server goes down, | |
404 | and the other server comes back up, the other server will not know | |
405 | that the first server was in the PARTNER-DOWN state, and may issue | |
406 | addresses previously issued by the other server to different clients, | |
407 | resulting in IP address conflicts. Before putting a server into | |
408 | PARTNER-DOWN state, therefore, make | |
409 | .I sure | |
410 | that the other server will not restart automatically. | |
411 | .PP | |
412 | The failover protocol defines a primary server role and a secondary | |
413 | server role. There are some differences in how primaries and | |
414 | secondaries act, but most of the differences simply have to do with | |
415 | providing a way for each peer to behave in the opposite way from the | |
416 | other. So one server must be configured as primary, and the other | |
417 | must be configured as secondary, and it doesn't matter too much which | |
418 | one is which. | |
419 | .SH CONFIGURING FAILOVER | |
420 | In order to configure failover, you need to write a peer declaration | |
421 | that configures the failover protocol, and you need to write peer | |
422 | references in each pool declaration for which you want to do | |
423 | failover. You do not have to do failover for all pools on a given | |
424 | network segment. You must not tell one server it's doing failover | |
425 | on a particular address pool and tell the other it is not. You must | |
426 | not have any common address pools on which you are not doing | |
427 | failover. | |
428 | .PP | |
429 | The server currently does very little sanity checking, so if you | |
430 | configure it wrong, it will just fail in odd ways. I would recommend | |
431 | therefore that you either do failover or don't do failover, but don't | |
432 | do any mixed pools. Also, use the same master configuration file for | |
433 | both servers, and have a seperate file that contains the peer | |
434 | declaration and includes the master file. This will help you to avoid | |
435 | configuration mismatches. As our implementation evolves, this will | |
436 | become less of a problem. A basic sample dhcpd.conf file for a | |
437 | primary server might look like this: | |
438 | .PP | |
439 | .nf | |
440 | failover peer "foo" { | |
441 | primary; | |
442 | address anthrax.rc.vix.com; | |
443 | port 519; | |
444 | peer address trantor.rc.vix.com; | |
445 | peer port 520; | |
446 | max-response-delay 60; | |
447 | max-unacked-updates 10; | |
448 | mclt 3600; | |
449 | hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff: | |
450 | 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00; | |
451 | load balance max seconds 3; | |
452 | } | |
453 | ||
454 | include "/etc/dhcpd.master"; | |
455 | .fi | |
456 | .PP | |
457 | The statements in the peer declaration are as follows: | |
458 | .PP | |
459 | .B The | |
460 | .I primary | |
461 | .B and | |
462 | .I secondary | |
463 | .B statements | |
464 | .PP | |
465 | [ \fBprimary\fR | \fBsecondary\fR ] | |
466 | .PP | |
467 | This determines whether the server is primary or secondary, as | |
468 | described earlier under DHCP FAILOVER. | |
469 | .PP | |
470 | .B The | |
471 | .I address | |
472 | .B statement | |
473 | .PP | |
474 | .B address | |
475 | .I address | |
476 | .PP | |
f07d12c6 TL |
477 | The \fBaddress\fR statement declares the IP address on which the |
478 | server should listen for connections from its failover peer, and also | |
479 | the value to use for the DHCP Failover Protocol server identifier. | |
480 | Because this value is used as an identifier, it may not be omitted. | |
59d36179 TL |
481 | .PP |
482 | .B The | |
483 | .I peer address | |
484 | .B statement | |
485 | .PP | |
486 | .B peer address | |
487 | .I address | |
488 | .PP | |
489 | The \fBpeer address\fR statement declares the IP address to which the | |
490 | server should connect to reach its failover peer for failover | |
491 | messages. | |
492 | .PP | |
493 | .B The | |
494 | .I port | |
495 | .B statement | |
496 | .PP | |
497 | .B port | |
498 | .I port-number | |
499 | .PP | |
500 | The \fBport\fR statement declares the TCP port on which the server | |
501 | should listen for connections from its failover peer. This statement | |
502 | may not currently be omitted, because the failover protocol does not | |
503 | yet have a reserved TCP port number. | |
504 | .PP | |
505 | .B The | |
506 | .I peer port | |
507 | .B statement | |
508 | .PP | |
509 | .B peer port | |
510 | .I port-number | |
511 | .PP | |
512 | The \fBpeer port\fR statement declares the TCP port to which the | |
513 | server should connect to reach its failover peer for failover | |
514 | messages. This statement may not be omitted because the failover | |
515 | protocol does not yet have a reserved TCP port number. The port | |
516 | number declared in the \fBpeer port\fR statement may be the same as | |
517 | the port number declared in the \fBport\fR statement. | |
518 | .PP | |
519 | .B The | |
520 | .I max-response-delay | |
521 | .B statement | |
522 | .PP | |
523 | .nf | |
524 | .B max-response-delay | |
525 | .I seconds | |
526 | .fi | |
527 | .PP | |
528 | The \fBmax-response-delay\fR statement tells the DHCP server how | |
529 | many seconds may pass without receiving a message from its failover | |
530 | peer before it assumes that connection has failed. This number | |
531 | should be small enough that a transient network failure that breaks | |
532 | the connection will not result in the servers being out of | |
533 | communication for a long time, but large enough that the server isn't | |
534 | constantly making and breaking connections. This parameter must be | |
535 | specified. | |
536 | .PP | |
537 | .B The | |
538 | .I max-unacked-updates | |
539 | .B statement | |
540 | .PP | |
541 | .B max-unacked-updates | |
542 | .I count | |
543 | .PP | |
544 | The \fBmax-unacked-updates\fR statement tells the DHCP server how | |
545 | many many BINDUPD messages it can send before it receives a BNDACK | |
546 | from the failover peer. We don't have enough operational experience | |
547 | to say what a good value for this is, but 10 seems to work. This | |
548 | parameter must be specified. | |
549 | .PP | |
550 | .B The | |
551 | .I mclt | |
552 | .B statement | |
553 | .PP | |
554 | .B mclt | |
555 | .I seconds | |
556 | .PP | |
557 | The \fBmclt\fR statement defines the Maximum Client Lead Time. It | |
558 | must be specified on the primary, and may not be specified on the | |
559 | secondary. This is the length of time for which a lease may be | |
560 | renewed by either failover peer without contacting the other. The | |
561 | longer you set this, the longer it will take for the running server to | |
562 | recover IP addresses after moving into PARTNER-DOWN state. The | |
563 | shorter you set it, the more load your servers will experience when | |
564 | they are not communicating. A value of something like 3600 is | |
565 | probably reasonable, but again bear in mind that we have no real | |
566 | operational experience with this. | |
567 | .PP | |
568 | .B The | |
569 | .I split | |
570 | .B statement | |
571 | .PP | |
572 | .B split | |
573 | .I index | |
574 | .PP | |
575 | The split statement specifies the split between the primary and | |
576 | secondary for the purposes of load balancing. Whenever a client | |
577 | makes a DHCP request, the DHCP server runs a hash on the client | |
578 | identification. If the hash comes out to less than the split value, | |
579 | the primary answers. If it comes out to equal to or more than the | |
580 | split, the secondary answers. This value should generally be set to | |
581 | 128, and can only be configured on the primary. | |
582 | .PP | |
583 | .B The | |
584 | .I hba | |
585 | .B statement | |
586 | .PP | |
587 | .B hba | |
588 | .I colon-seperated-hex-list | |
589 | .PP | |
590 | The hba statement specifies the split between the primary and | |
591 | secondary as a bitmap rather than a cutoff, which theoretically allows | |
592 | for finer-grained control. In practice, there is probably no need | |
593 | for such fine-grained control, however. An example hba statement: | |
594 | .PP | |
595 | .nf | |
596 | hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff: | |
597 | 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00; | |
598 | .fi | |
599 | .PP | |
600 | .B The | |
601 | .I load balance max seconds | |
602 | .B statement | |
603 | .PP | |
604 | .B load balance max seconds | |
605 | .I seconds | |
606 | .PP | |
607 | This statement allows you to configure a cutoff after which load | |
608 | balancing is disabled. The cutoff is based on the number of seconds | |
609 | since the client sent its first DHCPDISCOVER or DHCPREQUEST message, | |
610 | and only works with clients that correctly implement the \fIsecs\fR | |
611 | field - fortunately most clients do. We recommend setting this to | |
612 | something like 3 or 5. The effect of this is that if one of the | |
613 | failover peers gets into a state where it is responding to failover | |
614 | messages but not responding to some client requests, the other | |
615 | failover peer will take over its client load automatically as the | |
616 | clients retry. | |
d9dc2726 TL |
617 | .SH CLIENT CLASSING |
618 | Clients can be seperated into classes, and treated differently | |
619 | depending on what class they are in. This seperation can be done | |
620 | either with a conditional statement, or with a match statement within | |
621 | the class declaration. It is possible to specify a limit on the | |
622 | total number of clients within a particular class or subclass that may | |
623 | hold leases at one time, and it is possible to specify automatic | |
624 | subclassing based on the contents of the client packet. | |
625 | .PP | |
626 | To add clients to classes based on conditional evaluation, you would | |
627 | write an conditional statement to match the clients you wanted in the | |
628 | class, and then put an | |
629 | .B add | |
630 | statement in the conditional's list of statements: | |
631 | .PP | |
632 | .nf | |
c8ba1c79 | 633 | if substring (option dhcp-client-identifier, 1, 4) = "RAS " { |
e9bb983c | 634 | add "ras-clients"; |
d9dc2726 TL |
635 | } |
636 | .fi | |
637 | .PP | |
e9bb983c | 638 | A nearly equivalent way to do this is to simply specify the conditional |
d9dc2726 TL |
639 | expression as a matching expression in the class statement: |
640 | .PP | |
641 | .nf | |
e9bb983c | 642 | class "ras-clients" { |
c8ba1c79 | 643 | match if substring (option dhcp-client-identifier, 1, 4) = "RAS"; |
d9dc2726 TL |
644 | } |
645 | .fi | |
e9bb983c TL |
646 | Note that whether you use matching expressions or add statements (or |
647 | both) to classify clients, you must always write a class declaration | |
648 | for any class that you use. If there will be no match statement and | |
649 | no in-scope statements for a class, the declaration should look like | |
650 | this: | |
651 | .nf | |
652 | class "ras-clients" { | |
653 | } | |
654 | .fi | |
655 | .PP | |
656 | Also, the | |
657 | .B add | |
658 | statement adds the client to the class as the client's scopes are being | |
659 | evaluated - after any address assignment decision has been made. This means | |
660 | that a client that's a member of a class due to an add statement will not | |
661 | be affected by pool permits related to that class - when the pool permit list | |
662 | is computed, the client will not yet be a member of the pool. This is an | |
663 | inconsistency that will probably be addressed in later versions of the DHCP | |
664 | server, but it important to be aware of it at lease for the time being. | |
2cd60a52 | 665 | .SH SUBCLASSES |
d9dc2726 TL |
666 | .PP |
667 | In addition to classes, it is possible to declare subclasses. A | |
668 | subclass is a class with the same name as a regular class, but with a | |
669 | specific submatch expression which is hashed for quick matching. | |
670 | This is essentially a speed hack - the main difference between five | |
671 | classes with match expressions and one class with five subclasses is | |
672 | that it will be quicker to find the subclasses. Subclasses work as | |
673 | follows: | |
674 | .PP | |
675 | .nf | |
2cd60a52 TL |
676 | class "allocation-class-1" { |
677 | match pick-first-value (option dhcp-client-identifier, hardware); | |
d9dc2726 TL |
678 | } |
679 | ||
2cd60a52 TL |
680 | class "allocation-class-2" { |
681 | match pick-first-value (option dhcp-client-identifier, hardware); | |
d9dc2726 TL |
682 | } |
683 | ||
2cd60a52 TL |
684 | subclass "allocation-class-1" 1:8:0:2b:4c:39:ad; |
685 | subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3; | |
686 | subclass "allocation-class-1" 1:0:0:c4:aa:29:44; | |
687 | ||
688 | subnet 10.0.0.0 netmask 255.255.255.0 { | |
689 | pool { | |
7b9767ea | 690 | allow members of "allocation-class-1"; |
2cd60a52 TL |
691 | range 10.0.0.11 10.0.0.50; |
692 | } | |
693 | pool { | |
7b9767ea | 694 | allow members of "allocation-class-2"; |
2cd60a52 TL |
695 | range 10.0.0.51 10.0.0.100; |
696 | } | |
697 | } | |
698 | .fi | |
699 | .PP | |
700 | The data following the class name in the subclass declaration is a | |
701 | constant value to use in matching the match expression for the class. | |
702 | When class matching is done, the server will evaluate the match | |
703 | expression and then look the result up in the hash table. If it | |
704 | finds a match, the client is considered a member of both the class and | |
705 | the subclass. | |
706 | .PP | |
707 | Subclasses can be declared with or without scope. In the above | |
708 | example, the sole purpose of the subclass is to allow some clients | |
709 | access to one address pool, while other clients are given access to | |
710 | the other pool, so these subclasses are declared without scopes. If | |
711 | part of the purpose of the subclass were to define different parameter | |
712 | values for some clients, you might want to declare some subclasses | |
713 | with scopes. | |
714 | .PP | |
715 | In the above example, if you had a single client that needed some | |
716 | configuration parameters, while most didn't, you might write the | |
717 | following subclass declaration for that client: | |
718 | .PP | |
719 | .nf | |
605a8b6d | 720 | subclass "allocation-class-2" 1:08:00:2b:a1:11:31 { |
2cd60a52 TL |
721 | option root-path "samsara:/var/diskless/alphapc"; |
722 | filename "/tftpboot/netbsd.alphapc-diskless"; | |
d9dc2726 TL |
723 | } |
724 | .fi | |
725 | .PP | |
2cd60a52 TL |
726 | In this example, we've used subclassing as a way to control address |
727 | allocation on a per-client basis. However, it's also possible to use | |
728 | subclassing in ways that are not specific to clients - for example, to | |
729 | use the value of the vendor-class-identifier option to determine what | |
730 | values to send in the vendor-encapsulated-options option. An example | |
731 | of this is shown under the VENDOR ENCAPSULATED OPTIONS head later on | |
732 | in this document. | |
66ecafef | 733 | .SH PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION |
d9dc2726 TL |
734 | .PP |
735 | You may specify a limit to the number of clients in a class that can | |
736 | be assigned leases. The effect of this will be to make it difficult | |
737 | for a new client in a class to get an address. Once a class with | |
738 | such a limit has reached its limit, the only way a new client in that | |
739 | class can get a lease is for an existing client to relinquish its | |
740 | lease, either by letting it expire, or by sending a DHCPRELEASE | |
741 | packet. Classes with lease limits are specified as follows: | |
742 | .PP | |
743 | .nf | |
e9bb983c | 744 | class "limited-1" { |
d9dc2726 TL |
745 | lease limit 4; |
746 | } | |
747 | .fi | |
748 | .PP | |
749 | This will produce a class in which a maximum of four members may hold | |
750 | a lease at one time. | |
2cd60a52 | 751 | .SH SPAWNING CLASSES |
d9dc2726 TL |
752 | .PP |
753 | It is possible to declare a | |
754 | .I spawning class\fR. | |
755 | A spawning class is a class that automatically produces subclasses | |
756 | based on what the client sends. The reason that spawning classes | |
757 | were created was to make it possible to create lease-limited classes | |
758 | on the fly. The envisioned application is a cable-modem environment | |
759 | where the ISP wishes to provide clients at a particular site with more | |
760 | than one IP address, but does not wish to provide such clients with | |
761 | their own subnet, nor give them an unlimited number of IP addresses | |
762 | from the network segment to which they are connected. | |
763 | .PP | |
764 | Many cable modem head-end systems can be configured to add a Relay | |
765 | Agent Information option to DHCP packets when relaying them to the | |
766 | DHCP server. These systems typically add a circuit ID or remote ID | |
767 | option that uniquely identifies the customer site. To take advantage | |
768 | of this, you can write a class declaration as follows: | |
2cd60a52 | 769 | .PP |
d9dc2726 | 770 | .nf |
e9bb983c | 771 | class "customer" { |
b1c231ba | 772 | spawn with option agent.circuit-id; |
d9dc2726 TL |
773 | lease limit 4; |
774 | } | |
775 | .fi | |
776 | .PP | |
777 | Now whenever a request comes in from a customer site, the circuit ID | |
778 | option will be checked against the class's hash table. If a subclass | |
779 | is found that matches the circuit ID, the client will be classified in | |
780 | that subclass and treated accordingly. If no subclass is found | |
781 | matching the circuit ID, a new one will be created and logged in the | |
782 | .B dhcpd.leases | |
783 | file, and the client will be classified in this new class. Once the | |
784 | client has been classified, it will be treated according to the rules | |
785 | of the class, including, in this case, being subject to the per-site | |
786 | limit of four leases. | |
787 | .PP | |
788 | The use of the subclass spawning mechanism is not restricted to relay | |
789 | agent options - this particular example is given only because it is a | |
790 | fairly straightforward one. | |
874031aa TL |
791 | .SH COMBINING MATCH, MATCH IF AND SPAWN WITH |
792 | .PP | |
793 | In some cases, it may be useful to use one expression to assign a | |
794 | client to a particular class, and a second expression to put it into a | |
795 | subclass of that class. This can be done by combining the \fBmatch | |
796 | if\fR and \fBspawn with\fR statements, or the \fBmatch if\fR and | |
797 | \fBmatch\fR statements. For example: | |
798 | .PP | |
799 | .nf | |
800 | class "jr-cable-modems" { | |
801 | match if option dhcp-vendor-identifier = "jrcm"; | |
802 | spawn with option agent.circuit-id; | |
803 | lease limit 4; | |
804 | } | |
805 | ||
806 | class "dv-dsl-modems" { | |
807 | match if opton dhcp-vendor-identifier = "dvdsl"; | |
808 | spawn with option agent.circuit-id; | |
809 | lease limit 16; | |
810 | } | |
811 | .fi | |
812 | .PP | |
813 | This allows you to have two classes that both have the same \fBspawn | |
814 | with\fR expression without getting the clients in the two classes | |
815 | confused with each other. | |
66ecafef TL |
816 | .SH DYNAMIC DNS UPDATES |
817 | .PP | |
818 | The DHCP server has the ability to dynamically update the Domain Name | |
819 | System. Within the configuration files, you can define how you want | |
820 | the Domain Name System to be updated. These updates are RFC 2136 | |
821 | compliant so any DNS server supporting RFC 2136 should be able to | |
59d36179 | 822 | accept updates from the DHCP server. |
66ecafef TL |
823 | .PP |
824 | The Dynamic DNS update scheme implemented in this version of the ISC | |
825 | DHCP server is an interim implementation, which does not implement any | |
826 | of the standard update methods that have been discussed in the working | |
827 | group, but rather implements some very basic, yet useful, update | |
828 | capabilities. | |
829 | .PP | |
830 | There are three parameters, which may vary according to the scope, | |
831 | that control how DDNS updates will be done. The first two are the | |
832 | .I ddns-domainname | |
833 | and | |
834 | .I ddns-rev-domainname | |
835 | statements. The | |
836 | .I ddns-domainname | |
837 | parameter sets the domain name that will be appended to the client's | |
838 | hostname to form a fully-qualified domain-name (FQDN). For example, | |
839 | if the client's hostname is "hutson" and the | |
840 | .I ddns-domainname | |
841 | is set to "sneedville.edu", then the client's FQDN will be | |
842 | "hutson.sneedville.edu". | |
843 | .PP | |
844 | The | |
845 | .I ddns-rev-domainname | |
846 | parameter sets the domain name that will be appended to the client's | |
847 | reversed IP address to produce a name for use in the client's PTR | |
848 | record. Normally, you would set this to "in-addr.arpa", but this is | |
849 | not required. | |
850 | .PP | |
851 | A third parameter, | |
852 | .I ddns-hostname | |
853 | can be used to specify the hostname that will be used as the client's | |
854 | hostname. If no ddns-hostname is specified in scope, then the server | |
855 | will use a host-name option sent by the client. If the client did | |
856 | not send a host-name option, then if there is a host declaration that | |
857 | applies to the client, the name from that declaration will be used. | |
858 | If none of these applies, the server will not have a hostname for the | |
859 | client, and will not be able to do a DDNS update. | |
860 | .SH HOW DNS UPDATES WORK | |
861 | .PP | |
862 | The client's FQDN, derived as we have described, is used as the name | |
863 | on which an "A" record will be stored. The A record will contain the | |
864 | IP address that the client was assigned in its lease. If there is | |
865 | already an A record with the same name in the DNS server, no update of | |
866 | either the A or PTR records will occur - this prevents a client from | |
867 | claiming that its hostname is the name of some network server. For | |
868 | example, if you have a fileserver called "fs.sneedville.edu", and the | |
869 | client claims its hostname is "fs", no DNS update will be done for | |
870 | that client, and an error message will be logged. | |
871 | .PP | |
872 | If the A record update succeeds, a PTR record update for the assigned | |
873 | IP address will be done, pointing to the A record. This update is | |
874 | unconditional - it will be done even if another PTR record of the same | |
875 | name exists. Since the IP address has been assigned to the DHCP | |
876 | server, this should be safe. | |
877 | .PP | |
878 | Please note that the current implementation assumes clients only have | |
879 | a single network interface. A client with two network interfaces | |
880 | will see unpredictable behaviour. This is considered a bug, and will | |
881 | be fixed in a later release. It may be helpful to enable the | |
882 | .I one-lease-per-client | |
883 | parameter so that roaming clients do not trigger this same behavior. | |
884 | .PP | |
885 | The DHCP protocol normally involves a four-packet exchange - first the | |
886 | client sends a DHCPDISCOVER message, then the server sends a | |
887 | DHCPOFFER, then the client sends a DHCPREQUEST, then the server sends | |
888 | a DHCPACK. In the current version of the server, the server will do | |
889 | a DNS update after it has received the DHCPREQUEST, and before it has | |
890 | sent the DHCPOFFER. It only sends the DNS update if it has not sent | |
891 | one for the client's address before, in order to minimize the impact | |
892 | on the DHCP server. | |
893 | .PP | |
894 | When the client's lease expires, the DHCP server (if it is operating | |
895 | at the time, or when next it operates) will remove the client's A and | |
896 | PTR records from the DNS database. If the client releases its lease | |
897 | by sending a DHCPRELEASE message, the server will likewise remove the | |
898 | A and PTR records. | |
899 | .SH DYNAMIC DNS UPDATE SECURITY | |
900 | .PP | |
59d36179 TL |
901 | When you set your DNS server up to allow updates from the DHCP server, |
902 | you may be exposing it to unauthorized updates. To avoid this, you | |
903 | should use TSIG signatures - a method of cryptographically signing | |
904 | updates using a shared secret key. As long as you protect the | |
905 | secrecy of this key, your updates should also be secure. Note, | |
906 | however, that the DHCP protocol itself provides no security, and that | |
907 | clients can therefore provide information to the DHCP server which the | |
908 | DHCP server will then use in its updates, with the constraints | |
909 | described previously. | |
66ecafef TL |
910 | .PP |
911 | The DNS server must be configured to allow updates for any zone that | |
912 | the DHCP server will be updating. For example, let us say that | |
913 | clients in the sneedville.edu domain will be assigned addresses on the | |
59d36179 TL |
914 | 10.10.17.0/24 subnet. In that case, you will need a key declaration |
915 | for the TSIG key you will be using, and also two zone declarations - | |
916 | one for the zone containing A records that will be updates and one for | |
917 | the zone containing PTR records - for ISC BIND, something like this: | |
66ecafef TL |
918 | .PP |
919 | .nf | |
59d36179 TL |
920 | key DHCP_UPDATER { |
921 | algorithm HMAC-MD5.SIG-ALG.REG.INT; | |
922 | secret pRP5FapFoJ95JEL06sv4PQ==; | |
923 | }; | |
924 | ||
925 | zone "example.org" { | |
66ecafef | 926 | type master; |
59d36179 TL |
927 | file "example.org.db"; |
928 | allow-update { key DHCP_UPDATER; }; | |
66ecafef TL |
929 | }; |
930 | ||
931 | zone "17.10.10.in-addr.arpa" { | |
932 | type master; | |
933 | file "10.10.17.db"; | |
59d36179 | 934 | allow-update { key DHCP_UPDATER; }; |
66ecafef TL |
935 | }; |
936 | .fi | |
937 | .PP | |
59d36179 TL |
938 | You will also have to configure your DHCP server to do updates to |
939 | these zones. To do so, you need to add something like this to your | |
940 | dhcpd.conf file: | |
941 | .PP | |
942 | .nf | |
943 | key DHCP_UPDATER { | |
944 | algorithm HMAC-MD5.SIG-ALG.REG.INT; | |
945 | secret pRP5FapFoJ95JEL06sv4PQ==; | |
946 | }; | |
947 | ||
948 | zone EXAMPLE.ORG. { | |
949 | primary 127.0.0.1; | |
950 | key DHCP_UPDATER; | |
951 | } | |
952 | ||
953 | zone 17.127.10.in-addr.arpa. { | |
954 | primary 127.0.0.1; | |
955 | key DHCP_UPDATER; | |
956 | } | |
957 | .fi | |
958 | .PP | |
959 | You should choose your own secret key, of course. The ISC BIND 8 and | |
960 | 9 distributions come with a program for generating secret keys called | |
961 | dnskeygen. The version that comes with BIND 9 is likely to produce a | |
962 | substantially more random key, so we recommend you use that one even | |
963 | if you are not using BIND 9 as your DNS server. The key above was | |
964 | generated with the command: | |
965 | .nf | |
966 | dnskeygen -H 128 -u -c -n DHCP_UPDATER | |
967 | .fi | |
66ecafef TL |
968 | .PP |
969 | You may wish to enable logging of DNS transactions on your DNS server. | |
970 | To do so, you might write a logging statement like the following: | |
971 | .PP | |
972 | .nf | |
973 | logging { | |
974 | channel update_debug { | |
975 | file "/var/log/update-debug.log"; | |
976 | severity debug 3; | |
977 | print-category yes; | |
978 | print-severity yes; | |
979 | print-time yes; | |
980 | }; | |
981 | channel security_info { | |
982 | file "/var/log/named-auth.info"; | |
983 | severity info; | |
984 | print-category yes; | |
985 | print-severity yes; | |
986 | print-time yes; | |
987 | }; | |
988 | ||
989 | category update { update_debug; }; | |
990 | category security { security_info; }; | |
991 | }; | |
992 | .fi | |
993 | .PP | |
994 | You must create the /var/log/named-auth.info and | |
995 | /var/log/update-debug.log files before starting the name server. For | |
996 | more information on configuring ISC BIND, consult the documentation | |
997 | that accompanies it. | |
0f7099d7 TL |
998 | .SH REFERENCE: EVENTS |
999 | .PP | |
1000 | There are three kinds of events that can happen regarding a lease, and | |
1001 | it is possible to declare statements that occur when any of these | |
1002 | events happen. These events are the commit event, when the server | |
1003 | has made a commitment of a certain lease to a client, the release | |
1004 | event, when the client has released the server from its commitment, | |
1005 | and the expiry event, when the commitment expires. | |
1006 | .PP | |
0f7099d7 | 1007 | To declare a set of statements to execute when an event happens, you |
2cd60a52 | 1008 | must use the \fBon\fR statement, followed by the name of the event, |
0f7099d7 | 1009 | followed by a series of statements to execute when the event happens, |
66ecafef TL |
1010 | enclosed in braces. Events are used to implement dynamic DNS |
1011 | updates, so you should not define your own event handlers if you are | |
1012 | using the built-in dynamic DNS update mechanism. | |
59d36179 TL |
1013 | .PP |
1014 | The built-in version of the dynamic DNS update mechanism is in a text | |
1015 | string towards the top of server/dhcpd.c. If you want to use events | |
1016 | for things other than DNS updates, and you also want DNS updates, you | |
1017 | will have to start out by copying this code into your dhcpd.conf file | |
1018 | and modifying it. | |
5e6b52dc | 1019 | .SH REFERENCE: DECLARATIONS |
d250c5b9 | 1020 | .PP |
5e6b52dc TL |
1021 | .B The |
1022 | .I shared-network | |
1023 | .B statement | |
1024 | .PP | |
1025 | .nf | |
1026 | \fBshared-network\fR \fIname\fR \fB{\fR | |
1027 | [ \fIparameters\fR ] | |
1028 | [ \fIdeclarations\fR ] | |
1029 | \fB}\fR | |
1030 | .fi | |
1031 | .PP | |
1032 | The \fIshared-network\fR statement is used to inform the DHCP server | |
1033 | that some IP subnets actually share the same physical network. Any | |
1034 | subnets in a shared network should be declared within a | |
1035 | \fIshared-network\fR statement. Parameters specified in the | |
1036 | \fIshared-network\fR statement will be used when booting clients on | |
1037 | those subnets unless parameters provided at the subnet or host level | |
1038 | override them. If any subnet in a shared network has addresses | |
1039 | available for dynamic allocation, those addresses are collected into a | |
1040 | common pool for that shared network and assigned to clients as needed. | |
1041 | There is no way to distinguish on which subnet of a shared network a | |
1042 | client should boot. | |
1043 | .PP | |
1044 | .I Name | |
1045 | should be the name of the shared network. This name is used when | |
1046 | printing debugging messages, so it should be descriptive for the | |
1047 | shared network. The name may have the syntax of a valid domain name | |
1048 | (although it will never be used as such), or it may be any arbitrary | |
1049 | name, enclosed in quotes. | |
1050 | .PP | |
1051 | .B The | |
1052 | .I subnet | |
1053 | .B statement | |
1054 | .PP | |
1055 | .nf | |
1056 | \fBsubnet\fR \fIsubnet-number\fR \fBnetmask\fR \fInetmask\fR \fB{\fR | |
1057 | [ \fIparameters\fR ] | |
1058 | [ \fIdeclarations\fR ] | |
1059 | \fB}\fR | |
1060 | .fi | |
1061 | .PP | |
1062 | The \fIsubnet\fR statement is used to provide dhcpd with enough | |
1063 | information to tell whether or not an IP address is on that subnet. | |
1064 | It may also be used to provide subnet-specific parameters and to | |
1065 | specify what addresses may be dynamically allocated to clients booting | |
1066 | on that subnet. Such addresses are specified using the \fIrange\fR | |
1067 | declaration. | |
1068 | .PP | |
1069 | The | |
1070 | .I subnet-number | |
1071 | should be an IP address or domain name which resolves to the subnet | |
1072 | number of the subnet being described. The | |
1073 | .I netmask | |
1074 | should be an IP address or domain name which resolves to the subnet mask | |
1075 | of the subnet being described. The subnet number, together with the | |
1076 | netmask, are sufficient to determine whether any given IP address is | |
1077 | on the specified subnet. | |
1078 | .PP | |
73eaf823 TL |
1079 | Although a netmask must be given with every subnet declaration, it is |
1080 | recommended that if there is any variance in subnet masks at a site, a | |
1081 | subnet-mask option statement be used in each subnet declaration to set | |
1082 | the desired subnet mask, since any subnet-mask option statement will | |
1083 | override the subnet mask declared in the subnet statement. | |
1084 | .PP | |
5e6b52dc TL |
1085 | .B The |
1086 | .I range | |
1087 | .B statement | |
1088 | .PP | |
1089 | .nf | |
d9dc2726 | 1090 | .B range\fR [ \fBdynamic-bootp\fR ] \fIlow-address\fR [ \fIhigh-address\fR]\fB;\fR |
5e6b52dc TL |
1091 | .fi |
1092 | .PP | |
1093 | For any subnet on which addresses will be assigned dynamically, there | |
1094 | must be at least one \fIrange\fR statement. The range statement | |
1095 | gives the lowest and highest IP addresses in a range. All IP | |
1096 | addresses in the range should be in the subnet in which the | |
1097 | \fIrange\fR statement is declared. The \fIdynamic-bootp\fR flag may | |
1098 | be specified if addresses in the specified range may be dynamically | |
1099 | assigned to BOOTP clients as well as DHCP clients. When specifying a | |
1100 | single address, \fIhigh-address\fR can be omitted. | |
1101 | .PP | |
1102 | .B The | |
1103 | .I host | |
1104 | .B statement | |
1105 | .PP | |
1106 | .nf | |
1107 | \fBhost\fR \fIhostname\fR { | |
1108 | [ \fIparameters\fR ] | |
1109 | [ \fIdeclarations\fR ] | |
1110 | \fB}\fR | |
1111 | .fi | |
d250c5b9 | 1112 | .PP |
08fe7cdb | 1113 | There must be at least one |
d250c5b9 TL |
1114 | .B host |
1115 | statement for every BOOTP client that is to be served. | |
1116 | .B host | |
1117 | statements may also be specified for DHCP clients, although this is | |
5e6b52dc | 1118 | not required unless booting is only enabled for known hosts. |
47c9ea95 TL |
1119 | .PP |
1120 | If it is desirable to be able to boot a DHCP or BOOTP | |
d250c5b9 TL |
1121 | client on more than one subnet with fixed addresses, more than one |
1122 | address may be specified in the | |
5e6b52dc TL |
1123 | .I fixed-address |
1124 | parameter, or more than one | |
d250c5b9 | 1125 | .B host |
47c9ea95 TL |
1126 | statement may be specified. |
1127 | .PP | |
5e6b52dc | 1128 | If client-specific boot parameters must change based on the network |
d250c5b9 TL |
1129 | to which the client is attached, then multiple |
1130 | .B host | |
1131 | statements should | |
47c9ea95 TL |
1132 | be used. |
1133 | .PP | |
1134 | If a client is to be booted using a fixed address if it's | |
d250c5b9 TL |
1135 | possible, but should be allocated a dynamic address otherwise, then a |
1136 | .B host | |
1137 | statement must be specified without a | |
1138 | .B fixed-address | |
1139 | clause. | |
1140 | .I hostname | |
5e6b52dc TL |
1141 | should be a name identifying the host. If a \fIhostname\fR option is |
1142 | not specified for the host, \fIhostname\fR is used. | |
1143 | .PP | |
1144 | \fIHost\fR declarations are matched to actual DHCP or BOOTP clients | |
1145 | by matching the \fRdhcp-client-identifier\fR option specified in the | |
1146 | \fIhost\fR declaration to the one supplied by the client, or, if the | |
1147 | \fIhost\fR declaration or the client does not provide a | |
1148 | \fRdhcp-client-identifier\fR option, by matching the \fIhardware\fR | |
1149 | parameter in the \fIhost\fR declaration to the network hardware | |
1150 | address supplied by the client. BOOTP clients do not normally | |
1151 | provide a \fIdhcp-client-identifier\fR, so the hardware address must | |
1152 | be used for all clients that may boot using the BOOTP protocol. | |
1153 | .PP | |
1154 | .B The | |
1155 | .I group | |
1156 | .B statement | |
d250c5b9 | 1157 | .PP |
5e6b52dc TL |
1158 | .nf |
1159 | \fBgroup\fR { | |
1160 | [ \fIparameters\fR ] | |
1161 | [ \fIdeclarations\fR ] | |
1162 | \fB}\fR | |
1163 | .fi | |
1164 | .PP | |
1165 | The group statement is used simply to apply one or more parameters to | |
1166 | a group of declarations. It can be used to group hosts, shared | |
1167 | networks, subnets, or even other groups. | |
1a67a4d7 | 1168 | .SH REFERENCE: ALLOW AND DENY |
66b01364 TL |
1169 | The |
1170 | .I allow | |
1171 | and | |
1172 | .I deny | |
605a8b6d TL |
1173 | statements can be used to control the response of the DHCP server to |
1174 | various sorts of requests. The allow and deny keywords actually have | |
1175 | different meanings depending on the context. In a pool context, these | |
1176 | keywords can be used to set up access lists for address allocation | |
1177 | pools. In other contexts, the keywords simply control general server | |
1178 | behaviour with respect to clients based on scope. In a non-pool | |
1179 | context, the | |
1180 | .I ignore | |
1181 | keyword can be used in place of the | |
1182 | .I deny | |
1183 | keyword to prevent logging of denied requests. | |
1184 | .PP | |
1185 | .SH ALLOW DENY AND IGNORE IN SCOPE | |
1a67a4d7 TL |
1186 | The following usages of allow and deny will work in any scope, |
1187 | although it is not recommended that they be used in pool | |
1188 | declarations. | |
66b01364 TL |
1189 | .PP |
1190 | .B The | |
1191 | .I unknown-clients | |
1192 | .B keyword | |
1193 | .PP | |
1194 | \fBallow unknown-clients;\fR | |
1195 | \fBdeny unknown-clients;\fR | |
605a8b6d | 1196 | \fBignore unknown-clients;\fR |
66b01364 TL |
1197 | .PP |
1198 | The \fBunknown-clients\fR flag is used to tell dhcpd whether | |
1199 | or not to dynamically assign addresses to unknown clients. Dynamic | |
1200 | address assignment to unknown clients is \fBallow\fRed by default. | |
1201 | .PP | |
1202 | .B The | |
1203 | .I bootp | |
1204 | .B keyword | |
1205 | .PP | |
1206 | \fBallow bootp;\fR | |
1207 | \fBdeny bootp;\fR | |
605a8b6d | 1208 | \fBignore bootp;\fR |
66b01364 | 1209 | .PP |
ba7ed239 | 1210 | The \fBbootp\fR flag is used to tell dhcpd whether |
66b01364 TL |
1211 | or not to respond to bootp queries. Bootp queries are \fBallow\fRed |
1212 | by default. | |
1213 | .PP | |
1214 | .B The | |
1215 | .I booting | |
1216 | .B keyword | |
1217 | .PP | |
1218 | \fBallow booting;\fR | |
1219 | \fBdeny booting;\fR | |
605a8b6d | 1220 | \fBignore booting;\fR |
66b01364 TL |
1221 | .PP |
1222 | The \fBbooting\fR flag is used to tell dhcpd whether or not to respond | |
1223 | to queries from a particular client. This keyword only has meaning | |
1224 | when it appears in a host declaration. By default, booting is | |
1225 | \fBallow\fRed, but if it is disabled for a particular client, then | |
1226 | that client will not be able to get and address from the DHCP server. | |
605a8b6d TL |
1227 | .B The |
1228 | .I duplicates | |
1229 | .B keyword | |
1230 | .PP | |
1231 | \fBallow duplicates;\fR | |
1232 | \fBdeny duplicates;\fR | |
1233 | .PP | |
1234 | Host declarations can match client messages based on the DHCP Client | |
1235 | Identifer option or based on the client's network hardware type and | |
1236 | MAC address. If the MAC address is used, the host declaration will | |
1237 | match any client with that MAC address - even clients with different | |
1238 | client identifiers. This doesn't normally happen, but is possible | |
1239 | when one computer has more than one operating system installed on it - | |
1240 | for example, Microsoft Windows and NetBSD or Linux. | |
1241 | .PP | |
1242 | The \fBduplicates\fR flag tells the DHCP server that if a request is | |
1243 | received from a client that matches the MAC address of a host | |
1244 | declaration, any other leases matching that MAC address should be | |
1245 | discarded by the server, even if the UID is not the same. This is a | |
1246 | violation of the DHCP protocol, but can prevent clients whose client | |
1247 | identifiers change regularly from holding many leases at the same time. | |
1248 | By default, duplicates are \fBallow\fRed. | |
1249 | .B The | |
1250 | .I declines | |
1251 | .B keyword | |
1252 | .PP | |
1253 | \fBallow declines;\fR | |
1254 | \fBdeny declines;\fR | |
1255 | \fBignore declines;\fR | |
1256 | .PP | |
1257 | The DHCPDECLINE message is used by DHCP clients to indicate that the | |
1258 | lease the server has offered is not valid. When the server receives | |
1259 | a DHCPDECLINE for a particular address, it normally abandons that | |
1260 | address, assuming that some unauthorized system is using it. | |
1261 | Unfortunately, a malicious or buggy client can, using DHCPDECLINE | |
1262 | messages, completely exhaust the DHCP server's allocation pool. The | |
1263 | server will reclaim these leases, but while the client is running | |
1264 | through the pool, it may cause serious thrashing in the DNS, and it | |
1265 | will also cause the DHCP server to forget old DHCP client address | |
1266 | allocations. | |
1267 | .PP | |
1268 | The \fBdeclines\fR flag tells the DHCP server whether or not to honor | |
1269 | DHCPDECLINE messages. If it is set to \fBdeny\fR or \fBignore\fR in | |
1270 | a particular scope, the DHCP server will not respond to DHCPDECLINE | |
1271 | messages. | |
1a67a4d7 TL |
1272 | .SH ALLOW AND DENY WITHIN POOL DECLARATIONS |
1273 | .PP | |
1274 | The uses of the allow and deny keyword shown in the previous section | |
1275 | work pretty much the same way whether the client is sending a | |
1276 | DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated | |
1277 | to the client (either the old address it's requesting, or a new | |
1278 | address) and then that address will be tested to see if it's okay to | |
1279 | let the client have it. If the client requested it, and it's not | |
1280 | okay, the server will send a DHCPNAK message. Otherwise, the server | |
1281 | will simply not respond to the client. If it is okay to give the | |
1282 | address to the client, the server will send a DHCPACK message. | |
1283 | .PP | |
1284 | The primary motivation behind pool declarations is to have address | |
1285 | allocation pools whose allocation policies are different. A client | |
1286 | may be denied access to one pool, but allowed access to another pool | |
1287 | on the same network segment. In order for this to work, access | |
1288 | control has to be done during address allocation, not after address | |
1289 | allocation is done. | |
1290 | .PP | |
1291 | When a DHCPREQUEST message is processed, address allocation simply | |
1292 | consists of looking up the address the client is requesting and seeing | |
1293 | if it's still available for the client. If it is, then the DHCP | |
1294 | server checks both the address pool permit lists and the relevant | |
1295 | in-scope allow and deny statements to see if it's okay to give the | |
1296 | lease to the client. In the case of a DHCPDISCOVER message, the | |
1297 | allocation process is done as described previously in the ADDRESS | |
1298 | ALLOCATION section. | |
1299 | .PP | |
1300 | When declaring permit lists for address allocation pools, the | |
1301 | following syntaxes are recognized following the allow or deny keyword: | |
1302 | .PP | |
1303 | \fBknown clients;\fR | |
1304 | .PP | |
1305 | If specified, this statement either allows or prevents allocation from | |
1306 | this pool to any client that has a host declaration (i.e., is known). | |
66ecafef TL |
1307 | A client is known if it has a host declaration in \fIany\fR scope, not |
1308 | just the current scope. | |
1a67a4d7 TL |
1309 | .PP |
1310 | \fBunknown clients;\fR | |
1311 | .PP | |
1312 | If specified, this statement either allows or prevents allocation from | |
1313 | this pool to any client that has no host declaration (i.e., is not | |
1314 | known). | |
1315 | .PP | |
1316 | \fBmembers of "\fRclass\fB";\fR | |
1317 | .PP | |
1318 | If specified, this statement either allows or prevents allocation from | |
1319 | this pool to any client that is a member of the named class. | |
1320 | .PP | |
1321 | \fBdynamic bootp clients;\fR | |
1322 | .PP | |
1323 | If specified, this statement either allows or prevents allocation from | |
1324 | this pool to any bootp client. | |
1325 | .PP | |
1326 | \fBauthenticated clients;\fR | |
1327 | .PP | |
1328 | If specified, this statement either allows or prevents allocation from | |
1329 | this pool to any client that has been authenticated using the DHCP | |
1330 | authentication protocol. This is not yet supported. | |
1331 | .PP | |
1332 | \fBunauthenticated clients;\fR | |
1333 | .PP | |
1334 | If specified, this statement either allows or prevents allocation from | |
1335 | this pool to any client that has not been authenticated using the DHCP | |
1336 | authentication protocol. This is not yet supported. | |
1337 | .PP | |
1338 | \fBall clients;\fR | |
1339 | .PP | |
1340 | If specified, this statement either allows or prevents allocation from | |
1341 | this pool to all clients. This can be used when you want to write a | |
1342 | pool declaration for some reason, but hold it in reserve, or when you | |
1343 | want to renumber your network quickly, and thus want the server to | |
1344 | force all clients that have been allocated addresses from this pool to | |
1345 | obtain new addresses immediately when they next renew. | |
5e6b52dc TL |
1346 | .SH REFERENCE: PARAMETERS |
1347 | .PP | |
1348 | .B The | |
0a1c1f11 TL |
1349 | .I lease-file-name |
1350 | .B statement | |
1351 | .PP | |
1352 | .B lease-file-name | |
1353 | .I name\fR\fB;\fR | |
1354 | .PP | |
1355 | .I Name | |
1356 | should be the name of the DHCP server's lease file. By default, this | |
1357 | is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer | |
1358 | scope of the configuration file - if it appears in some other scope, | |
1359 | it will have no effect. | |
1360 | .PP | |
1361 | .B The | |
1362 | .I pid-file-name | |
1363 | .B statement | |
1364 | .PP | |
1365 | .B pid-file-name | |
1366 | .I name\fR\fB;\fR | |
1367 | .PP | |
1368 | .I Name | |
1369 | should be the name of the DHCP server's process ID file. This is the | |
1370 | file in which the DHCP server's process ID is stored when the server | |
1371 | starts. By default, this is RUNDIR/dhcpd.pid. Like the | |
1372 | lease-file-name statement, this statement must appear in the outer scope | |
1373 | of the configuration file. | |
1374 | .PP | |
1375 | .B The | |
5e6b52dc TL |
1376 | .I default-lease-time |
1377 | .B statement | |
1378 | .PP | |
1379 | \fBdefault-lease-time\fR \fItime\fR\fB;\fR | |
1380 | .PP | |
1381 | .I Time | |
1382 | should be the length in seconds that will be assigned to a lease if | |
1383 | the client requesting the lease does not ask for a specific expiration | |
1384 | time. | |
1385 | .PP | |
1386 | .B The | |
1387 | .I max-lease-time | |
1388 | .B statement | |
1389 | .PP | |
1390 | \fBmax-lease-time\fR \fItime\fR\fB;\fR | |
1391 | .PP | |
1392 | .I Time | |
1393 | should be the maximum length in seconds that will be assigned to a | |
71498466 TL |
1394 | lease. The only exception to this is that Dynamic BOOTP lease |
1395 | lengths, which are not specified by the client, are not limited by | |
1396 | this maximum. | |
5e6b52dc | 1397 | .PP |
cdd70b87 TL |
1398 | .B The |
1399 | .I min-lease-time | |
1400 | .B statement | |
1401 | .PP | |
1402 | \fBmin-lease-time\fR \fItime\fR\fB;\fR | |
1403 | .PP | |
1404 | .I Time | |
1405 | should be the minimum length in seconds that will be assigned to a | |
71498466 | 1406 | lease. |
cdd70b87 TL |
1407 | .PP |
1408 | .B The | |
1409 | .I min-secs | |
1410 | .B statement | |
1411 | .PP | |
1412 | \fBmin-secs\fR \fIseconds\fR\fB;\fR | |
1413 | .PP | |
1414 | .I Seconds | |
1415 | should be the minimum number of seconds since a client began trying to | |
1416 | acquire a new lease before the DHCP server will respond to its request. | |
1417 | The number of seconds is based on what the client reports, and the maximum | |
1418 | value that the client can report is 255 seconds. Generally, setting this | |
1419 | to one will result in the DHCP server not responding to the client's first | |
1420 | request, but always responding to its second request. | |
1421 | .PP | |
1422 | This can be used | |
1423 | to set up a secondary DHCP server which never offers an address to a client | |
1424 | until the primary server has been given a chance to do so. If the primary | |
1425 | server is down, the client will bind to the secondary server, but otherwise | |
1426 | clients should always bind to the primary. Note that this does not, by | |
1427 | itself, permit a primary server and a secondary server to share a pool of | |
1428 | dynamically-allocatable addresses. | |
1429 | .PP | |
5e6b52dc TL |
1430 | .B The |
1431 | .I hardware | |
1432 | .B statement | |
1433 | .PP | |
1434 | \fBhardware\fR \fIhardware-type\fR \fIhardware-address\fR\fB;\fR | |
d250c5b9 | 1435 | .PP |
08fe7cdb | 1436 | In order for a BOOTP client to be recognized, its network hardware |
5e6b52dc TL |
1437 | address must be declared using a \fIhardware\fR clause in the |
1438 | .I host | |
1439 | statement. | |
d250c5b9 | 1440 | .I hardware-type |
08fe7cdb TL |
1441 | must be the name of a physical hardware interface type. Currently, |
1442 | only the | |
d250c5b9 | 1443 | .B ethernet |
08fe7cdb | 1444 | and |
2b1986ed TL |
1445 | .B token-ring |
1446 | types are recognized, although support for a | |
d250c5b9 | 1447 | .B fddi |
2b1986ed | 1448 | hardware type (and others) would also be desirable. |
08fe7cdb | 1449 | The |
d250c5b9 | 1450 | .I hardware-address |
08fe7cdb | 1451 | should be a set of hexadecimal octets (numbers from 0 through ff) |
2d1b06e0 | 1452 | seperated by colons. The \fIhardware\fR statement may also be used |
5e6b52dc | 1453 | for DHCP clients. |
d250c5b9 | 1454 | .PP |
5e6b52dc | 1455 | .B The |
d250c5b9 | 1456 | .I filename |
5e6b52dc | 1457 | .B statement |
d250c5b9 | 1458 | .PP |
5e6b52dc TL |
1459 | \fBfilename\fR \fB"\fR\fIfilename\fR\fB";\fR |
1460 | .PP | |
1461 | The \fIfilename\fR statement can be used to specify the name of the | |
1462 | initial boot file which is to be loaded by a client. The | |
d250c5b9 | 1463 | .I filename |
08fe7cdb TL |
1464 | should be a filename recognizable to whatever file transfer protocol |
1465 | the client can be expected to use to load the file. | |
d250c5b9 | 1466 | .PP |
5e6b52dc TL |
1467 | .B The |
1468 | .I server-name | |
1469 | .B statement | |
1470 | .PP | |
1471 | \fBserver-name\fR \fB"\fR\fIname\fR\fB";\fR | |
1472 | .PP | |
1473 | The \fIserver-name\fR statement can be used to inform the client of | |
1474 | the name of the server from which it is booting. \fIName\fR should | |
1475 | be the name that will be provided to the client. | |
1476 | .PP | |
1477 | .B The | |
1478 | .I next-server | |
1479 | .B statement | |
1480 | .PP | |
1481 | \fBnext-server\fR \fIserver-name\fR\fB;\fR | |
1482 | .PP | |
1483 | The \fInext-server\fR statement is used to specify the host address of | |
1484 | the server from which the initial boot file (specified in the | |
1485 | \fIfilename\fR statement) is to be loaded. \fIServer-name\fR should | |
1486 | be a numeric IP address or a domain name. If no \fInext-server\fR | |
612bc350 TL |
1487 | parameter applies to a given client, the DHCP server's IP address is |
1488 | used. | |
5e6b52dc TL |
1489 | .PP |
1490 | .B The | |
1491 | .I fixed-address | |
1492 | .B statement | |
1493 | .PP | |
1494 | \fBfixed-address\fR \fIaddress\fR [\fB,\fR \fIaddress\fR ... ]\fB;\fR | |
1495 | .PP | |
1496 | The \fIfixed-address\fR statement is used to assign one or more fixed | |
1497 | IP addresses to a client. It should only appear in a \fIhost\fR | |
1498 | declaration. If more than one address is supplied, then when the | |
1499 | client boots, it will be assigned the address which corresponds to the | |
1500 | network on which it is booting. If none of the addresses in the | |
1501 | \fIfixed-address\fR statement are on the network on which the client | |
1502 | is booting, that client will not match the \fIhost\fR declaration | |
1503 | containing that \fIfixed-address\fR statement. Each \fIaddress\fR | |
1504 | should be either an IP address or a domain name which resolves to one | |
1505 | or more IP addresses. | |
1506 | .PP | |
1507 | .B The | |
1508 | .I dynamic-bootp-lease-cutoff | |
1509 | .B statement | |
1510 | .PP | |
1511 | \fBdynamic-bootp-lease-cutoff\fR \fIdate\fR\fB;\fR | |
1512 | .PP | |
1513 | The \fIdynamic-bootp-lease-cutoff\fR statement sets the ending time | |
1514 | for all leases assigned dynamically to BOOTP clients. Because BOOTP | |
1515 | clients do not have any way of renewing leases, and don't know that | |
1516 | their leases could expire, by default dhcpd assignes infinite leases | |
1517 | to all BOOTP clients. However, it may make sense in some situations | |
1518 | to set a cutoff date for all BOOTP leases - for example, the end of a | |
1519 | school term, or the time at night when a facility is closed and all | |
1520 | machines are required to be powered off. | |
1521 | .PP | |
1522 | .I Date | |
1523 | should be the date on which all assigned BOOTP leases will end. The | |
1524 | date is specified in the form: | |
1525 | .PP | |
1526 | .ce 1 | |
1527 | W YYYY/MM/DD HH:MM:SS | |
1528 | .PP | |
1529 | W is the day of the week expressed as a number | |
1530 | from zero (Sunday) to six (Saturday). YYYY is the year, including the | |
1531 | century. MM is the month expressed as a number from 1 to 12. DD is | |
1532 | the day of the month, counting from 1. HH is the hour, from zero to | |
1533 | 23. MM is the minute and SS is the second. The time is always in | |
6ceb9118 | 1534 | Coordinated Universal Time (UTC), not local time. |
5e6b52dc TL |
1535 | .PP |
1536 | .B The | |
1537 | .I dynamic-bootp-lease-length | |
1538 | .B statement | |
1539 | .PP | |
1540 | \fBdynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR | |
1541 | .PP | |
1542 | The \fIdynamic-bootp-lease-length\fR statement is used to set the | |
1543 | length of leases dynamically assigned to BOOTP clients. At some | |
1544 | sites, it may be possible to assume that a lease is no longer in | |
1545 | use if its holder has not used BOOTP or DHCP to get its address within | |
1546 | a certain time period. The period is specified in \fIlength\fR as a | |
1547 | number of seconds. If a client reboots using BOOTP during the | |
1548 | timeout period, the lease duration is reset to \fIlength\fR, so a | |
1549 | BOOTP client that boots frequently enough will never lose its lease. | |
1550 | Needless to say, this parameter should be adjusted with extreme | |
1551 | caution. | |
1552 | .PP | |
1553 | .B The | |
5fea7b10 TL |
1554 | .I get-lease-hostnames |
1555 | .B statement | |
1556 | .PP | |
1557 | \fBget-lease-hostnames\fR \fIflag\fR\fB;\fR | |
1558 | .PP | |
1559 | The \fIget-lease-hostnames\fR statement is used to tell dhcpd whether | |
1560 | or not to look up the domain name corresponding to the IP address of | |
1561 | each address in the lease pool and use that address for the DHCP | |
1562 | \fIhostname\fR option. If \fIflag\fR is true, then this lookup is | |
1563 | done for all addresses in the current scope. By default, or if | |
1564 | \fIflag\fR is false, no lookups are done. | |
c256bae9 TL |
1565 | .PP |
1566 | .B The | |
1567 | .I use-host-decl-names | |
1568 | .B statement | |
1569 | .PP | |
1570 | \fBuse-host-decl-names\fR \fIflag\fR\fB;\fR | |
1571 | .PP | |
1572 | If the \fIuse-host-decl-names\fR parameter is true in a given scope, | |
1573 | then for every host declaration within that scope, the name provided | |
1574 | for the host declaration will be supplied to the client as its | |
1575 | hostname. So, for example, | |
1576 | .PP | |
1577 | .nf | |
1578 | group { | |
1579 | use-host-decl-names on; | |
1580 | ||
1581 | host joe { | |
1582 | hardware ethernet 08:00:2b:4c:29:32; | |
1583 | fixed-address joe.fugue.com; | |
1584 | } | |
1585 | } | |
1586 | ||
1587 | is equivalent to | |
1588 | ||
1589 | host joe { | |
1590 | hardware ethernet 08:00:2b:4c:29:32; | |
1591 | fixed-address joe.fugue.com; | |
1592 | option host-name "joe"; | |
1593 | } | |
1594 | .fi | |
1595 | .PP | |
1596 | An \fIoption host-name\fR statement within a host declaration will | |
1597 | override the use of the name in the host declaration. | |
d250c5b9 | 1598 | .PP |
612bc350 | 1599 | .B The |
c43fe218 TL |
1600 | .I authoritative |
1601 | .B statement | |
1602 | .PP | |
1603 | \fBauthoritative;\fR | |
1604 | .PP | |
1605 | \fBnot authoritative;\fR | |
1606 | .PP | |
1607 | The DHCP server will normally assume that the configuration | |
007e3ee4 TL |
1608 | information about a given network segment is not known to be correct |
1609 | and is not authoritative. This is so that if a naive user installs a | |
1610 | DHCP server not fully understanding how to configure it, it does not | |
1611 | send spurious DHCPNAK messages to clients that have obtained addresses | |
1612 | from a legitimate DHCP server on the network. | |
1613 | .PP | |
1614 | Network administrators setting up authoritative DHCP servers for their | |
1615 | networks should always write \fBauthoritative;\fR at the top of their | |
1616 | configuration file to indicate that the DHCP server \fIshould\fR send | |
1617 | DHCPNAK messages to misconfigured clients. If this is not done, | |
1618 | clients will be unable to get a correct IP address after changing | |
1619 | subnets until their old lease has expired, which could take quite a | |
1620 | long time. | |
1621 | .PP | |
1622 | Usually, writing \fBauthoritative;\fR at the top level of the file | |
c43fe218 TL |
1623 | should be sufficient. However, if a DHCP server is to be set up so |
1624 | that it is aware of some networks for which it is authoritative and | |
1625 | some networks for which it is not, it may be more appropriate to | |
1626 | declare authority on a per-network-segment basis. | |
1627 | .PP | |
1628 | Note that the most specific scope for which the concept of authority | |
1629 | makes any sense is the physical network segment - either a | |
1630 | shared-network statement or a subnet statement that is not contained | |
1631 | within a shared-network statement. It is not meaningful to specify | |
1632 | that the server is authoritative for some subnets within a shared | |
1633 | network, but not authoritative for others, nor is it meaningful to | |
1634 | specify that the server is authoritative for some host declarations | |
1635 | and not others. | |
1636 | .PP | |
1637 | .B The | |
41885489 TL |
1638 | .I always-reply-rfc1048 |
1639 | .B statement | |
1640 | .PP | |
1641 | \fBalways-reply-rfc1048\fR \fIflag\fR\fB;\fR | |
1642 | .PP | |
1643 | Some BOOTP clients expect RFC1048-style responses, but do not follow | |
1644 | RFC1048 when sending their requests. You can tell that a client is | |
1645 | having this problem if it is not getting the options you have | |
1646 | configured for it and if you see in the server log the message | |
1647 | "(non-rfc1048)" printed with each BOOTREQUEST that is logged. | |
1648 | .PP | |
1649 | If you want to send rfc1048 options to such a client, you can set the | |
1650 | .B always-reply-rfc1048 | |
1651 | option in that client's host declaration, and the DHCP server will | |
1652 | respond with an RFC-1048-style vendor options field. This flag can | |
1653 | be set in any scope, and will affect all clients covered by that | |
1654 | scope. | |
1655 | .PP | |
1656 | .B The | |
b1c231ba TL |
1657 | .I always-broadcast |
1658 | .B statement | |
1659 | .PP | |
1660 | \fBalways-broadcast\fR \fIflag\fR\fB;\fR | |
1661 | .PP | |
1662 | The DHCP and BOOTP protocols both require DHCP and BOOTP clients to | |
1663 | set the broadcast bit in the flags field of the BOOTP message header. | |
1664 | Unfortunately, some DHCP and BOOTP clients do not do this, and | |
1665 | therefore may not receive responses from the DHCP server. The DHCP | |
1666 | server can be made to always broadcast its responses to clients by | |
1667 | setting this flag to 'on' for the relevant scope. To avoid creating | |
1668 | excess broadcast traffic on your network, we recommend that you | |
1669 | restrict the use of this option to as few clients as possible. For | |
1670 | example, the Microsoft DHCP client is known not to have this problem, | |
1671 | as are the OpenTransport and ISC DHCP clients. | |
1672 | .PP | |
1673 | .B The | |
600d4b35 TL |
1674 | .I one-lease-per-client |
1675 | .B statement | |
1676 | .PP | |
1677 | \fBone-lease-per-client\fR \fIflag\fR\fB;\fR | |
1678 | .PP | |
1679 | If this flag is enabled, whenever a client sends a DHCPREQUEST for a | |
1680 | particular lease, the server will automatically free any other leases | |
1681 | the client holds. This presumes that when the client sends a | |
1682 | DHCPREQUEST, it has forgotten any lease not mentioned in the | |
1683 | DHCPREQUEST - i.e., the client has only a single network interface | |
1684 | .I and | |
1685 | it does not remember leases it's holding on networks to which it is | |
1686 | not currently attached. Neither of these assumptions are guaranteed | |
1687 | or provable, so we urge caution in the use of this statement. | |
1688 | .PP | |
1689 | .B The | |
cdd70b87 TL |
1690 | .I use-lease-addr-for-default-route |
1691 | .B statement | |
1692 | .PP | |
1693 | \fBuse-lease-addr-for-default-route\fR \fIflag\fR\fB;\fR | |
1694 | .PP | |
1695 | If the \fIuse-lease-addr-for-default-route\fR parameter is true in a | |
1696 | given scope, then instead of sending the value specified in the | |
1697 | routers option (or sending no value at all), the IP address of the | |
1698 | lease being assigned is sent to the client. This supposedly causes | |
1699 | Win95 machines to ARP for all IP addresses, which can be helpful if | |
1700 | your router is configured for proxy ARP. | |
1701 | .PP | |
1702 | .B The | |
612bc350 TL |
1703 | .I server-identifier |
1704 | .B statement | |
d250c5b9 | 1705 | .PP |
612bc350 | 1706 | \fBserver-identifier \fIhostname\fR\fB;\fR |
d250c5b9 | 1707 | .PP |
b13b05da TL |
1708 | The server-identifier statement can be used to define the value that |
1709 | is sent in the DHCP Server Identifier option for a given scope. The | |
1710 | value specified \fBmust\fR be an IP address for the DHCP server, and | |
1711 | must be reachable by all clients served by a particular scope. | |
1712 | .PP | |
1713 | The use of the server-identifier statement is not recommended - the only | |
1714 | reason to use it is to force a value other than the default value to be | |
1715 | sent on occasions where the default value would be incorrect. The default | |
1716 | value is the first IP address associated with the physical network interface | |
74f45f96 TL |
1717 | on which the request arrived. |
1718 | .PP | |
1719 | The usual case where the | |
b13b05da TL |
1720 | \fIserver-identifier\fR statement needs to be sent is when a physical |
1721 | interface has more than one IP address, and the one being sent by default | |
1722 | isn't appropriate for some or all clients served by that interface. | |
74f45f96 TL |
1723 | Another common case is when an alias is defined for the purpose of |
1724 | having a consistent IP address for the DHCP server, and it is desired | |
1725 | that the clients use this IP address when contacting the server. | |
1726 | .PP | |
1727 | Supplying a value for the dhcp-server-identifier option is equivalent | |
1728 | to using the server-identifier statement. | |
66ecafef TL |
1729 | .PP |
1730 | .B The | |
1731 | .I ddns-updates | |
1732 | .B statement | |
1733 | .PP | |
1734 | \fBddns-updates \fIflag\fR\fB;\fR | |
1735 | .PP | |
1736 | The \fIddns-updates\fR parameter controls whether or not the server will | |
1737 | attempt to do a ddns update when a lease is confirmed. Set this to \fIoff\fR | |
1738 | if the server should not attempt to do updates within a certain scope. | |
1739 | The \fIddns-updates\fR parameter is on by default. | |
e501cb07 TL |
1740 | .SH SETTING PARAMETER VALUES USING EXPRESSIONS |
1741 | Sometimes it's helpful to be able to set the value of a DHCP server | |
1742 | parameter based on some value that the client has sent. To do this, | |
1743 | you can use expression evaluation. The | |
1744 | .B dhcp-eval(5) | |
1745 | manual page describes how to write expressions. To assign the result | |
1746 | of an evaluation to an option, define the option as follows: | |
1747 | .nf | |
1748 | .sp 1 | |
1749 | \fImy-parameter \fB= \fIexpression \fB;\fR | |
1750 | .fi | |
1751 | .PP | |
1752 | For example: | |
1753 | .nf | |
1754 | .sp 1 | |
1755 | ddns-hostname = binary-to-ascii (16, 8, "-", | |
1756 | substring (hardware, 1, 6)); | |
1757 | .fi | |
612bc350 | 1758 | .SH REFERENCE: OPTION STATEMENTS |
d250c5b9 | 1759 | .PP |
612bc350 TL |
1760 | DHCP option statements are documented in the |
1761 | .B dhcp-options(5) | |
1762 | manual page. | |
d250c5b9 | 1763 | .SH SEE ALSO |
65e15add | 1764 | dhcpd.conf(5), dhcpd.leases(5), RFC2132, RFC2131. |
d250c5b9 TL |
1765 | .SH AUTHOR |
1766 | .B dhcpd(8) | |
1767 | was written by Ted Lemon <mellon@vix.com> | |
08fe7cdb | 1768 | under a contract with Vixie Labs. Funding |
f39b6e00 | 1769 | for this project was provided by the Internet Software Consortium. |
08fe7cdb | 1770 | Information about the Internet Software Consortium can be found at |
d250c5b9 | 1771 | .B http://www.isc.org/isc. |