Import (slightly modified) ru.koi8-r.win.kbd:1.1 from FreeBSD (fjoe):
[dragonfly.git] / contrib / dhcp-3.0 / server / dhcpd.conf.5
1 .\"     dhcpd.conf.5
2 .\"
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 1996-2003 by Internet Software Consortium
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
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.
17 .\"
18 .\"   Internet Systems Consortium, Inc.
19 .\"   950 Charter Street
20 .\"   Redwood City, CA 94063
21 .\"   <info@isc.org>
22 .\"   http://www.isc.org/
23 .\"
24 .\" This software has been written for Internet Systems Consortium
25 .\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.
26 .\" To learn more about Internet Systems Consortium, see
27 .\" ``http://www.isc.org/''.  To learn more about Vixie Enterprises,
28 .\" see ``http://www.vix.com''.   To learn more about Nominum, Inc., see
29 .\" ``http://www.nominum.com''.
30 .\"
31 .\" $Id: dhcpd.conf.5,v 1.63.2.22 2004/09/29 23:01:50 dhankins Exp $
32 .\"
33 .TH dhcpd.conf 5
34 .SH NAME
35 dhcpd.conf - dhcpd configuration file
36 .SH DESCRIPTION
37 The dhcpd.conf file contains configuration information for
38 .IR dhcpd,
39 the Internet Systems Consortium DHCP Server.
40 .PP
41 The dhcpd.conf file is a free-form ASCII text file.   It is parsed by
42 the recursive-descent parser built into dhcpd.   The file may contain
43 extra tabs and newlines for formatting purposes.  Keywords in the file
44 are case-insensitive.   Comments may be placed anywhere within the
45 file (except within quotes).   Comments begin with the # character and
46 end at the end of the line.
47 .PP
48 The file essentially consists of a list of statements.   Statements
49 fall into two broad categories - parameters and declarations.
50 .PP
51 Parameter statements either say how to do something (e.g., how long a
52 lease to offer), whether to do something (e.g., should dhcpd provide
53 addresses to unknown clients), or what parameters to provide to the
54 client (e.g., use gateway 220.177.244.7).
55 .PP
56 Declarations are used to describe the topology of the
57 network, to describe clients on the network, to provide addresses that
58 can be assigned to clients, or to apply a group of parameters to a
59 group of declarations.   In any group of parameters and declarations,
60 all parameters must be specified before any declarations which depend
61 on those parameters may be specified.
62 .PP
63 Declarations about network topology include the \fIshared-network\fR
64 and the \fIsubnet\fR declarations.   If clients on a subnet are to be
65 assigned addresses
66 dynamically, a \fIrange\fR declaration must appear within the
67 \fIsubnet\fR declaration.   For clients with statically assigned
68 addresses, or for installations where only known clients will be
69 served, each such client must have a \fIhost\fR declaration.   If
70 parameters are to be applied to a group of declarations which are not
71 related strictly on a per-subnet basis, the \fIgroup\fR declaration
72 can be used.
73 .PP
74 For every subnet which will be served, and for every subnet
75 to which the dhcp server is connected, there must be one \fIsubnet\fR
76 declaration, which tells dhcpd how to recognize that an address is on
77 that subnet.  A \fIsubnet\fR declaration is required for each subnet
78 even if no addresses will be dynamically allocated on that subnet.
79 .PP
80 Some installations have physical networks on which more than one IP
81 subnet operates.   For example, if there is a site-wide requirement
82 that 8-bit subnet masks be used, but a department with a single
83 physical ethernet network expands to the point where it has more than
84 254 nodes, it may be necessary to run two 8-bit subnets on the same
85 ethernet until such time as a new physical network can be added.   In
86 this case, the \fIsubnet\fR declarations for these two networks must be
87 enclosed in a \fIshared-network\fR declaration.
88 .PP
89 Some sites may have departments which have clients on more than one
90 subnet, but it may be desirable to offer those clients a uniform set
91 of parameters which are different than what would be offered to
92 clients from other departments on the same subnet.   For clients which
93 will be declared explicitly with \fIhost\fR declarations, these
94 declarations can be enclosed in a \fIgroup\fR declaration along with
95 the parameters which are common to that department.   For clients
96 whose addresses will be dynamically assigned, class declarations and
97 conditional declarations may be used to group parameter assignments
98 based on information the client sends.
99 .PP
100 When a client is to be booted, its boot parameters are determined by
101 consulting that client's \fIhost\fR declaration (if any), and then
102 consulting any \fIclass\fR declarations matching the client,
103 followed by the \fIpool\fR, \fIsubnet\fR and \fIshared-network\fR
104 declarations for the IP address assigned to the client.   Each of
105 these declarations itself appears within a lexical scope, and all
106 declarations at less specific lexical scopes are also consulted for
107 client option declarations.   Scopes are never considered
108 twice, and if parameters are declared in more than one scope, the
109 parameter declared in the most specific scope is the one that is
110 used.
111 .PP
112 When dhcpd tries to find a \fIhost\fR declaration for a client, it
113 first looks for a \fIhost\fR declaration which has a
114 \fIfixed-address\fR declaration that lists an IP address that is valid
115 for the subnet or shared network on which the client is booting.   If
116 it doesn't find any such entry, it tries to find an entry which has
117 no \fIfixed-address\fR declaration.
118 .SH EXAMPLES
119 .PP
120 A typical dhcpd.conf file will look something like this:
121 .nf
122
123 .I global parameters...
124
125 subnet 204.254.239.0 netmask 255.255.255.224 {
126   \fIsubnet-specific parameters...\fR
127   range 204.254.239.10 204.254.239.30;
128 }
129
130 subnet 204.254.239.32 netmask 255.255.255.224 {
131   \fIsubnet-specific parameters...\fR
132   range 204.254.239.42 204.254.239.62;
133 }
134
135 subnet 204.254.239.64 netmask 255.255.255.224 {
136   \fIsubnet-specific parameters...\fR
137   range 204.254.239.74 204.254.239.94;
138 }
139
140 group {
141   \fIgroup-specific parameters...\fR
142   host zappo.test.isc.org {
143     \fIhost-specific parameters...\fR
144   }
145   host beppo.test.isc.org {
146     \fIhost-specific parameters...\fR
147   }
148   host harpo.test.isc.org {
149     \fIhost-specific parameters...\fR
150   }
151 }
152
153 .ce 1
154 Figure 1
155
156 .fi
157 .PP
158 Notice that at the beginning of the file, there's a place
159 for global parameters.   These might be things like the organization's
160 domain name, the addresses of the name servers (if they are common to
161 the entire organization), and so on.   So, for example:
162 .nf
163
164         option domain-name "isc.org";
165         option domain-name-servers ns1.isc.org, ns2.isc.org;
166
167 .ce 1
168 Figure 2
169 .fi
170 .PP
171 As you can see in Figure 2, you can specify host addresses in
172 parameters using their domain names rather than their numeric IP
173 addresses.  If a given hostname resolves to more than one IP address
174 (for example, if that host has two ethernet interfaces), then where
175 possible, both addresses are supplied to the client.
176 .PP
177 The most obvious reason for having subnet-specific parameters as
178 shown in Figure 1 is that each subnet, of necessity, has its own
179 router.   So for the first subnet, for example, there should be
180 something like:
181 .nf
182
183         option routers 204.254.239.1;
184 .fi
185 .PP
186 Note that the address here is specified numerically.   This is not
187 required - if you have a different domain name for each interface on
188 your router, it's perfectly legitimate to use the domain name for that
189 interface instead of the numeric address.   However, in many cases
190 there may be only one domain name for all of a router's IP addresses, and
191 it would not be appropriate to use that name here.
192 .PP
193 In Figure 1 there is also a \fIgroup\fR statement, which provides
194 common parameters for a set of three hosts - zappo, beppo and harpo.
195 As you can see, these hosts are all in the test.isc.org domain, so it
196 might make sense for a group-specific parameter to override the domain
197 name supplied to these hosts:
198 .nf
199
200         option domain-name "test.isc.org";
201 .fi
202 .PP
203 Also, given the domain they're in, these are probably test machines.
204 If we wanted to test the DHCP leasing mechanism, we might set the
205 lease timeout somewhat shorter than the default:
206
207 .nf
208         max-lease-time 120;
209         default-lease-time 120;
210 .fi
211 .PP
212 You may have noticed that while some parameters start with the
213 \fIoption\fR keyword, some do not.   Parameters starting with the
214 \fIoption\fR keyword correspond to actual DHCP options, while
215 parameters that do not start with the option keyword either control
216 the behavior of the DHCP server (e.g., how long a lease dhcpd will
217 give out), or specify client parameters that are not optional in the
218 DHCP protocol (for example, server-name and filename).
219 .PP
220 In Figure 1, each host had \fIhost-specific parameters\fR.   These
221 could include such things as the \fIhostname\fR option, the name of a
222 file to upload (the \fIfilename\fR parameter) and the address of the
223 server from which to upload the file (the \fInext-server\fR
224 parameter).   In general, any parameter can appear anywhere that
225 parameters are allowed, and will be applied according to the scope in
226 which the parameter appears.
227 .PP
228 Imagine that you have a site with a lot of NCD X-Terminals.   These
229 terminals come in a variety of models, and you want to specify the
230 boot files for each model.   One way to do this would be to have host
231 declarations for each server and group them by model:
232 .nf
233
234 group {
235   filename "Xncd19r";
236   next-server ncd-booter;
237
238   host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; }
239   host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; }
240   host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }
241 }
242
243 group {
244   filename "Xncd19c";
245   next-server ncd-booter;
246
247   host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }
248   host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }
249 }
250
251 group {
252   filename "XncdHMX";
253   next-server ncd-booter;
254
255   host ncd1 { hardware ethernet 0:c0:c3:11:90:23; }
256   host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; }
257   host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }
258 }
259 .fi
260 .SH ADDRESS POOLS
261 .PP
262 The
263 .B pool
264 declaration can be used to specify a pool of addresses that will be
265 treated differently than another pool of addresses, even on the same
266 network segment or subnet.   For example, you may want to provide a
267 large set of addresses that can be assigned to DHCP clients that are
268 registered to your DHCP server, while providing a smaller set of
269 addresses, possibly with short lease times, that are available for
270 unknown clients.   If you have a firewall, you may be able to arrange
271 for addresses from one pool to be allowed access to the Internet,
272 while addresses in another pool are not, thus encouraging users to
273 register their DHCP clients.   To do this, you would set up a pair of
274 pool declarations:
275 .PP
276 .nf
277 subnet 10.0.0.0 netmask 255.255.255.0 {
278   option routers 10.0.0.254;
279
280   # Unknown clients get this pool.
281   pool {
282     option domain-name-servers bogus.example.com;
283     max-lease-time 300;
284     range 10.0.0.200 10.0.0.253;
285     allow unknown-clients;
286   }
287
288   # Known clients get this pool.
289   pool {
290     option domain-name-servers ns1.example.com, ns2.example.com;
291     max-lease-time 28800;
292     range 10.0.0.5 10.0.0.199;
293     deny unknown-clients;
294   }
295 }
296 .fi
297 .PP
298 It is also possible to set up entirely different subnets for known and
299 unknown clients - address pools exist at the level of shared networks,
300 so address ranges within pool declarations can be on different
301 subnets.
302 .PP
303 As you can see in the preceding example, pools can have permit lists
304 that control which clients are allowed access to the pool and which
305 aren't.  Each entry in a pool's permit list is introduced with the
306 .I allow
307 or \fIdeny\fR keyword.   If a pool has a permit list, then only those
308 clients that match specific entries on the permit list will be
309 eligible to be assigned addresses from the pool.   If a pool has a
310 deny list, then only those clients that do not match any entries on
311 the deny list will be eligible.    If both permit and deny lists exist
312 for a pool, then only clients that match the permit list and do not
313 match the deny list will be allowed access.
314 .SH DYNAMIC ADDRESS ALLOCATION
315 Address allocation is actually only done when a client is in the INIT
316 state and has sent a DHCPDISCOVER message.  If the client thinks it
317 has a valid lease and sends a DHCPREQUEST to initiate or renew that
318 lease, the server has only three choices - it can ignore the
319 DHCPREQUEST, send a DHCPNAK to tell the client it should stop using
320 the address, or send a DHCPACK, telling the client to go ahead and use
321 the address for a while.
322 .PP
323 If the server finds the address the client is requesting, and that
324 address is available to the client, the server will send a DHCPACK.
325 If the address is no longer available, or the client isn't permitted
326 to have it, the server will send a DHCPNAK.  If the server knows
327 nothing about the address, it will remain silent, unless the address
328 is incorrect for the network segment to which the client has been
329 attached and the server is authoritative for that network segment, in
330 which case the server will send a DHCPNAK even though it doesn't know
331 about the address.
332 .PP
333 There may be a host declaration matching the client's identification.
334 If that host declaration contains a fixed-address declaration that 
335 lists an IP address that is valid for the network segment to which the
336 client is connected.  In this case, the DHCP server will never do
337 dynamic address allocation.  In this case, the client is \fIrequired\fR
338 to take the address specified in the host declaration.   If the
339 client sends a DHCPREQUEST for some other address, the server will respond
340 with a DHCPNAK.
341 .PP
342 When the DHCP server allocates a new address for a client (remember,
343 this only happens if the client has sent a DHCPDISCOVER), it first
344 looks to see if the client already has a valid lease on an IP address,
345 or if there is an old IP address the client had before that hasn't yet
346 been reassigned.  In that case, the server will take that address and
347 check it to see if the client is still permitted to use it.  If the
348 client is no longer permitted to use it, the lease is freed if the
349 server thought it was still in use - the fact that the client has sent
350 a DHCPDISCOVER proves to the server that the client is no longer using
351 the lease.
352 .PP
353 If no existing lease is found, or if the client is forbidden to
354 receive the existing lease, then the server will look in the list of
355 address pools for the network segment to which the client is attached
356 for a lease that is not in use and that the client is permitted to
357 have.   It looks through each pool declaration in sequence (all
358 .I range
359 declarations that appear outside of pool declarations are grouped into
360 a single pool with no permit list).   If the permit list for the pool
361 allows the client to be allocated an address from that pool, the pool
362 is examined to see if there is an address available.   If so, then the
363 client is tentatively assigned that address.   Otherwise, the next
364 pool is tested.   If no addresses are found that can be assigned to
365 the client, no response is sent to the client.
366 .PP
367 If an address is found that the client is permitted to have, and that
368 has never been assigned to any client before, the address is
369 immediately allocated to the client.   If the address is available for
370 allocation but has been previously assigned to a different client, the
371 server will keep looking in hopes of finding an address that has never
372 before been assigned to a client.
373 .PP
374 The DHCP server generates the list of available IP addresses from a
375 hash table.   This means that the addresses are not sorted in any
376 particular order, and so it is not possible to predict the order in
377 which the DHCP server will allocate IP addresses.   Users of previous
378 versions of the ISC DHCP server may have become accustomed to the DHCP
379 server allocating IP addresses in ascending order, but this is no
380 longer possible, and there is no way to configure this behavior with
381 version 3 of the ISC DHCP server.
382 .SH IP ADDRESS CONFLICT PREVENTION
383 The DHCP server checks IP addresses to see if they are in use before
384 allocating them to clients.   It does this by sending an ICMP Echo
385 request message to the IP address being allocated.   If no ICMP Echo
386 reply is received within a second, the address is assumed to be free.
387 This is only done for leases that have been specified in range
388 statements, and only when the lease is thought by the DHCP server to
389 be free - i.e., the DHCP server or its failover peer has not listed
390 the lease as in use.
391 .PP
392 If a response is received to an ICMP Echo request, the DHCP server
393 assumes that there is a configuration error - the IP address is in use
394 by some host on the network that is not a DHCP client.   It marks the
395 address as abandoned, and will not assign it to clients.
396 .PP
397 If a DHCP client tries to get an IP address, but none are available,
398 but there are abandoned IP addresses, then the DHCP server will
399 attempt to reclaim an abandoned IP address.   It marks one IP address
400 as free, and then does the same ICMP Echo request check described
401 previously.   If there is no answer to the ICMP Echo request, the
402 address is assigned to the client.
403 .PP
404 The DHCP server does not cycle through abandoned IP addresses if the
405 first IP address it tries to reclaim is free.   Rather, when the next
406 DHCPDISCOVER comes in from the client, it will attempt a new
407 allocation using the same method described here, and will typically
408 try a new IP address.
409 .SH DHCP FAILOVER
410 This version of the ISC DHCP server supports the DHCP failover
411 protocol as documented in draft-ietf-dhc-failover-07.txt.   This is
412 not a final protocol document, and we have not done interoperability
413 testing with other vendors' implementations of this protocol, so you
414 must not assume that this implementation conforms to the standard.
415 If you wish to use the failover protocol, make sure that both failover
416 peers are running the same version of the ISC DHCP server.
417 .PP
418 The failover protocol allows two DHCP servers (and no more than two)
419 to share a common address pool.   Each server will have about half of
420 the available IP addresses in the pool at any given time for
421 allocation.   If one server fails, the other server will continue to
422 renew leases out of the pool, and will allocate new addresses out of
423 the roughly half of available addresses that it had when
424 communications with the other server were lost.
425 .PP
426 It is possible during a prolonged failure to tell the remaining server
427 that the other server is down, in which case the remaining server will
428 (over time) reclaim all the addresses the other server had available
429 for allocation, and begin to reuse them.   This is called putting the
430 server into the PARTNER-DOWN state.
431 .PP
432 You can put the server into the PARTNER-DOWN state either by using the
433 .B omshell (1)
434 command or by stopping the server, editing the last peer state
435 declaration in the lease file, and restarting the server.   If you use
436 this last method, be sure to leave the date and time of the start of
437 the state blank:
438 .PP
439 .nf
440 .B failover peer "\fIname\fB" state {
441 .B   my   state partner-down;
442 .B   peer state \fIstate\fB at \fIdate\fB;
443 .B }
444 .fi
445 .PP
446 When the other server comes back online, it should automatically
447 detect that it has been offline and request a complete update from the
448 server that was running in the PARTNER-DOWN state, and then both
449 servers will resume processing together.
450 .PP
451 It is possible to get into a dangerous situation: if you put one
452 server into the PARTNER-DOWN state, and then *that* server goes down,
453 and the other server comes back up, the other server will not know
454 that the first server was in the PARTNER-DOWN state, and may issue
455 addresses previously issued by the other server to different clients,
456 resulting in IP address conflicts.   Before putting a server into
457 PARTNER-DOWN state, therefore, make
458 .I sure
459 that the other server will not restart automatically.
460 .PP
461 The failover protocol defines a primary server role and a secondary
462 server role.   There are some differences in how primaries and
463 secondaries act, but most of the differences simply have to do with
464 providing a way for each peer to behave in the opposite way from the
465 other.   So one server must be configured as primary, and the other
466 must be configured as secondary, and it doesn't matter too much which
467 one is which.
468 .SH FAILOVER STARTUP
469 When a server starts that has not previously communicated with its
470 failover peer, it must establish communications with its failover peer
471 and synchronize with it before it can serve clients.   This can happen
472 either because you have just configured your DHCP servers to perform
473 failover for the first time, or because one of your failover servers
474 has failed catastrophically and lost its database.
475 .PP
476 The initial recovery process is designed to ensure that when one
477 failover peer loses its database and then resynchronizes, any leases
478 that the failed server gave out before it failed will be honored.
479 When the failed server starts up, it notices that it has no saved
480 failover state, and attempts to contact its peer.
481 .PP
482 When it has established contact, it asks the peer for a complete copy
483 its peer's lease database.  The peer then sends its complete database,
484 and sends a message indicating that it is done.  The failed server
485 then waits until MCLT has passed, and once MCLT has passed both
486 servers make the transition back into normal operation.  This waiting
487 period ensures that any leases the failed server may have given out
488 while out of contact with its partner will have expired.
489 .PP
490 While the failed server is recovering, its partner remains in the
491 partner-down state, which means that it is serving all clients.  The
492 failed server provides no service at all to DHCP clients until it has
493 made the transition into normal operation.
494 .PP
495 In the case where both servers detect that they have never before
496 communicated with their partner, they both come up in this recovery
497 state and follow the procedure we have just described.   In this case,
498 no service will be provided to DHCP clients until MCLT has expired.
499 .SH CONFIGURING FAILOVER
500 In order to configure failover, you need to write a peer declaration
501 that configures the failover protocol, and you need to write peer
502 references in each pool declaration for which you want to do
503 failover.   You do not have to do failover for all pools on a given
504 network segment.    You must not tell one server it's doing failover
505 on a particular address pool and tell the other it is not.   You must
506 not have any common address pools on which you are not doing
507 failover.  A pool declaration that utilizes failover would look like this:
508 .PP
509 .nf
510 pool {
511         failover peer "foo";
512         deny dynamic bootp clients;
513         \fIpool specific parameters\fR
514 };
515 .fi
516 .PP
517 Dynamic BOOTP leases are not compatible with failover, and, as such,
518 you need to disallow BOOTP in pools that you are using failover for.
519 .PP
520 The  server currently  does very  little  sanity checking,  so if  you
521 configure it wrong, it will just  fail in odd ways.  I would recommend
522 therefore that you either do  failover or don't do failover, but don't
523 do any mixed pools.  Also,  use the same master configuration file for
524 both  servers,  and  have  a  separate file  that  contains  the  peer
525 declaration and includes the master file.  This will help you to avoid
526 configuration  mismatches.  As our  implementation evolves,  this will
527 become  less of  a  problem.  A  basic  sample dhcpd.conf  file for  a
528 primary server might look like this:
529 .PP
530 .nf
531 failover peer "foo" {
532   primary;
533   address anthrax.rc.vix.com;
534   port 519;
535   peer address trantor.rc.vix.com;
536   peer port 520;
537   max-response-delay 60;
538   max-unacked-updates 10;
539   mclt 3600;
540   split 128;
541   load balance max seconds 3;
542 }
543
544 include "/etc/dhcpd.master";
545 .fi
546 .PP
547 The statements in the peer declaration are as follows:
548 .PP
549 The 
550 .I primary
551 and
552 .I secondary
553 statements
554 .RS 0.25i
555 .PP
556 [ \fBprimary\fR | \fBsecondary\fR ]\fB;\fR
557 .PP
558 This determines whether the server is primary or secondary, as
559 described earlier under DHCP FAILOVER.
560 .RE
561 .PP
562 The 
563 .I address
564 statement
565 .RS 0.25i
566 .PP
567 .B address \fIaddress\fR\fB;\fR
568 .PP
569 The \fBaddress\fR statement declares the IP address or DNS name on which the
570 server should listen for connections from its failover peer, and also the
571 value to use for the DHCP Failover Protocol server identifier.  Because this
572 value is used as an identifier, it may not be omitted.
573 .RE
574 .PP
575 The 
576 .I peer address
577 statement
578 .RS 0.25i
579 .PP
580 .B peer address \fIaddress\fR\fB;\fR
581 .PP
582 The \fBpeer address\fR statement declares the IP address or DNS name to
583 which the server should connect to reach its failover peer for failover
584 messages.
585 .RE
586 .PP
587 The 
588 .I port
589 statement
590 .RS 0.25i
591 .PP
592 .B port \fIport-number\fR\fB;\fR
593 .PP
594 The \fBport\fR statement declares the TCP port on which the server
595 should listen for connections from its failover peer.   This statement
596 may not currently be omitted, because the failover protocol does not
597 yet have a reserved TCP port number.
598 .RE
599 .PP
600 The 
601 .I peer port
602 statement
603 .RS 0.25i
604 .PP
605 .B peer port \fIport-number\fR\fB;\fR
606 .PP
607 The \fBpeer port\fR statement declares the TCP port to which the
608 server should connect to reach its failover peer for failover
609 messages.   This statement may not be omitted because the failover
610 protocol does not yet have a reserved TCP port number.   The port
611 number declared in the \fBpeer port\fR statement may be the same as
612 the port number declared in the \fBport\fR statement.
613 .RE
614 .PP
615 The 
616 .I max-response-delay
617 statement
618 .RS 0.25i
619 .PP
620 .B max-response-delay \fIseconds\fR\fB;\fR
621 .PP
622 The \fBmax-response-delay\fR statement tells the DHCP server how
623 many seconds may pass without receiving a message from its failover
624 peer before it assumes that connection has failed.   This number
625 should be small enough that a transient network failure that breaks
626 the connection will not result in the servers being out of
627 communication for a long time, but large enough that the server isn't
628 constantly making and breaking connections.   This parameter must be
629 specified.
630 .RE
631 .PP
632 The 
633 .I max-unacked-updates
634 statement
635 .RS 0.25i
636 .PP
637 .B max-unacked-updates \fIcount\fR\fB;\fR
638 .PP
639 The \fBmax-unacked-updates\fR statement tells the DHCP server how
640 many BNDUPD messages it can send before it receives a BNDACK
641 from the failover peer.   We don't have enough operational experience
642 to say what a good value for this is, but 10 seems to work.   This
643 parameter must be specified.
644 .RE
645 .PP
646 The 
647 .I mclt
648 statement
649 .RS 0.25i
650 .PP
651 .B mclt \fIseconds\fR\fB;\fR
652 .PP
653 The \fBmclt\fR statement defines the Maximum Client Lead Time.   It
654 must be specified on the primary, and may not be specified on the
655 secondary.   This is the length of time for which a lease may be
656 renewed by either failover peer without contacting the other.   The
657 longer you set this, the longer it will take for the running server to
658 recover IP addresses after moving into PARTNER-DOWN state.   The
659 shorter you set it, the more load your servers will experience when
660 they are not communicating.   A value of something like 3600 is
661 probably reasonable, but again bear in mind that we have no real
662 operational experience with this.
663 .RE
664 .PP
665 The 
666 .I split
667 statement
668 .RS 0.25i
669 .PP
670 .B split \fIindex\fR\fB;\fR
671 .PP
672 The split statement specifies the split between the primary and
673 secondary for the purposes of load balancing.   Whenever a client
674 makes a DHCP request, the DHCP server runs a hash on the client
675 identification.   If the hash comes out to less than the split value,
676 the primary answers.   If it comes out to equal to or more than the
677 split, the secondary answers.   The only meaningful value is 128, and can
678 only be configured on the primary.
679 .RE
680 .PP
681 The 
682 .I hba
683 statement
684 .RS 0.25i
685 .PP
686 .B hba \fIcolon-separated-hex-list\fB;\fR
687 .PP
688 The hba statement specifies the split between the primary and
689 secondary as a bitmap rather than a cutoff, which theoretically allows
690 for finer-grained control.   In practice, there is probably no need
691 for such fine-grained control, however.   An example hba statement:
692 .PP
693 .nf
694   hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:
695       00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;
696 .fi
697 .PP
698 This is equivalent to a \fBsplit 128;\fR statement.  You must only have
699 \fBsplit\fR or \fBhba\fR defined, never both.  For most cases, the
700 fine-grained control that \fBhba\fR offers isn't necessary, and \fBsplit\fR
701 should be used.  As such, the use of \fBhba\fR is deprecated.
702 .RE
703 .PP
704 The 
705 .I load balance max seconds
706 statement
707 .RS 0.25i
708 .PP
709 .B load balance max seconds \fIseconds\fR\fB;\fR
710 .PP
711 This statement allows you to configure a cutoff after which load
712 balancing is disabled.  The cutoff is based on the number of seconds
713 since the client sent its first DHCPDISCOVER or DHCPREQUEST message,
714 and only works with clients that correctly implement the \fIsecs\fR
715 field - fortunately most clients do.  We recommend setting this to
716 something like 3 or 5.  The effect of this is that if one of the
717 failover peers gets into a state where it is responding to failover
718 messages but not responding to some client requests, the other
719 failover peer will take over its client load automatically as the
720 clients retry.
721 .RE
722 .SH CLIENT CLASSING
723 Clients can be separated into classes, and treated differently
724 depending on what class they are in.   This separation can be done
725 either with a conditional statement, or with a match statement within
726 the class declaration.   It is possible to specify a limit on the
727 total number of clients within a particular class or subclass that may
728 hold leases at one time, and it is possible to specify automatic
729 subclassing based on the contents of the client packet.
730 .PP
731 To add clients to classes based on conditional evaluation, you can
732 specify a matching expression in the class statement:
733 .PP
734 .nf
735 class "ras-clients" {
736   match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
737 }
738 .fi
739 .PP
740 Note that whether you use matching expressions or add statements (or
741 both) to classify clients, you must always write a class declaration
742 for any class that you use.   If there will be no match statement and
743 no in-scope statements for a class, the declaration should look like
744 this:
745 .PP
746 .nf
747 class "ras-clients" {
748 }
749 .fi
750 .SH SUBCLASSES
751 .PP
752 In addition to classes, it is possible to declare subclasses.   A
753 subclass is a class with the same name as a regular class, but with a
754 specific submatch expression which is hashed for quick matching.
755 This is essentially a speed hack - the main difference between five
756 classes with match expressions and one class with five subclasses is
757 that it will be quicker to find the subclasses.   Subclasses work as
758 follows:
759 .PP
760 .nf
761 class "allocation-class-1" {
762   match pick-first-value (option dhcp-client-identifier, hardware);
763 }
764
765 class "allocation-class-2" {
766   match pick-first-value (option dhcp-client-identifier, hardware);
767 }
768
769 subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;
770 subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;
771 subclass "allocation-class-1" 1:0:0:c4:aa:29:44;
772
773 subnet 10.0.0.0 netmask 255.255.255.0 {
774   pool {
775     allow members of "allocation-class-1";
776     range 10.0.0.11 10.0.0.50;
777   }
778   pool {
779     allow members of "allocation-class-2";
780     range 10.0.0.51 10.0.0.100;
781   }
782 }
783 .fi
784 .PP
785 The data following the class name in the subclass declaration is a
786 constant value to use in matching the match expression for the class.
787 When class matching is done, the server will evaluate the match
788 expression and then look the result up in the hash table.   If it
789 finds a match, the client is considered a member of both the class and
790 the subclass.
791 .PP
792 Subclasses can be declared with or without scope.   In the above
793 example, the sole purpose of the subclass is to allow some clients
794 access to one address pool, while other clients are given access to
795 the other pool, so these subclasses are declared without scopes.   If
796 part of the purpose of the subclass were to define different parameter
797 values for some clients, you might want to declare some subclasses
798 with scopes.
799 .PP
800 In the above example, if you had a single client that needed some
801 configuration parameters, while most didn't, you might write the
802 following subclass declaration for that client:
803 .PP
804 .nf
805 subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {
806   option root-path "samsara:/var/diskless/alphapc";
807   filename "/tftpboot/netbsd.alphapc-diskless";
808 }
809 .fi
810 .PP
811 In this example, we've used subclassing as a way to control address
812 allocation on a per-client basis.  However, it's also possible to use
813 subclassing in ways that are not specific to clients - for example, to
814 use the value of the vendor-class-identifier option to determine what
815 values to send in the vendor-encapsulated-options option.  An example
816 of this is shown under the VENDOR ENCAPSULATED OPTIONS head in the
817 .B dhcp-options(5)
818 manual page.
819 .SH PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION
820 .PP
821 You may specify a limit to the number of clients in a class that can
822 be assigned leases.   The effect of this will be to make it difficult
823 for a new client in a class to get an address.   Once a class with
824 such a limit has reached its limit, the only way a new client in that
825 class can get a lease is for an existing client to relinquish its
826 lease, either by letting it expire, or by sending a DHCPRELEASE
827 packet.   Classes with lease limits are specified as follows:
828 .PP
829 .nf
830 class "limited-1" {
831   lease limit 4;
832 }
833 .fi
834 .PP
835 This will produce a class in which a maximum of four members may hold
836 a lease at one time.
837 .SH SPAWNING CLASSES
838 .PP
839 It is possible to declare a
840 .I spawning class\fR.
841 A spawning class is a class that automatically produces subclasses
842 based on what the client sends.   The reason that spawning classes
843 were created was to make it possible to create lease-limited classes
844 on the fly.   The envisioned application is a cable-modem environment
845 where the ISP wishes to provide clients at a particular site with more
846 than one IP address, but does not wish to provide such clients with
847 their own subnet, nor give them an unlimited number of IP addresses
848 from the network segment to which they are connected.
849 .PP
850 Many cable modem head-end systems can be configured to add a Relay
851 Agent Information option to DHCP packets when relaying them to the
852 DHCP server.   These systems typically add a circuit ID or remote ID
853 option that uniquely identifies the customer site.   To take advantage
854 of this, you can write a class declaration as follows:
855 .PP
856 .nf
857 class "customer" {
858   spawn with option agent.circuit-id;
859   lease limit 4;
860 }
861 .fi
862 .PP
863 Now whenever a request comes in from a customer site, the circuit ID
864 option will be checked against the class's hash table.   If a subclass
865 is found that matches the circuit ID, the client will be classified in
866 that subclass and treated accordingly.   If no subclass is found
867 matching the circuit ID, a new one will be created and logged in the
868 .B dhcpd.leases
869 file, and the client will be classified in this new class.   Once the
870 client has been classified, it will be treated according to the rules
871 of the class, including, in this case, being subject to the per-site
872 limit of four leases.
873 .PP
874 The use of the subclass spawning mechanism is not restricted to relay
875 agent options - this particular example is given only because it is a
876 fairly straightforward one.
877 .SH COMBINING MATCH, MATCH IF AND SPAWN WITH
878 .PP
879 In some cases, it may be useful to use one expression to assign a
880 client to a particular class, and a second expression to put it into a
881 subclass of that class.   This can be done by combining the \fBmatch
882 if\fR and \fBspawn with\fR statements, or the \fBmatch if\fR and
883 \fBmatch\fR statements.   For example:
884 .PP
885 .nf
886 class "jr-cable-modems" {
887   match if option dhcp-vendor-identifier = "jrcm";
888   spawn with option agent.circuit-id;
889   lease limit 4;
890 }
891
892 class "dv-dsl-modems" {
893   match if opton dhcp-vendor-identifier = "dvdsl";
894   spawn with option agent.circuit-id;
895   lease limit 16;
896 }
897 .fi
898 .PP
899 This allows you to have two classes that both have the same \fBspawn
900 with\fR expression without getting the clients in the two classes
901 confused with each other.
902 .SH DYNAMIC DNS UPDATES
903 .PP
904 The DHCP server has the ability to dynamically update the Domain Name
905 System.  Within the configuration files, you can define how you want
906 the Domain Name System to be updated.  These updates are RFC 2136
907 compliant so any DNS server supporting RFC 2136 should be able to
908 accept updates from the DHCP server.
909 .PP
910 Two DNS update schemes are currently implemented, and another is
911 planned.   The two that are currently available are the ad-hoc DNS
912 update mode and the interim DHCP-DNS interaction draft update mode.
913 If and when the DHCP-DNS interaction draft and the DHCID draft make it
914 through the IETF standards process, there will be a third mode, which
915 will be the standard DNS update method.   The DHCP server must be
916 configured to use one of the two currently-supported methods, or not
917 to do dns updates.   This can be done with the
918 .I ddns-update-style
919 configuration parameter.
920 .SH THE AD-HOC DNS UPDATE SCHEME
921 The ad-hoc Dynamic DNS update scheme is
922 .B now deprecated
923 and
924 .B
925 does not work.
926 In future releases of the ISC DHCP server, this scheme will not likely be
927 available.  The interim scheme works, allows for failover, and should now be
928 used.  The following description is left here for informational purposes
929 only.
930 .PP
931 The ad-hoc Dynamic DNS update scheme implemented in this version of
932 the ISC DHCP server is a prototype design, which does not
933 have much to do with the standard update method that is being
934 standardized in the IETF DHC working group, but rather implements some
935 very basic, yet useful, update capabilities.   This mode
936 .B does not work
937 with the
938 .I failover protocol
939 because it does not account for the possibility of two different DHCP
940 servers updating the same set of DNS records.
941 .PP
942 For the ad-hoc DNS update method, the client's FQDN is derived in two
943 parts.   First, the hostname is determined.   Then, the domain name is
944 determined, and appended to the hostname.
945 .PP
946 The DHCP server determines the client's hostname by first looking for
947 a \fIddns-hostname\fR configuration option, and using that if it is
948 present.  If no such option is present, the server looks for a
949 valid hostname in the FQDN option sent by the client.  If one is
950 found, it is used; otherwise, if the client sent a host-name option,
951 that is used.  Otherwise, if there is a host declaration that applies
952 to the client, the name from that declaration will be used.  If none
953 of these applies, the server will not have a hostname for the client,
954 and will not be able to do a DNS update.
955 .PP
956 The domain name is determined based strictly on the server
957 configuration, not on what the client sends.   First, if there is a 
958 .I ddns-domainname
959 configuration option, it is used.   Second, if there is a
960 \fIdomain-name\fR option configured, that is used.  Otherwise, the
961 server will not do the DNS update.
962 .PP
963 The client's fully-qualified domain name, derived as we have
964 described, is used as the name on which an "A" record will be stored.
965 The A record will contain the IP address that the client was assigned
966 in its lease.   If there is already an A record with the same name in
967 the DNS server, no update of either the A or PTR records will occur -
968 this prevents a client from claiming that its hostname is the name of
969 some network server.   For example, if you have a fileserver called
970 "fs.sneedville.edu", and the client claims its hostname is "fs", no
971 DNS update will be done for that client, and an error message will be
972 logged.
973 .PP
974 If the A record update succeeds, a PTR record update for the assigned
975 IP address will be done, pointing to the A record.   This update is
976 unconditional - it will be done even if another PTR record of the same
977 name exists.   Since the IP address has been assigned to the DHCP
978 server, this should be safe.
979 .PP
980 Please note that the current implementation assumes clients only have
981 a single network interface.   A client with two network interfaces
982 will see unpredictable behavior.   This is considered a bug, and will
983 be fixed in a later release.   It may be helpful to enable the
984 .I one-lease-per-client
985 parameter so that roaming clients do not trigger this same behavior.
986 .PP
987 The DHCP protocol normally involves a four-packet exchange - first the
988 client sends a DHCPDISCOVER message, then the server sends a
989 DHCPOFFER, then the client sends a DHCPREQUEST, then the server sends
990 a DHCPACK.   In the current version of the server, the server will do
991 a DNS update after it has received the DHCPREQUEST, and before it has
992 sent the DHCPACK.   It only sends the DNS update if it has not sent
993 one for the client's address before, in order to minimize the impact
994 on the DHCP server.
995 .PP
996 When the client's lease expires, the DHCP server (if it is operating
997 at the time, or when next it operates) will remove the client's A and
998 PTR records from the DNS database.   If the client releases its lease
999 by sending a DHCPRELEASE message, the server will likewise remove the
1000 A and PTR records.
1001 .SH THE INTERIM DNS UPDATE SCHEME
1002 The interim DNS update scheme operates mostly according to several
1003 drafts that are being considered by the IETF and are expected to
1004 become standards, but are not yet standards, and may not be
1005 standardized exactly as currently proposed.   These are:
1006 .PP
1007 .nf
1008 .ce 3
1009 draft-ietf-dhc-ddns-resolution-??.txt
1010 draft-ietf-dhc-fqdn-option-??.txt
1011 draft-ietf-dnsext-dhcid-rr-??.txt
1012 .fi
1013 .PP
1014 Because our implementation is slightly different than the standard, we
1015 will briefly document the operation of this update style here.
1016 .PP
1017 The first point to understand about this style of DNS update is that
1018 unlike the ad-hoc style, the DHCP server does not necessarily
1019 always update both the A and the PTR records.   The FQDN option
1020 includes a flag which, when sent by the client, indicates that the
1021 client wishes to update its own A record.   In that case, the server
1022 can be configured either to honor the client's intentions or ignore
1023 them.   This is done with the statement \fIallow client-updates;\fR or
1024 the statement \fIignore client-updates;\fR.   By default, client
1025 updates are allowed.
1026 .PP
1027 If the server is configured to allow client updates, then if the
1028 client sends a fully-qualified domain name in the FQDN option, the
1029 server will use that name the client sent in the FQDN option to update
1030 the PTR record.   For example, let us say that the client is a visitor
1031 from the "radish.org" domain, whose hostname is "jschmoe".   The
1032 server is for the "example.org" domain.   The DHCP client indicates in
1033 the FQDN option that its FQDN is "jschmoe.radish.org.".   It also
1034 indicates that it wants to update its own A record.   The DHCP server
1035 therefore does not attempt to set up an A record for the client, but
1036 does set up a PTR record for the IP address that it assigns the
1037 client, pointing at jschmoe.radish.org.   Once the DHCP client has an
1038 IP address, it can update its own A record, assuming that the
1039 "radish.org" DNS server will allow it to do so.
1040 .PP
1041 If the server is configured not to allow client updates, or if the
1042 client doesn't want to do its own update, the server will simply
1043 choose a name for the client, possibly using the hostname supplied by
1044 the client ("jschmoe" in the previous example).   It will use its own
1045 domain name for the client, just as in the ad-hoc update scheme.
1046 It will then update both the A and PTR record, using the name that it
1047 chose for the client.   If the client sends a fully-qualified domain
1048 name in the fqdn option, the server uses only the leftmost part of the
1049 domain name - in the example above, "jschmoe" instead of
1050 "jschmoe.radish.org".
1051 .PP
1052 The other difference between the ad-hoc scheme and the interim
1053 scheme is that with the interim scheme, a method is used that
1054 allows more than one DHCP server to update the DNS database without
1055 accidentally deleting A records that shouldn't be deleted nor failing
1056 to add A records that should be added.   The scheme works as follows:
1057 .PP
1058 When the DHCP server issues a client a new lease, it creates a text
1059 string that is an MD5 hash over the DHCP client's identification (see
1060 draft-ietf-dnsext-dhcid-rr-??.txt for details).   The update adds an A
1061 record with the name the server chose and a TXT record containing the
1062 hashed identifier string (hashid).   If this update succeeds, the
1063 server is done.
1064 .PP
1065 If the update fails because the A record already exists, then the DHCP
1066 server attempts to add the A record with the prerequisite that there
1067 must be a TXT record in the same name as the new A record, and that
1068 TXT record's contents must be equal to hashid.   If this update
1069 succeeds, then the client has its A record and PTR record.   If it
1070 fails, then the name the client has been assigned (or requested) is in
1071 use, and can't be used by the client.   At this point the DHCP server
1072 gives up trying to do a DNS update for the client until the client
1073 chooses a new name.
1074 .PP
1075 The interim DNS update scheme is called interim for two reasons.
1076 First, it does not quite follow the drafts.   The current versions of
1077 the drafts call for a new DHCID RRtype, but this is not yet
1078 available.   The interim DNS update scheme uses a TXT record
1079 instead.   Also, the existing ddns-resolution draft calls for the DHCP
1080 server to put a DHCID RR on the PTR record, but the \fIinterim\fR
1081 update method does not do this.   It is our position that this is not
1082 useful, and we are working with the author in hopes of removing it
1083 from the next version of the draft, or better understanding why it is
1084 considered useful.
1085 .PP
1086 In addition to these differences, the server also does not update very
1087 aggressively.  Because each DNS update involves a round trip to the
1088 DNS server, there is a cost associated with doing updates even if they
1089 do not actually modify the DNS database.   So the DHCP server tracks
1090 whether or not it has updated the record in the past (this information
1091 is stored on the lease) and does not attempt to update records that it
1092 thinks it has already updated.
1093 .PP
1094 This can lead to cases where the DHCP server adds a record, and then
1095 the record is deleted through some other mechanism, but the server
1096 never again updates the DNS because it thinks the data is already
1097 there.   In this case the data can be removed from the lease through
1098 operator intervention, and once this has been done, the DNS will be
1099 updated the next time the client renews.
1100 .SH DYNAMIC DNS UPDATE SECURITY
1101 .PP
1102 When you set your DNS server up to allow updates from the DHCP server,
1103 you may be exposing it to unauthorized updates.  To avoid this, you
1104 should use TSIG signatures - a method of cryptographically signing
1105 updates using a shared secret key.   As long as you protect the
1106 secrecy of this key, your updates should also be secure.   Note,
1107 however, that the DHCP protocol itself provides no security, and that
1108 clients can therefore provide information to the DHCP server which the
1109 DHCP server will then use in its updates, with the constraints
1110 described previously.
1111 .PP
1112 The DNS server must be configured to allow updates for any zone that
1113 the DHCP server will be updating.  For example, let us say that
1114 clients in the sneedville.edu domain will be assigned addresses on the
1115 10.10.17.0/24 subnet.  In that case, you will need a key declaration
1116 for the TSIG key you will be using, and also two zone declarations -
1117 one for the zone containing A records that will be updates and one for
1118 the zone containing PTR records - for ISC BIND, something like this:
1119 .PP
1120 .nf
1121 key DHCP_UPDATER {
1122   algorithm HMAC-MD5.SIG-ALG.REG.INT;
1123   secret pRP5FapFoJ95JEL06sv4PQ==;
1124 };
1125
1126 zone "example.org" {
1127         type master;
1128         file "example.org.db";
1129         allow-update { key DHCP_UPDATER; };
1130 };
1131
1132 zone "17.10.10.in-addr.arpa" {
1133         type master;
1134         file "10.10.17.db";
1135         allow-update { key DHCP_UPDATER; };
1136 };
1137 .fi
1138 .PP
1139 You will also have to configure your DHCP server to do updates to
1140 these zones.   To do so, you need to add something like this to your
1141 dhcpd.conf file:
1142 .PP
1143 .nf
1144 key DHCP_UPDATER {
1145   algorithm HMAC-MD5.SIG-ALG.REG.INT;
1146   secret pRP5FapFoJ95JEL06sv4PQ==;
1147 };
1148
1149 zone EXAMPLE.ORG. {
1150   primary 127.0.0.1;
1151   key DHCP_UPDATER;
1152 }
1153
1154 zone 17.127.10.in-addr.arpa. {
1155   primary 127.0.0.1;
1156   key DHCP_UPDATER;
1157 }
1158 .fi
1159 .PP
1160 The \fIprimary\fR statement specifies the IP address of the name
1161 server whose zone information is to be updated.
1162 .PP
1163 Note that the zone declarations have to correspond to authority
1164 records in your name server - in the above example, there must be an
1165 SOA record for "example.org." and for "17.10.10.in-addr.arpa.".   For
1166 example, if there were a subdomain "foo.example.org" with no separate
1167 SOA, you could not write a zone declaration for "foo.example.org."  
1168 Also keep in mind that zone names in your DHCP configuration should end in a
1169 "."; this is the preferred syntax.  If you do not end your zone name in a
1170 ".", the DHCP server will figure it out.  Also note that in the DHCP
1171 configuration, zone names are not encapsulated in quotes where there are in
1172 the DNS configuration.
1173 .PP
1174 You should choose your own secret key, of course.  The ISC BIND 8 and
1175 9 distributions come with a program for generating secret keys called
1176 dnssec-keygen.  The version that comes with BIND 9 is likely to produce a
1177 substantially more random key, so we recommend you use that one even
1178 if you are not using BIND 9 as your DNS server.  If you are using BIND 9's
1179 dnssec-keygen, the above key would be created as follows:
1180 .PP
1181 .nf
1182         dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
1183 .fi
1184 .PP
1185 If you are using the BIND 8 dnskeygen program, the following command will
1186 generate a key as seen above:
1187 .PP
1188 .nf
1189         dnskeygen -H 128 -u -c -n DHCP_UPDATER
1190 .fi
1191 .PP
1192 You may wish to enable logging of DNS updates on your DNS server.
1193 To do so, you might write a logging statement like the following:
1194 .PP
1195 .nf
1196 logging {
1197         channel update_debug {
1198                 file "/var/log/update-debug.log";
1199                 severity        debug 3;
1200                 print-category  yes;
1201                 print-severity  yes;
1202                 print-time      yes;
1203         };
1204         channel security_info   {
1205                 file    "/var/log/named-auth.info";
1206                 severity        info;
1207                 print-category  yes;
1208                 print-severity  yes;
1209                 print-time      yes;
1210         };
1211
1212         category update { update_debug; };
1213         category security { security_info; };
1214 };
1215 .fi
1216 .PP
1217 You must create the /var/log/named-auth.info and
1218 /var/log/update-debug.log files before starting the name server.   For
1219 more information on configuring ISC BIND, consult the documentation
1220 that accompanies it.
1221 .SH REFERENCE: EVENTS
1222 .PP
1223 There are three kinds of events that can happen regarding a lease, and
1224 it is possible to declare statements that occur when any of these
1225 events happen.   These events are the commit event, when the server
1226 has made a commitment of a certain lease to a client, the release
1227 event, when the client has released the server from its commitment,
1228 and the expiry event, when the commitment expires.
1229 .PP
1230 To declare a set of statements to execute when an event happens, you
1231 must use the \fBon\fR statement, followed by the name of the event,
1232 followed by a series of statements to execute when the event happens,
1233 enclosed in braces.   Events are used to implement DNS
1234 updates, so you should not define your own event handlers if you are
1235 using the built-in DNS update mechanism.
1236 .PP
1237 The built-in version of the DNS update mechanism is in a text
1238 string towards the top of server/dhcpd.c.   If you want to use events
1239 for things other than DNS updates, and you also want DNS updates, you
1240 will have to start out by copying this code into your dhcpd.conf file
1241 and modifying it.
1242 .SH REFERENCE: DECLARATIONS
1243 .PP
1244 .B The
1245 .I include
1246 .B statement
1247 .PP
1248 .nf
1249  \fBinclude\fR \fI"filename"\fR\fB;\fR
1250 .fi
1251 .PP
1252 The \fIinclude\fR statement is used to read in a named file, and process
1253 the contents of that file as though it were entered in place of the
1254 include statement.
1255 .PP
1256 .B The 
1257 .I shared-network
1258 .B statement
1259 .PP
1260 .nf
1261  \fBshared-network\fR \fIname\fR \fB{\fR
1262    [ \fIparameters\fR ]
1263    [ \fIdeclarations\fR ]
1264  \fB}\fR
1265 .fi
1266 .PP
1267 The \fIshared-network\fR statement is used to inform the DHCP server
1268 that some IP subnets actually share the same physical network.  Any
1269 subnets in a shared network should be declared within a
1270 \fIshared-network\fR statement.  Parameters specified in the
1271 \fIshared-network\fR statement will be used when booting clients on
1272 those subnets unless parameters provided at the subnet or host level
1273 override them.  If any subnet in a shared network has addresses
1274 available for dynamic allocation, those addresses are collected into a
1275 common pool for that shared network and assigned to clients as needed.
1276 There is no way to distinguish on which subnet of a shared network a
1277 client should boot.
1278 .PP
1279 .I Name
1280 should be the name of the shared network.   This name is used when
1281 printing debugging messages, so it should be descriptive for the
1282 shared network.   The name may have the syntax of a valid domain name
1283 (although it will never be used as such), or it may be any arbitrary
1284 name, enclosed in quotes.
1285 .PP
1286 .B The 
1287 .I subnet
1288 .B statement
1289 .PP
1290 .nf
1291  \fBsubnet\fR \fIsubnet-number\fR \fBnetmask\fR \fInetmask\fR \fB{\fR
1292    [ \fIparameters\fR ]
1293    [ \fIdeclarations\fR ]
1294  \fB}\fR
1295 .fi
1296 .PP
1297 The \fIsubnet\fR statement is used to provide dhcpd with enough
1298 information to tell whether or not an IP address is on that subnet.
1299 It may also be used to provide subnet-specific parameters and to
1300 specify what addresses may be dynamically allocated to clients booting
1301 on that subnet.   Such addresses are specified using the \fIrange\fR
1302 declaration.
1303 .PP
1304 The
1305 .I subnet-number
1306 should be an IP address or domain name which resolves to the subnet
1307 number of the subnet being described.   The 
1308 .I netmask
1309 should be an IP address or domain name which resolves to the subnet mask
1310 of the subnet being described.   The subnet number, together with the
1311 netmask, are sufficient to determine whether any given IP address is
1312 on the specified subnet.
1313 .PP
1314 Although a netmask must be given with every subnet declaration, it is
1315 recommended that if there is any variance in subnet masks at a site, a
1316 subnet-mask option statement be used in each subnet declaration to set
1317 the desired subnet mask, since any subnet-mask option statement will
1318 override the subnet mask declared in the subnet statement.
1319 .PP
1320 .B The
1321 .I range
1322 .B statement
1323 .PP
1324 .nf
1325 .B range\fR [ \fBdynamic-bootp\fR ] \fIlow-address\fR [ \fIhigh-address\fR]\fB;\fR
1326 .fi
1327 .PP
1328 For any subnet on which addresses will be assigned dynamically, there
1329 must be at least one \fIrange\fR statement.   The range statement
1330 gives the lowest and highest IP addresses in a range.   All IP
1331 addresses in the range should be in the subnet in which the
1332 \fIrange\fR statement is declared.   The \fIdynamic-bootp\fR flag may
1333 be specified if addresses in the specified range may be dynamically
1334 assigned to BOOTP clients as well as DHCP clients.   When specifying a
1335 single address, \fIhigh-address\fR can be omitted.
1336 .PP
1337 .B The
1338 .I host
1339 .B statement
1340 .PP
1341 .nf
1342  \fBhost\fR \fIhostname\fR {
1343    [ \fIparameters\fR ]
1344    [ \fIdeclarations\fR ]
1345  \fB}\fR
1346 .fi
1347 .PP
1348 The
1349 .B host
1350 declaration provides a scope in which to provide configuration information about
1351 a specific client, and also provides a way to assign a client a fixed address.
1352 The host declaration provides a way for the DHCP server to identify a DHCP or
1353 BOOTP client, and also a way to assign the client a static IP address.
1354 .PP
1355 If it is desirable to be able to boot a DHCP or BOOTP
1356 client on more than one subnet with fixed addresses, more than one
1357 address may be specified in the
1358 .I fixed-address
1359 declaration, or more than one
1360 .B host
1361 statement may be specified.
1362 .PP
1363 If client-specific boot parameters must change based on the network
1364 to which the client is attached, then multiple 
1365 .B host
1366 declaration should
1367 be used.
1368 .PP
1369 If a client is to be booted using a fixed address if it's
1370 possible, but should be allocated a dynamic address otherwise, then a
1371 .B host
1372 declaration must be specified without a
1373 .B fixed-address
1374 declaration.
1375 .I hostname
1376 should be a name identifying the host.  If a \fIhostname\fR option is
1377 not specified for the host, \fIhostname\fR is used.
1378 .PP
1379 \fIHost\fR declarations are matched to actual DHCP or BOOTP clients
1380 by matching the \fRdhcp-client-identifier\fR option specified in the
1381 \fIhost\fR declaration to the one supplied by the client, or, if the
1382 \fIhost\fR declaration or the client does not provide a
1383 \fRdhcp-client-identifier\fR option, by matching the \fIhardware\fR
1384 parameter in the \fIhost\fR declaration to the network hardware
1385 address supplied by the client.   BOOTP clients do not normally
1386 provide a \fIdhcp-client-identifier\fR, so the hardware address must
1387 be used for all clients that may boot using the BOOTP protocol.
1388 .PP
1389 Please be aware that
1390 .B only
1391 the \fIdhcp-client-identifier\fR option and the hardware address can be
1392 used to match a host declaration.   For example, it is not possible to match
1393 a host declaration to a \fIhost-name\fR option.   This is because the
1394 host-name option cannot be guaranteed to be unique for any given client,
1395 whereas both the hardware address and \fIdhcp-client-identifier\fR option
1396 are at least theoretically guaranteed to be unique to a given client.
1397 .PP
1398 .B The
1399 .I group
1400 .B statement
1401 .PP
1402 .nf
1403  \fBgroup\fR {
1404    [ \fIparameters\fR ]
1405    [ \fIdeclarations\fR ]
1406  \fB}\fR
1407 .fi
1408 .PP
1409 The group statement is used simply to apply one or more parameters to
1410 a group of declarations.   It can be used to group hosts, shared
1411 networks, subnets, or even other groups.
1412 .SH REFERENCE: ALLOW AND DENY
1413 The
1414 .I allow
1415 and
1416 .I deny
1417 statements can be used to control the response of the DHCP server to
1418 various sorts of requests.  The allow and deny keywords actually have
1419 different meanings depending on the context.  In a pool context, these
1420 keywords can be used to set up access lists for address allocation
1421 pools.  In other contexts, the keywords simply control general server
1422 behavior with respect to clients based on scope.   In a non-pool
1423 context, the
1424 .I ignore
1425 keyword can be used in place of the
1426 .I deny
1427 keyword to prevent logging of denied requests.
1428 .PP
1429 .SH ALLOW DENY AND IGNORE IN SCOPE
1430 The following usages of allow and deny will work in any scope,
1431 although it is not recommended that they be used in pool
1432 declarations.
1433 .PP
1434 .B The
1435 .I unknown-clients
1436 .B keyword
1437 .PP
1438  \fBallow unknown-clients;\fR
1439  \fBdeny unknown-clients;\fR
1440  \fBignore unknown-clients;\fR
1441 .PP
1442 The \fBunknown-clients\fR flag is used to tell dhcpd whether
1443 or not to dynamically assign addresses to unknown clients.   Dynamic
1444 address assignment to unknown clients is \fBallow\fRed by default.
1445 An unknown client is simply a client that has no host declaration.
1446 .PP
1447 The use of this option is now \fIdeprecated\fR.  If you are trying to
1448 restrict access on your network to known clients, you should use \fBdeny
1449 unknown-clients;\fR inside of your address pool, as described under the
1450 heading ALLOW AND DENY WITHIN POOL DECLARAIONS.
1451 .PP
1452 .B The
1453 .I bootp
1454 .B keyword
1455 .PP
1456  \fBallow bootp;\fR
1457  \fBdeny bootp;\fR
1458  \fBignore bootp;\fR
1459 .PP
1460 The \fBbootp\fR flag is used to tell dhcpd whether
1461 or not to respond to bootp queries.  Bootp queries are \fBallow\fRed
1462 by default.
1463 .PP
1464 This option does not satisfy the requirement of failover peers for denying
1465 dynamic bootp clients.  The \fBdeny dynamic bootp clients;\fR option should
1466 be used instead. See the ALLOW AND DENY WITHIN POOL DECLARATIONS section
1467 of this man page for more details.
1468 .PP
1469 .B The
1470 .I booting
1471 .B keyword
1472 .PP
1473  \fBallow booting;\fR
1474  \fBdeny booting;\fR
1475  \fBignore booting;\fR
1476 .PP
1477 The \fBbooting\fR flag is used to tell dhcpd whether or not to respond
1478 to queries from a particular client.  This keyword only has meaning
1479 when it appears in a host declaration.   By default, booting is
1480 \fBallow\fRed, but if it is disabled for a particular client, then
1481 that client will not be able to get an address from the DHCP server.
1482 .PP
1483 .B The
1484 .I duplicates
1485 .B keyword
1486 .PP
1487  \fBallow duplicates;\fR
1488  \fBdeny duplicates;\fR
1489 .PP
1490 Host declarations can match client messages based on the DHCP Client
1491 Identifer option or based on the client's network hardware type and
1492 MAC address.   If the MAC address is used, the host declaration will
1493 match any client with that MAC address - even clients with different
1494 client identifiers.   This doesn't normally happen, but is possible
1495 when one computer has more than one operating system installed on it -
1496 for example, Microsoft Windows and NetBSD or Linux.
1497 .PP
1498 The \fBduplicates\fR flag tells the DHCP server that if a request is
1499 received from a client that matches the MAC address of a host
1500 declaration, any other leases matching that MAC address should be
1501 discarded by the server, even if the UID is not the same.   This is a
1502 violation of the DHCP protocol, but can prevent clients whose client
1503 identifiers change regularly from holding many leases at the same time.
1504 By default, duplicates are \fBallow\fRed.
1505 .PP
1506 .B The
1507 .I declines
1508 .B keyword
1509 .PP
1510  \fBallow declines;\fR
1511  \fBdeny declines;\fR
1512  \fBignore declines;\fR
1513 .PP
1514 The DHCPDECLINE message is used by DHCP clients to indicate that the
1515 lease the server has offered is not valid.   When the server receives
1516 a DHCPDECLINE for a particular address, it normally abandons that
1517 address, assuming that some unauthorized system is using it.
1518 Unfortunately, a malicious or buggy client can, using DHCPDECLINE
1519 messages, completely exhaust the DHCP server's allocation pool.   The
1520 server will reclaim these leases, but while the client is running
1521 through the pool, it may cause serious thrashing in the DNS, and it
1522 will also cause the DHCP server to forget old DHCP client address
1523 allocations.
1524 .PP
1525 The \fBdeclines\fR flag tells the DHCP server whether or not to honor
1526 DHCPDECLINE messages.   If it is set to \fBdeny\fR or \fBignore\fR in
1527 a particular scope, the DHCP server will not respond to DHCPDECLINE
1528 messages.
1529 .PP
1530 .B The
1531 .I client-updates
1532 .B keyword
1533 .PP
1534  \fBallow client-updates;\fR
1535  \fBdeny client-updates;\fR
1536 .PP
1537 The \fBclient-updates\fR flag tells the DHCP server whether or not to
1538 honor the client's intention to do its own update of its A record.
1539 This is only relevant when doing \fIinterim\fR DNS updates.   See the
1540 documentation under the heading THE INTERIM DNS UPDATE SCHEME for
1541 details.
1542 .SH ALLOW AND DENY WITHIN POOL DECLARATIONS
1543 .PP
1544 The uses of the allow and deny keywords shown in the previous section
1545 work pretty much the same way whether the client is sending a
1546 DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated
1547 to the client (either the old address it's requesting, or a new
1548 address) and then that address will be tested to see if it's okay to
1549 let the client have it.   If the client requested it, and it's not
1550 okay, the server will send a DHCPNAK message.   Otherwise, the server
1551 will simply not respond to the client.   If it is okay to give the
1552 address to the client, the server will send a DHCPACK message.
1553 .PP
1554 The primary motivation behind pool declarations is to have address
1555 allocation pools whose allocation policies are different.   A client
1556 may be denied access to one pool, but allowed access to another pool
1557 on the same network segment.   In order for this to work, access
1558 control has to be done during address allocation, not after address
1559 allocation is done.
1560 .PP
1561 When a DHCPREQUEST message is processed, address allocation simply
1562 consists of looking up the address the client is requesting and seeing
1563 if it's still available for the client.  If it is, then the DHCP
1564 server checks both the address pool permit lists and the relevant
1565 in-scope allow and deny statements to see if it's okay to give the
1566 lease to the client.  In the case of a DHCPDISCOVER message, the
1567 allocation process is done as described previously in the ADDRESS
1568 ALLOCATION section.
1569 .PP
1570 When declaring permit lists for address allocation pools, the
1571 following syntaxes are recognized following the allow or deny keywords:
1572 .PP
1573  \fBknown-clients;\fR
1574 .PP
1575 If specified, this statement either allows or prevents allocation from
1576 this pool to any client that has a host declaration (i.e., is known).
1577 A client is known if it has a host declaration in \fIany\fR scope, not
1578 just the current scope.
1579 .PP
1580  \fBunknown-clients;\fR
1581 .PP
1582 If specified, this statement either allows or prevents allocation from
1583 this pool to any client that has no host declaration (i.e., is not
1584 known).
1585 .PP
1586  \fBmembers of "\fRclass\fB";\fR
1587 .PP
1588 If specified, this statement either allows or prevents allocation from
1589 this pool to any client that is a member of the named class.
1590 .PP
1591  \fBdynamic bootp clients;\fR
1592 .PP
1593 If specified, this statement either allows or prevents allocation from
1594 this pool to any bootp client.
1595 .PP
1596  \fBauthenticated clients;\fR
1597 .PP
1598 If specified, this statement either allows or prevents allocation from
1599 this pool to any client that has been authenticated using the DHCP
1600 authentication protocol.   This is not yet supported.
1601 .PP
1602  \fBunauthenticated clients;\fR
1603 .PP
1604 If specified, this statement either allows or prevents allocation from
1605 this pool to any client that has not been authenticated using the DHCP
1606 authentication protocol.   This is not yet supported.
1607 .PP
1608  \fBall clients;\fR
1609 .PP
1610 If specified, this statement either allows or prevents allocation from
1611 this pool to all clients.   This can be used when you want to write a
1612 pool declaration for some reason, but hold it in reserve, or when you
1613 want to renumber your network quickly, and thus want the server to
1614 force all clients that have been allocated addresses from this pool to
1615 obtain new addresses immediately when they next renew.
1616 .SH REFERENCE: PARAMETERS
1617 The
1618 .I always-broadcast
1619 statement
1620 .RS 0.25i
1621 .PP
1622 .B always-broadcast \fIflag\fR\fB;\fR
1623 .PP
1624 The DHCP and BOOTP protocols both require DHCP and BOOTP clients to
1625 set the broadcast bit in the flags field of the BOOTP message header.
1626 Unfortunately, some DHCP and BOOTP clients do not do this, and
1627 therefore may not receive responses from the DHCP server.   The DHCP
1628 server can be made to always broadcast its responses to clients by
1629 setting this flag to 'on' for the relevant scope; relevant scopes would be
1630 inside a conditional statement, as a parameter for a class, or as a parameter
1631 for a host declaration.   To avoid creating excess broadcast traffic on your
1632 network, we recommend that you restrict the use of this option to as few
1633 clients as possible.   For example, the Microsoft DHCP client is known not
1634 to have this problem, as are the OpenTransport and ISC DHCP clients.
1635 .RE
1636 .PP
1637 The
1638 .I always-reply-rfc1048
1639 statement
1640 .RS 0.25i
1641 .PP
1642 .B always-reply-rfc1048 \fIflag\fR\fB;\fR
1643 .PP
1644 Some BOOTP clients expect RFC1048-style responses, but do not follow
1645 RFC1048 when sending their requests.   You can tell that a client is
1646 having this problem if it is not getting the options you have
1647 configured for it and if you see in the server log the message
1648 "(non-rfc1048)" printed with each BOOTREQUEST that is logged.
1649 .PP
1650 If you want to send rfc1048 options to such a client, you can set the
1651 .B always-reply-rfc1048
1652 option in that client's host declaration, and the DHCP server will
1653 respond with an RFC-1048-style vendor options field.   This flag can
1654 be set in any scope, and will affect all clients covered by that
1655 scope.
1656 .RE
1657 .PP
1658 The
1659 .I authoritative
1660 statement
1661 .RS 0.25i
1662 .PP
1663 .B authoritative;
1664 .PP
1665 .B not authoritative;
1666 .PP
1667 The DHCP server will normally assume that the configuration
1668 information about a given network segment is not known to be correct
1669 and is not authoritative.  This is so that if a naive user installs a
1670 DHCP server not fully understanding how to configure it, it does not
1671 send spurious DHCPNAK messages to clients that have obtained addresses
1672 from a legitimate DHCP server on the network.
1673 .PP
1674 Network administrators setting up authoritative DHCP servers for their
1675 networks should always write \fBauthoritative;\fR at the top of their
1676 configuration file to indicate that the DHCP server \fIshould\fR send
1677 DHCPNAK messages to misconfigured clients.   If this is not done,
1678 clients will be unable to get a correct IP address after changing
1679 subnets until their old lease has expired, which could take quite a
1680 long time.
1681 .PP
1682 Usually, writing \fBauthoritative;\fR at the top level of the file
1683 should be sufficient.   However, if a DHCP server is to be set up so
1684 that it is aware of some networks for which it is authoritative and
1685 some networks for which it is not, it may be more appropriate to
1686 declare authority on a per-network-segment basis.
1687 .PP
1688 Note that the most specific scope for which the concept of authority
1689 makes any sense is the physical network segment - either a
1690 shared-network statement or a subnet statement that is not contained
1691 within a shared-network statement.  It is not meaningful to specify
1692 that the server is authoritative for some subnets within a shared
1693 network, but not authoritative for others, nor is it meaningful to
1694 specify that the server is authoritative for some host declarations
1695 and not others.
1696 .RE
1697 .PP
1698 The \fIboot-unknown-clients\fR statement
1699 .RS 0.25i
1700 .PP
1701 .B boot-unknown-clients \fIflag\fB;\fR
1702 .PP
1703 If the \fIboot-unknown-clients\fR statement is present and has a value
1704 of \fIfalse\fR or \fIoff\fR, then clients for which there is no
1705 .I host
1706 declaration will not be allowed to obtain IP addresses.   If this
1707 statement is not present or has a value of \fItrue\fR or \fIon\fR,
1708 then clients without host declarations will be allowed to obtain IP
1709 addresses, as long as those addresses are not restricted by
1710 .I allow
1711 and \fIdeny\fR statements within their \fIpool\fR declarations.
1712 .RE
1713 .PP
1714 The \fIddns-hostname\fR statement
1715 .RS 0.25i
1716 .PP
1717 .B ddns-hostname \fIname\fB;\fR
1718 .PP
1719 The \fIname\fR parameter should be the hostname that will be used in
1720 setting up the client's A and PTR records.   If no ddns-hostname is
1721 specified in scope, then the server will derive the hostname
1722 automatically, using an algorithm that varies for each of the
1723 different update methods.
1724 .RE
1725 .PP
1726 The \fIddns-domainname\fR statement
1727 .RS 0.25i
1728 .PP
1729 .B ddns-domainname \fIname\fB;\fR
1730 .PP
1731 The \fIname\fR parameter should be the domain name that will be
1732 appended to the client's hostname to form a fully-qualified
1733 domain-name (FQDN).
1734 .RE
1735 .PP
1736 The \fIddns-rev-domainname\fR statement
1737 .RS 0.25i
1738 .PP
1739 .B ddns-rev-domainname \fIname\fB;\fR
1740 The \fIname\fR parameter should be the domain name that will be
1741 appended to the client's reversed IP address to produce a name for use
1742 in the client's PTR record.   By default, this is "in-addr.arpa.", but
1743 the default can be overridden here.
1744 .PP
1745 The reversed IP address to which this domain name is appended is
1746 always the IP address of the client, in dotted quad notation, reversed
1747 - for example, if the IP address assigned to the client is
1748 10.17.92.74, then the reversed IP address is 74.92.17.10.   So a
1749 client with that IP address would, by default, be given a PTR record
1750 of 10.17.92.74.in-addr.arpa.
1751 .RE
1752 .PP
1753 The \fIddns-update-style\fR parameter
1754 .RS 0.25i
1755 .PP
1756 .B ddns-update-style \fIstyle\fB;\fR
1757 .PP
1758 The
1759 .I style
1760 parameter must be one of \fBad-hoc\fR, \fBinterim\fR or \fBnone\fR.
1761 The \fIddns-update-style\fR statement is only meaningful in the outer
1762 scope - it is evaluated once after reading the dhcpd.conf file, rather
1763 than each time a client is assigned an IP address, so there is no way
1764 to use different DNS update styles for different clients.
1765 .RE
1766 .PP
1767 .B The  
1768 .I ddns-updates
1769 .B statement
1770 .RS 0.25i
1771 .PP
1772  \fBddns-updates \fIflag\fR\fB;\fR
1773 .PP
1774 The \fIddns-updates\fR parameter controls whether or not the server will
1775 attempt to do a DNS update when a lease is confirmed.   Set this to \fIoff\fR
1776 if the server should not attempt to do updates within a certain scope.
1777 The \fIddns-updates\fR parameter is on by default.   To disable DNS
1778 updates in all scopes, it is preferable to use the
1779 \fIddns-update-style\fR statement, setting the style to \fInone\fR.
1780 .RE
1781 .PP
1782 The
1783 .I default-lease-time
1784 statement
1785 .RS 0.25i
1786 .PP
1787 .B default-lease-time \fItime\fR\fB;\fR
1788 .PP
1789 .I Time
1790 should be the length in seconds that will be assigned to a lease if
1791 the client requesting the lease does not ask for a specific expiration
1792 time.
1793 .RE
1794 .PP
1795 The
1796 .I do-forward-updates
1797 statement
1798 .RS 0.25i
1799 .PP
1800 .B do-forward-updates \fIflag\fB;\fR
1801 .PP
1802 The \fIdo-forward-updates\fR statement instructs the DHCP server as
1803 to whether it should attempt to update a DHCP client's A record
1804 when the client acquires or renews a lease.   This statement has no
1805 effect unless DNS updates are enabled and \fBddns-update-style\fR is
1806 set to \fBinterim\fR.   Forward updates are enabled by default.   If
1807 this statement is used to disable forward updates, the DHCP server
1808 will never attempt to update the client's A record, and will only ever
1809 attempt to update the client's PTR record if the client supplies an
1810 FQDN that should be placed in the PTR record using the fqdn option.
1811 If forward updates are enabled, the DHCP server will still honor the
1812 setting of the \fBclient-updates\fR flag.
1813 .RE
1814 .PP
1815 The
1816 .I dynamic-bootp-lease-cutoff
1817 statement
1818 .RS 0.25i
1819 .PP
1820 .B dynamic-bootp-lease-cutoff \fIdate\fB;\fR
1821 .PP
1822 The \fIdynamic-bootp-lease-cutoff\fR statement sets the ending time
1823 for all leases assigned dynamically to BOOTP clients.  Because BOOTP
1824 clients do not have any way of renewing leases, and don't know that
1825 their leases could expire, by default dhcpd assignes infinite leases
1826 to all BOOTP clients.  However, it may make sense in some situations
1827 to set a cutoff date for all BOOTP leases - for example, the end of a
1828 school term, or the time at night when a facility is closed and all
1829 machines are required to be powered off.
1830 .PP
1831 .I Date
1832 should be the date on which all assigned BOOTP leases will end.  The
1833 date is specified in the form:
1834 .PP
1835 .ce 1
1836 W YYYY/MM/DD HH:MM:SS
1837 .PP
1838 W is the day of the week expressed as a number
1839 from zero (Sunday) to six (Saturday).  YYYY is the year, including the
1840 century.  MM is the month expressed as a number from 1 to 12.  DD is
1841 the day of the month, counting from 1.  HH is the hour, from zero to
1842 23.  MM is the minute and SS is the second.  The time is always in
1843 Coordinated Universal Time (UTC), not local time.
1844 .RE
1845 .PP
1846 The
1847 .I dynamic-bootp-lease-length
1848 statement
1849 .RS 0.25i
1850 .PP
1851 .B dynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR
1852 .PP
1853 The \fIdynamic-bootp-lease-length\fR statement is used to set the
1854 length of leases dynamically assigned to BOOTP clients.   At some
1855 sites, it may be possible to assume that a lease is no longer in
1856 use if its holder has not used BOOTP or DHCP to get its address within
1857 a certain time period.   The period is specified in \fIlength\fR as a
1858 number of seconds.   If a client reboots using BOOTP during the
1859 timeout period, the lease duration is reset to \fIlength\fR, so a
1860 BOOTP client that boots frequently enough will never lose its lease.
1861 Needless to say, this parameter should be adjusted with extreme
1862 caution.
1863 .RE
1864 .PP
1865 The
1866 .I filename
1867 statement
1868 .RS 0.25i
1869 .PP
1870 .B filename\fR \fB"\fR\fIfilename\fR\fB";\fR
1871 .PP
1872 The \fIfilename\fR statement can be used to specify the name of the
1873 initial boot file which is to be loaded by a client.  The
1874 .I filename
1875 should be a filename recognizable to whatever file transfer protocol
1876 the client can be expected to use to load the file.
1877 .RE
1878 .PP
1879 The
1880 .I fixed-address
1881 declaration
1882 .RS 0.25i
1883 .PP
1884 .B fixed-address address\fR [\fB,\fR \fIaddress\fR ... ]\fB;\fR
1885 .PP
1886 The \fIfixed-address\fR declaration is used to assign one or more fixed
1887 IP addresses to a client.  It should only appear in a \fIhost\fR
1888 declaration.  If more than one address is supplied, then when the
1889 client boots, it will be assigned the address that corresponds to the
1890 network on which it is booting.  If none of the addresses in the
1891 \fIfixed-address\fR statement are valid for the network to which the client
1892 is connected, that client will not match the \fIhost\fR declaration
1893 containing that \fIfixed-address\fR declaration.  Each \fIaddress\fR
1894 in the \fIfixed-address\fR declaration should be either an IP address or
1895 a domain name that resolves to one or more IP addresses.
1896 .RE
1897 .PP
1898 The
1899 .I get-lease-hostnames
1900 statement
1901 .RS 0.25i
1902 .PP
1903 .B get-lease-hostnames\fR \fIflag\fR\fB;\fR
1904 .PP
1905 The \fIget-lease-hostnames\fR statement is used to tell dhcpd whether
1906 or not to look up the domain name corresponding to the IP address of
1907 each address in the lease pool and use that address for the DHCP
1908 \fIhostname\fR option.  If \fIflag\fR is true, then this lookup is
1909 done for all addresses in the current scope.   By default, or if
1910 \fIflag\fR is false, no lookups are done.
1911 .RE
1912 .PP
1913 The 
1914 .I hardware
1915 statement
1916 .RS 0.25i
1917 .PP
1918 .B hardware \fIhardware-type hardware-address\fB;\fR
1919 .PP
1920 In order for a BOOTP client to be recognized, its network hardware
1921 address must be declared using a \fIhardware\fR clause in the
1922 .I host
1923 statement.
1924 .I hardware-type
1925 must be the name of a physical hardware interface type.   Currently,
1926 only the
1927 .B ethernet
1928 and
1929 .B token-ring
1930 types are recognized, although support for a
1931 .B fddi
1932 hardware type (and others) would also be desirable.
1933 The
1934 .I hardware-address
1935 should be a set of hexadecimal octets (numbers from 0 through ff)
1936 separated by colons.   The \fIhardware\fR statement may also be used
1937 for DHCP clients.
1938 .RE
1939 .PP
1940 The
1941 .I lease-file-name
1942 statement
1943 .RS 0.25i
1944 .PP
1945 .B lease-file-name \fIname\fB;\fR
1946 .PP
1947 .I Name
1948 should be the name of the DHCP server's lease file.   By default, this
1949 is DBDIR/dhcpd.leases.   This statement \fBmust\fR appear in the outer
1950 scope of the configuration file - if it appears in some other scope,
1951 it will have no effect.
1952 .RE
1953 .PP
1954 The
1955 .I local-port
1956 statement
1957 .RS 0.25i
1958 .PP
1959 .B local-port \fIport\fB;\fR
1960 .PP
1961 This statement causes the DHCP server to listen for DHCP requests on
1962 the UDP port specified in \fIport\fR, rather than on port 67.
1963 .RE
1964 .PP
1965 The
1966 .I log-facility
1967 statement
1968 .RS 0.25i
1969 .PP
1970 .B log-facility \fIfacility\fB;\fR
1971 .PP
1972 This statement causes the DHCP server to do all of its logging on the
1973 specified log facility once the dhcpd.conf file has been read.   By
1974 default the DHCP server logs to the daemon facility.   Possible log
1975 facilities include auth, authpriv, cron, daemon, ftp, kern, lpr, mail,
1976 mark, news, ntp, security, syslog, user, uucp, and local0 through
1977 local7.   Not all of these facilities are available on all systems,
1978 and there may be other facilities available on other systems.
1979 .PP
1980 In addition to setting this value, you may need to modify your
1981 .I syslog.conf
1982 file to configure logging of the DHCP server.   For example, you might
1983 add a line like this:
1984 .PP
1985 .nf
1986         local7.debug /var/log/dhcpd.log
1987 .fi
1988 .PP
1989 The syntax of the \fIsyslog.conf\fR file may be different on some
1990 operating systems - consult the \fIsyslog.conf\fR manual page to be
1991 sure.  To get syslog to start logging to the new file, you must first
1992 create the file with correct ownership and permissions (usually, the
1993 same owner and permissions of your /var/log/messages or
1994 /usr/adm/messages file should be fine) and send a SIGHUP to syslogd.
1995 Some systems support log rollover using a shell script or program
1996 called newsyslog or logrotate, and you may be able to configure this
1997 as well so that your log file doesn't grow uncontrollably.
1998 .PP
1999 Because the \fIlog-facility\fR setting is controlled by the dhcpd.conf
2000 file, log messages printed while parsing the dhcpd.conf file or before
2001 parsing it are logged to the default log facility.  To prevent this,
2002 see the README file included with this distribution, which describes
2003 how to change the default log facility.  When this parameter is used,
2004 the DHCP server prints its startup message a second time after parsing
2005 the configuration file, so that the log will be as complete as
2006 possible.
2007 .RE
2008 .PP
2009 The
2010 .I max-lease-time
2011 statement
2012 .RS 0.25i
2013 .PP
2014 .B max-lease-time \fItime\fR\fB;\fR
2015 .PP
2016 .I Time
2017 should be the maximum length in seconds that will be assigned to a
2018 lease.   The only exception to this is that Dynamic BOOTP lease
2019 lengths, which are not specified by the client, are not limited by
2020 this maximum.
2021 .RE
2022 .PP
2023 The
2024 .I min-lease-time
2025 statement
2026 .RS 0.25i
2027 .PP
2028 .B min-lease-time \fItime\fR\fB;\fR
2029 .PP
2030 .I Time
2031 should be the minimum length in seconds that will be assigned to a
2032 lease.
2033 .RE
2034 .PP
2035 The
2036 .I min-secs
2037 statement
2038 .RS 0.25i
2039 .PP
2040 .B min-secs \fIseconds\fR\fB;\fR
2041 .PP
2042 .I Seconds
2043 should be the minimum number of seconds since a client began trying to
2044 acquire a new lease before the DHCP server will respond to its request.
2045 The number of seconds is based on what the client reports, and the maximum
2046 value that the client can report is 255 seconds.   Generally, setting this
2047 to one will result in the DHCP server not responding to the client's first
2048 request, but always responding to its second request.
2049 .PP
2050 This can be used
2051 to set up a secondary DHCP server which never offers an address to a client
2052 until the primary server has been given a chance to do so.   If the primary
2053 server is down, the client will bind to the secondary server, but otherwise
2054 clients should always bind to the primary.   Note that this does not, by
2055 itself, permit a primary server and a secondary server to share a pool of
2056 dynamically-allocatable addresses.
2057 .RE
2058 .PP
2059 The
2060 .I next-server
2061 statement
2062 .RS 0.25i
2063 .PP
2064 .B next-server\fR \fIserver-name\fR\fB;\fR
2065 .PP
2066 The \fInext-server\fR statement is used to specify the host address of
2067 the server from which the initial boot file (specified in the
2068 \fIfilename\fR statement) is to be loaded.   \fIServer-name\fR should
2069 be a numeric IP address or a domain name.   If no \fInext-server\fR
2070 parameter applies to a given client, the DHCP server's IP address is
2071 used.
2072 .RE
2073 .PP
2074 The
2075 .I omapi-port
2076 statement
2077 .RS 0.25i
2078 .PP
2079 .B omapi-port\fR \fIport\fR\fB;\fR
2080 .PP
2081 The \fIomapi-port\fR statement causes the DHCP server to listen for
2082 OMAPI connections on the specified port.   This statement is required
2083 to enable the OMAPI protocol, which is used to examine and modify the
2084 state of the DHCP server as it is running.
2085 .RE
2086 .PP
2087 The
2088 .I one-lease-per-client
2089 statement
2090 .RS 0.25i
2091 .PP
2092 .B one-lease-per-client \fIflag\fR\fB;\fR
2093 .PP
2094 If this flag is enabled, whenever a client sends a DHCPREQUEST for a
2095 particular lease, the server will automatically free any other leases
2096 the client holds.   This presumes that when the client sends a
2097 DHCPREQUEST, it has forgotten any lease not mentioned in the
2098 DHCPREQUEST - i.e., the client has only a single network interface
2099 .I and
2100 it does not remember leases it's holding on networks to which it is
2101 not currently attached.   Neither of these assumptions are guaranteed
2102 or provable, so we urge caution in the use of this statement.
2103 .RE
2104 .PP
2105 The
2106 .I pid-file-name
2107 statement
2108 .RS 0.25i
2109 .PP
2110 .B pid-file-name
2111 .I name\fR\fB;\fR
2112 .PP
2113 .I Name
2114 should be the name of the DHCP server's process ID file.   This is the
2115 file in which the DHCP server's process ID is stored when the server
2116 starts.   By default, this is RUNDIR/dhcpd.pid.   Like the
2117 lease-file-name statement, this statement must appear in the outer scope
2118 of the configuration file.
2119 .RE
2120 .PP
2121 The
2122 .I ping-check
2123 statement
2124 .RS 0.25i
2125 .PP
2126 .B ping-check
2127 .I flag\fR\fB;\fR
2128 .PP
2129 When the DHCP server is considering dynamically allocating an IP
2130 address to a client, it first sends an ICMP Echo request (a \fIping\fR)
2131 to the address being assigned.   It waits for a second, and if no
2132 ICMP Echo response has been heard, it assigns the address.   If a
2133 response \fIis\fR heard, the lease is abandoned, and the server does
2134 not respond to the client.
2135 .PP
2136 This \fIping check\fR introduces a default one-second delay in responding
2137 to DHCPDISCOVER messages, which can be a problem for some clients.   The
2138 default delay of one second may be configured using the ping-timeout
2139 parameter.  The ping-check configuration parameter can be used to control
2140 checking - if its value is false, no ping check is done.
2141 .RE
2142 .PP
2143 The
2144 .I ping-timeout
2145 statement
2146 .RS 0.25i
2147 .PP
2148 .B ping-timeout
2149 .I seconds\fR\fB;\fR
2150 .PP
2151 If the DHCP server determined it should send an ICMP echo request (a
2152 \fIping\fR) because the ping-check statement is true, ping-timeout allows
2153 you to configure how many seconds the DHCP server should wait for an
2154 ICMP Echo response to be heard, if no ICMP Echo response has been received
2155 before the timeout expires, it assigns the address.  If a response \fIis\fR
2156 heard, the lease is abandoned, and the server does not respond to the client.
2157 If no value is set, ping-timeout defaults to 1 second.
2158 .RE
2159 .PP
2160 The
2161 .I server-identifier
2162 statement
2163 .RS 0.25i
2164 .PP
2165 .B server-identifier \fIhostname\fR\fB;\fR
2166 .PP
2167 The server-identifier statement can be used to define the value that
2168 is sent in the DHCP Server Identifier option for a given scope.   The
2169 value specified \fBmust\fR be an IP address for the DHCP server, and
2170 must be reachable by all clients served by a particular scope.
2171 .PP
2172 The use of the server-identifier statement is not recommended - the only
2173 reason to use it is to force a value other than the default value to be
2174 sent on occasions where the default value would be incorrect.   The default
2175 value is the first IP address associated with the physical network interface
2176 on which the request arrived.
2177 .PP
2178 The usual case where the
2179 \fIserver-identifier\fR statement needs to be sent is when a physical
2180 interface has more than one IP address, and the one being sent by default
2181 isn't appropriate for some or all clients served by that interface.
2182 Another common case is when an alias is defined for the purpose of
2183 having a consistent IP address for the DHCP server, and it is desired
2184 that the clients use this IP address when contacting the server.
2185 .PP
2186 Supplying a value for the dhcp-server-identifier option is equivalent
2187 to using the server-identifier statement.
2188 .RE
2189 .PP
2190 The
2191 .I server-name
2192 statement
2193 .RS 0.25i
2194 .PP
2195 .B server-name "\fIname\fB";\fR
2196 .PP
2197 The \fIserver-name\fR statement can be used to inform the client of
2198 the name of the server from which it is booting.   \fIName\fR should
2199 be the name that will be provided to the client.
2200 .RE
2201 .PP
2202 The
2203 .I site-option-space
2204 statement
2205 .RS 0.25i
2206 .PP
2207 .B site-option-space "\fIname\fB";\fR
2208 .PP
2209 The \fIsite-option-space\fR statement can be used to determine from
2210 what option space site-local options will be taken.   This can be used
2211 in much the same way as the \fIvendor-option-space\fR statement.
2212 Site-local options in DHCP are those options whose numeric codes are
2213 greater than 128.   These options are intended for site-specific
2214 uses, but are frequently used by vendors of embedded hardware that
2215 contains DHCP clients.   Because site-specific options are allocated
2216 on an ad hoc basis, it is quite possible that one vendor's DHCP client
2217 might use the same option code that another vendor's client uses, for
2218 different purposes.   The \fIsite-option-space\fR option can be used
2219 to assign a different set of site-specific options for each such
2220 vendor, using conditional evaluation (see \fBdhcp-eval (5)\fR for
2221 details).
2222 .RE
2223 .PP
2224 The
2225 .I stash-agent-options
2226 statement
2227 .RS 0.25i
2228 .PP
2229 .B stash-agent-options \fIflag\fB;\fR
2230 .PP
2231 If the \fIstash-agent-options\fR parameter is true for a given client,
2232 the server will record the relay agent information options sent during
2233 the client's initial DHCPREQUEST message when the client was in the
2234 SELECTING state and behave as if those options are included in all
2235 subsequent DHCPREQUEST messages sent in the RENEWING state.   This
2236 works around a problem with relay agent information options, which is
2237 that they usually not appear in DHCPREQUEST messages sent by the
2238 client in the RENEWING state, because such messages are unicast
2239 directly to the server and not sent through a relay agent.
2240 .RE
2241 .PP
2242 The
2243 .I update-optimization
2244 statement
2245 .RS 0.25i
2246 .PP
2247 .B update-optimization \fIflag\fB;\fR
2248 .PP
2249 If the \fIupdate-optimization\fR parameter is false for a given client,
2250 the server will attempt a DNS update for that client each time the
2251 client renews its lease, rather than only attempting an update when it
2252 appears to be necessary.   This will allow the DNS to heal from
2253 database inconsistencies more easily, but the cost is that the DHCP
2254 server must do many more DNS updates.   We recommend leaving this option
2255 enabled, which is the default.  This option only affects the behavior of
2256 the interim DNS update scheme, and has no effect on the ad-hoc DNS update
2257 scheme.   If this parameter is not specified, or is true, the DHCP server
2258 will only update when the client information changes, the client gets a
2259 different lease, or the client's lease expires.
2260 .RE
2261 .PP
2262 The
2263 .I update-static-leases
2264 statement
2265 .RS 0.25i
2266 .PP
2267 .B update-static-leases \fIflag\fB;\fR
2268 .PP
2269 The \fIupdate-static-leases\fR flag, if enabled, causes the DHCP
2270 server to do DNS updates for clients even if those clients are being
2271 assigned their IP address using a \fIfixed-address\fR statement - that
2272 is, the client is being given a static assignment.   This can only
2273 work with the \fIinterim\fR DNS update scheme.   It is not
2274 recommended because the DHCP server has no way to tell that the update
2275 has been done, and therefore will not delete the record when it is not
2276 in use.   Also, the server must attempt the update each time the
2277 client renews its lease, which could have a significant performance
2278 impact in environments that place heavy demands on the DHCP server.
2279 .RE
2280 .PP
2281 The
2282 .I use-host-decl-names
2283 statement
2284 .RS 0.25i
2285 .PP
2286 .B use-host-decl-names \fIflag\fB;\fR
2287 .PP
2288 If the \fIuse-host-decl-names\fR parameter is true in a given scope,
2289 then for every host declaration within that scope, the name provided
2290 for the host declaration will be supplied to the client as its
2291 hostname.   So, for example,
2292 .PP
2293 .nf
2294     group {
2295       use-host-decl-names on;
2296
2297       host joe {
2298         hardware ethernet 08:00:2b:4c:29:32;
2299         fixed-address joe.fugue.com;
2300       }
2301     }
2302
2303 is equivalent to
2304
2305       host joe {
2306         hardware ethernet 08:00:2b:4c:29:32;
2307         fixed-address joe.fugue.com;
2308         option host-name "joe";
2309       }
2310 .fi
2311 .PP
2312 An \fIoption host-name\fR statement within a host declaration will
2313 override the use of the name in the host declaration.
2314 .PP
2315 It should be noted here that most DHCP clients completely ignore the
2316 host-name option sent by the DHCP server, and there is no way to
2317 configure them not to do this.   So you generally have a choice of
2318 either not having any hostname to client IP address mapping that the
2319 client will recognize, or doing DNS updates.   It is beyond
2320 the scope of this document to describe how to make this
2321 determination.
2322 .RE
2323 .PP
2324 The
2325 .I use-lease-addr-for-default-route
2326 statement
2327 .RS 0.25i
2328 .PP
2329 .B use-lease-addr-for-default-route \fIflag\fR\fB;\fR
2330 .PP
2331 If the \fIuse-lease-addr-for-default-route\fR parameter is true in a
2332 given scope, then instead of sending the value specified in the
2333 routers option (or sending no value at all), the IP address of the
2334 lease being assigned is sent to the client.   This supposedly causes
2335 Win95 machines to ARP for all IP addresses, which can be helpful if
2336 your router is configured for proxy ARP.   The use of this feature is
2337 not recommended, because it won't work for many DHCP clients.
2338 .RE
2339 .PP
2340 The
2341 .I vendor-option-space
2342 statement
2343 .RS 0.25i
2344 .PP
2345 .B vendor-option-space \fIstring\fR\fB;\fR
2346 .PP
2347 The \fIvendor-option-space\fR parameter determines from what option
2348 space vendor options are taken.   The use of this configuration
2349 parameter is illustrated in the \fBdhcp-options(5)\fR manual page, in
2350 the \fIVENDOR ENCAPSULATED OPTIONS\fR section.
2351 .RE
2352 .SH SETTING PARAMETER VALUES USING EXPRESSIONS
2353 Sometimes it's helpful to be able to set the value of a DHCP server
2354 parameter based on some value that the client has sent.   To do this,
2355 you can use expression evaluation.   The 
2356 .B dhcp-eval(5)
2357 manual page describes how to write expressions.   To assign the result
2358 of an evaluation to an option, define the option as follows:
2359 .nf
2360 .sp 1
2361   \fImy-parameter \fB= \fIexpression \fB;\fR
2362 .fi
2363 .PP
2364 For example:
2365 .nf
2366 .sp 1
2367   ddns-hostname = binary-to-ascii (16, 8, "-",
2368                                    substring (hardware, 1, 6));
2369 .fi
2370 .SH REFERENCE: OPTION STATEMENTS
2371 DHCP option statements are documented in the
2372 .B dhcp-options(5)
2373 manual page.
2374 .SH REFERENCE: EXPRESSIONS
2375 Expressions used in DHCP option statements and elsewhere are
2376 documented in the
2377 .B dhcp-eval(5)
2378 manual page.
2379 .SH SEE ALSO
2380 dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132, RFC2131.
2381 .SH AUTHOR
2382 .B dhcpd.conf(5)
2383 was written by Ted Lemon
2384 under a contract with Vixie Labs.   Funding
2385 for this project was provided by Internet Systems Consortium.
2386 Information about Internet Systems Consortium can be found at
2387 .B http://www.isc.org.