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