Annotation of embedaddon/dhcp/server/dhcpd.conf.5, revision 1.1
1.1 ! misho 1: .\" dhcpd.conf.5
! 2: .\"
! 3: .\" Copyright (c) 2004-2011 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.99.10.4.6.2 2011-06-01 23:38:06 sar 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: This option does not satisfy the requirement of failover peers for denying
! 1715: dynamic bootp clients. The \fBdeny dynamic bootp clients;\fR option should
! 1716: be used instead. See the ALLOW AND DENY WITHIN POOL DECLARATIONS section
! 1717: of this man page for more details.
! 1718: .PP
! 1719: .B The
! 1720: .I booting
! 1721: .B keyword
! 1722: .PP
! 1723: \fBallow booting;\fR
! 1724: \fBdeny booting;\fR
! 1725: \fBignore booting;\fR
! 1726: .PP
! 1727: The \fBbooting\fR flag is used to tell dhcpd whether or not to respond
! 1728: to queries from a particular client. This keyword only has meaning
! 1729: when it appears in a host declaration. By default, booting is
! 1730: \fBallow\fRed, but if it is disabled for a particular client, then
! 1731: that client will not be able to get an address from the DHCP server.
! 1732: .PP
! 1733: .B The
! 1734: .I duplicates
! 1735: .B keyword
! 1736: .PP
! 1737: \fBallow duplicates;\fR
! 1738: \fBdeny duplicates;\fR
! 1739: .PP
! 1740: Host declarations can match client messages based on the DHCP Client
! 1741: Identifier option or based on the client's network hardware type and
! 1742: MAC address. If the MAC address is used, the host declaration will
! 1743: match any client with that MAC address - even clients with different
! 1744: client identifiers. This doesn't normally happen, but is possible
! 1745: when one computer has more than one operating system installed on it -
! 1746: for example, Microsoft Windows and NetBSD or Linux.
! 1747: .PP
! 1748: The \fBduplicates\fR flag tells the DHCP server that if a request is
! 1749: received from a client that matches the MAC address of a host
! 1750: declaration, any other leases matching that MAC address should be
! 1751: discarded by the server, even if the UID is not the same. This is a
! 1752: violation of the DHCP protocol, but can prevent clients whose client
! 1753: identifiers change regularly from holding many leases at the same time.
! 1754: By default, duplicates are \fBallow\fRed.
! 1755: .PP
! 1756: .B The
! 1757: .I declines
! 1758: .B keyword
! 1759: .PP
! 1760: \fBallow declines;\fR
! 1761: \fBdeny declines;\fR
! 1762: \fBignore declines;\fR
! 1763: .PP
! 1764: The DHCPDECLINE message is used by DHCP clients to indicate that the
! 1765: lease the server has offered is not valid. When the server receives
! 1766: a DHCPDECLINE for a particular address, it normally abandons that
! 1767: address, assuming that some unauthorized system is using it.
! 1768: Unfortunately, a malicious or buggy client can, using DHCPDECLINE
! 1769: messages, completely exhaust the DHCP server's allocation pool. The
! 1770: server will reclaim these leases, but while the client is running
! 1771: through the pool, it may cause serious thrashing in the DNS, and it
! 1772: will also cause the DHCP server to forget old DHCP client address
! 1773: allocations.
! 1774: .PP
! 1775: The \fBdeclines\fR flag tells the DHCP server whether or not to honor
! 1776: DHCPDECLINE messages. If it is set to \fBdeny\fR or \fBignore\fR in
! 1777: a particular scope, the DHCP server will not respond to DHCPDECLINE
! 1778: messages.
! 1779: .PP
! 1780: .B The
! 1781: .I client-updates
! 1782: .B keyword
! 1783: .PP
! 1784: \fBallow client-updates;\fR
! 1785: \fBdeny client-updates;\fR
! 1786: .PP
! 1787: The \fBclient-updates\fR flag tells the DHCP server whether or not to
! 1788: honor the client's intention to do its own update of its A record.
! 1789: This is only relevant when doing \fIinterim\fR DNS updates. See the
! 1790: documentation under the heading THE INTERIM DNS UPDATE SCHEME for
! 1791: details.
! 1792: .PP
! 1793: .B The
! 1794: .I leasequery
! 1795: .B keyword
! 1796: .PP
! 1797: \fBallow leasequery;\fR
! 1798: \fBdeny leasequery;\fR
! 1799: .PP
! 1800: The \fBleasequery\fR flag tells the DHCP server whether or not to
! 1801: answer DHCPLEASEQUERY packets. The answer to a DHCPLEASEQUERY packet
! 1802: includes information about a specific lease, such as when it was
! 1803: issued and when it will expire. By default, the server will not
! 1804: respond to these packets.
! 1805: .SH ALLOW AND DENY WITHIN POOL DECLARATIONS
! 1806: .PP
! 1807: The uses of the allow and deny keywords shown in the previous section
! 1808: work pretty much the same way whether the client is sending a
! 1809: DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated
! 1810: to the client (either the old address it's requesting, or a new
! 1811: address) and then that address will be tested to see if it's okay to
! 1812: let the client have it. If the client requested it, and it's not
! 1813: okay, the server will send a DHCPNAK message. Otherwise, the server
! 1814: will simply not respond to the client. If it is okay to give the
! 1815: address to the client, the server will send a DHCPACK message.
! 1816: .PP
! 1817: The primary motivation behind pool declarations is to have address
! 1818: allocation pools whose allocation policies are different. A client
! 1819: may be denied access to one pool, but allowed access to another pool
! 1820: on the same network segment. In order for this to work, access
! 1821: control has to be done during address allocation, not after address
! 1822: allocation is done.
! 1823: .PP
! 1824: When a DHCPREQUEST message is processed, address allocation simply
! 1825: consists of looking up the address the client is requesting and seeing
! 1826: if it's still available for the client. If it is, then the DHCP
! 1827: server checks both the address pool permit lists and the relevant
! 1828: in-scope allow and deny statements to see if it's okay to give the
! 1829: lease to the client. In the case of a DHCPDISCOVER message, the
! 1830: allocation process is done as described previously in the ADDRESS
! 1831: ALLOCATION section.
! 1832: .PP
! 1833: When declaring permit lists for address allocation pools, the
! 1834: following syntaxes are recognized following the allow or deny keywords:
! 1835: .PP
! 1836: \fBknown-clients;\fR
! 1837: .PP
! 1838: If specified, this statement either allows or prevents allocation from
! 1839: this pool to any client that has a host declaration (i.e., is known).
! 1840: A client is known if it has a host declaration in \fIany\fR scope, not
! 1841: just the current scope.
! 1842: .PP
! 1843: \fBunknown-clients;\fR
! 1844: .PP
! 1845: If specified, this statement either allows or prevents allocation from
! 1846: this pool to any client that has no host declaration (i.e., is not
! 1847: known).
! 1848: .PP
! 1849: \fBmembers of "\fRclass\fB";\fR
! 1850: .PP
! 1851: If specified, this statement either allows or prevents allocation from
! 1852: this pool to any client that is a member of the named class.
! 1853: .PP
! 1854: \fBdynamic bootp clients;\fR
! 1855: .PP
! 1856: If specified, this statement either allows or prevents allocation from
! 1857: this pool to any bootp client.
! 1858: .PP
! 1859: \fBauthenticated clients;\fR
! 1860: .PP
! 1861: If specified, this statement either allows or prevents allocation from
! 1862: this pool to any client that has been authenticated using the DHCP
! 1863: authentication protocol. This is not yet supported.
! 1864: .PP
! 1865: \fBunauthenticated clients;\fR
! 1866: .PP
! 1867: If specified, this statement either allows or prevents allocation from
! 1868: this pool to any client that has not been authenticated using the DHCP
! 1869: authentication protocol. This is not yet supported.
! 1870: .PP
! 1871: \fBall clients;\fR
! 1872: .PP
! 1873: If specified, this statement either allows or prevents allocation from
! 1874: this pool to all clients. This can be used when you want to write a
! 1875: pool declaration for some reason, but hold it in reserve, or when you
! 1876: want to renumber your network quickly, and thus want the server to
! 1877: force all clients that have been allocated addresses from this pool to
! 1878: obtain new addresses immediately when they next renew.
! 1879: .PP
! 1880: \fBafter \fItime\fR\fB;\fR
! 1881: .PP
! 1882: If specified, this statement either allows or prevents allocation from
! 1883: this pool after a given date. This can be used when you want to move
! 1884: clients from one pool to another. The server adjusts the regular lease
! 1885: time so that the latest expiry time is at the given time+min-lease-time.
! 1886: A short min-lease-time enforces a step change, whereas a longer
! 1887: min-lease-time allows for a gradual change.
! 1888: \fItime\fR is either second since epoch, or a UTC time string e.g.
! 1889: 4 2007/08/24 09:14:32 or a string with time zone offset in seconds
! 1890: e.g. 4 2007/08/24 11:14:32 -7200
! 1891: .SH REFERENCE: PARAMETERS
! 1892: The
! 1893: .I adaptive-lease-time-threshold
! 1894: statement
! 1895: .RS 0.25i
! 1896: .PP
! 1897: .B adaptive-lease-time-threshold \fIpercentage\fR\fB;\fR
! 1898: .PP
! 1899: When the number of allocated leases within a pool rises above
! 1900: the \fIpercentage\fR given in this statement, the DHCP server decreases
! 1901: the lease length for new clients within this pool to \fImin-lease-time\fR
! 1902: seconds. Clients renewing an already valid (long) leases get at least the
! 1903: remaining time from the current lease. Since the leases expire faster,
! 1904: the server may either recover more quickly or avoid pool exhaustion
! 1905: entirely. Once the number of allocated leases drop below the threshold,
! 1906: the server reverts back to normal lease times. Valid percentages are
! 1907: between 1 and 99.
! 1908: .RE
! 1909: .PP
! 1910: The
! 1911: .I always-broadcast
! 1912: statement
! 1913: .RS 0.25i
! 1914: .PP
! 1915: .B always-broadcast \fIflag\fR\fB;\fR
! 1916: .PP
! 1917: The DHCP and BOOTP protocols both require DHCP and BOOTP clients to
! 1918: set the broadcast bit in the flags field of the BOOTP message header.
! 1919: Unfortunately, some DHCP and BOOTP clients do not do this, and
! 1920: therefore may not receive responses from the DHCP server. The DHCP
! 1921: server can be made to always broadcast its responses to clients by
! 1922: setting this flag to \'on\' for the relevant scope; relevant scopes would be
! 1923: inside a conditional statement, as a parameter for a class, or as a parameter
! 1924: for a host declaration. To avoid creating excess broadcast traffic on your
! 1925: network, we recommend that you restrict the use of this option to as few
! 1926: clients as possible. For example, the Microsoft DHCP client is known not
! 1927: to have this problem, as are the OpenTransport and ISC DHCP clients.
! 1928: .RE
! 1929: .PP
! 1930: The
! 1931: .I always-reply-rfc1048
! 1932: statement
! 1933: .RS 0.25i
! 1934: .PP
! 1935: .B always-reply-rfc1048 \fIflag\fR\fB;\fR
! 1936: .PP
! 1937: Some BOOTP clients expect RFC1048-style responses, but do not follow
! 1938: RFC1048 when sending their requests. You can tell that a client is
! 1939: having this problem if it is not getting the options you have
! 1940: configured for it and if you see in the server log the message
! 1941: "(non-rfc1048)" printed with each BOOTREQUEST that is logged.
! 1942: .PP
! 1943: If you want to send rfc1048 options to such a client, you can set the
! 1944: .B always-reply-rfc1048
! 1945: option in that client's host declaration, and the DHCP server will
! 1946: respond with an RFC-1048-style vendor options field. This flag can
! 1947: be set in any scope, and will affect all clients covered by that
! 1948: scope.
! 1949: .RE
! 1950: .PP
! 1951: The
! 1952: .I authoritative
! 1953: statement
! 1954: .RS 0.25i
! 1955: .PP
! 1956: .B authoritative;
! 1957: .PP
! 1958: .B not authoritative;
! 1959: .PP
! 1960: The DHCP server will normally assume that the configuration
! 1961: information about a given network segment is not known to be correct
! 1962: and is not authoritative. This is so that if a naive user installs a
! 1963: DHCP server not fully understanding how to configure it, it does not
! 1964: send spurious DHCPNAK messages to clients that have obtained addresses
! 1965: from a legitimate DHCP server on the network.
! 1966: .PP
! 1967: Network administrators setting up authoritative DHCP servers for their
! 1968: networks should always write \fBauthoritative;\fR at the top of their
! 1969: configuration file to indicate that the DHCP server \fIshould\fR send
! 1970: DHCPNAK messages to misconfigured clients. If this is not done,
! 1971: clients will be unable to get a correct IP address after changing
! 1972: subnets until their old lease has expired, which could take quite a
! 1973: long time.
! 1974: .PP
! 1975: Usually, writing \fBauthoritative;\fR at the top level of the file
! 1976: should be sufficient. However, if a DHCP server is to be set up so
! 1977: that it is aware of some networks for which it is authoritative and
! 1978: some networks for which it is not, it may be more appropriate to
! 1979: declare authority on a per-network-segment basis.
! 1980: .PP
! 1981: Note that the most specific scope for which the concept of authority
! 1982: makes any sense is the physical network segment - either a
! 1983: shared-network statement or a subnet statement that is not contained
! 1984: within a shared-network statement. It is not meaningful to specify
! 1985: that the server is authoritative for some subnets within a shared
! 1986: network, but not authoritative for others, nor is it meaningful to
! 1987: specify that the server is authoritative for some host declarations
! 1988: and not others.
! 1989: .RE
! 1990: .PP
! 1991: The \fIboot-unknown-clients\fR statement
! 1992: .RS 0.25i
! 1993: .PP
! 1994: .B boot-unknown-clients \fIflag\fB;\fR
! 1995: .PP
! 1996: If the \fIboot-unknown-clients\fR statement is present and has a value
! 1997: of \fIfalse\fR or \fIoff\fR, then clients for which there is no
! 1998: .I host
! 1999: declaration will not be allowed to obtain IP addresses. If this
! 2000: statement is not present or has a value of \fItrue\fR or \fIon\fR,
! 2001: then clients without host declarations will be allowed to obtain IP
! 2002: addresses, as long as those addresses are not restricted by
! 2003: .I allow
! 2004: and \fIdeny\fR statements within their \fIpool\fR declarations.
! 2005: .RE
! 2006: .PP
! 2007: The \fIdb-time-format\fR statement
! 2008: .RS 0.25i
! 2009: .PP
! 2010: .B db-time-format \fR[ \fIdefault\fR | \fIlocal\fR ] \fB;\fR
! 2011: .PP
! 2012: The DHCP server software outputs several timestamps when writing leases to
! 2013: persistent storage. This configuration parameter selects one of two output
! 2014: formats. The \fIdefault\fR format prints the day, date, and time in UTC,
! 2015: while the \fIlocal\fR format prints the system seconds-since-epoch, and
! 2016: helpfully provides the day and time in the system timezone in a comment.
! 2017: The time formats are described in detail in the dhcpd.leases(5) manpage.
! 2018: .RE
! 2019: .PP
! 2020: The \fIddns-hostname\fR statement
! 2021: .RS 0.25i
! 2022: .PP
! 2023: .B ddns-hostname \fIname\fB;\fR
! 2024: .PP
! 2025: The \fIname\fR parameter should be the hostname that will be used in
! 2026: setting up the client's A and PTR records. If no ddns-hostname is
! 2027: specified in scope, then the server will derive the hostname
! 2028: automatically, using an algorithm that varies for each of the
! 2029: different update methods.
! 2030: .RE
! 2031: .PP
! 2032: The \fIddns-domainname\fR statement
! 2033: .RS 0.25i
! 2034: .PP
! 2035: .B ddns-domainname \fIname\fB;\fR
! 2036: .PP
! 2037: The \fIname\fR parameter should be the domain name that will be
! 2038: appended to the client's hostname to form a fully-qualified
! 2039: domain-name (FQDN).
! 2040: .RE
! 2041: .PP
! 2042: The \fIddns-rev-domainname\fR statement
! 2043: .RS 0.25i
! 2044: .PP
! 2045: .B ddns-rev-domainname \fIname\fB;\fR
! 2046: The \fIname\fR parameter should be the domain name that will be
! 2047: appended to the client's reversed IP address to produce a name for use
! 2048: in the client's PTR record. By default, this is "in-addr.arpa.", but
! 2049: the default can be overridden here.
! 2050: .PP
! 2051: The reversed IP address to which this domain name is appended is
! 2052: always the IP address of the client, in dotted quad notation, reversed
! 2053: - for example, if the IP address assigned to the client is
! 2054: 10.17.92.74, then the reversed IP address is 74.92.17.10. So a
! 2055: client with that IP address would, by default, be given a PTR record
! 2056: of 10.17.92.74.in-addr.arpa.
! 2057: .RE
! 2058: .PP
! 2059: The \fIddns-update-style\fR parameter
! 2060: .RS 0.25i
! 2061: .PP
! 2062: .B ddns-update-style \fIstyle\fB;\fR
! 2063: .PP
! 2064: The
! 2065: .I style
! 2066: parameter must be one of \fBad-hoc\fR, \fBinterim\fR or \fBnone\fR.
! 2067: The \fIddns-update-style\fR statement is only meaningful in the outer
! 2068: scope - it is evaluated once after reading the dhcpd.conf file, rather
! 2069: than each time a client is assigned an IP address, so there is no way
! 2070: to use different DNS update styles for different clients. The default
! 2071: is \fBnone\fR.
! 2072: .RE
! 2073: .PP
! 2074: .B The
! 2075: .I ddns-updates
! 2076: .B statement
! 2077: .RS 0.25i
! 2078: .PP
! 2079: \fBddns-updates \fIflag\fR\fB;\fR
! 2080: .PP
! 2081: The \fIddns-updates\fR parameter controls whether or not the server will
! 2082: attempt to do a DNS update when a lease is confirmed. Set this to \fIoff\fR
! 2083: if the server should not attempt to do updates within a certain scope.
! 2084: The \fIddns-updates\fR parameter is on by default. To disable DNS
! 2085: updates in all scopes, it is preferable to use the
! 2086: \fIddns-update-style\fR statement, setting the style to \fInone\fR.
! 2087: .RE
! 2088: .PP
! 2089: The
! 2090: .I default-lease-time
! 2091: statement
! 2092: .RS 0.25i
! 2093: .PP
! 2094: .B default-lease-time \fItime\fR\fB;\fR
! 2095: .PP
! 2096: .I Time
! 2097: should be the length in seconds that will be assigned to a lease if
! 2098: the client requesting the lease does not ask for a specific expiration
! 2099: time. This is used for both DHCPv4 and DHCPv6 leases (it is also known
! 2100: as the "valid lifetime" in DHCPv6).
! 2101: The default is 43200 seconds.
! 2102: .RE
! 2103: .PP
! 2104: The
! 2105: .I delayed-ack
! 2106: and
! 2107: .I max-ack-delay
! 2108: statements
! 2109: .RS 0.25i
! 2110: .PP
! 2111: .B delayed-ack \fIcount\fR\fB;\fR
! 2112: .B max-ack-delay \fImicroseconds\fR\fB;\fR
! 2113: .PP
! 2114: .I Count
! 2115: should be an integer value from zero to 2^16-1, and defaults to 28. The
! 2116: count represents how many DHCPv4 replies maximum will be queued pending
! 2117: transmission until after a database commit event. If this number is
! 2118: reached, a database commit event (commonly resulting in fsync() and
! 2119: representing a performance penalty) will be made, and the reply packets
! 2120: will be transmitted in a batch afterwards. This preserves the RFC2131
! 2121: direction that "stable storage" be updated prior to replying to clients.
! 2122: Should the DHCPv4 sockets "go dry" (select() returns immediately with no
! 2123: read sockets), the commit is made and any queued packets are transmitted.
! 2124: .PP
! 2125: Similarly, \fImicroseconds\fR indicates how many microseconds are permitted
! 2126: to pass inbetween queuing a packet pending an fsync, and performing the
! 2127: fsync. Valid values range from 0 to 2^32-1, and defaults to 250,000 (1/4 of
! 2128: a second).
! 2129: .PP
! 2130: Please note that as delayed-ack is currently experimental, the delayed-ack
! 2131: feature is not compiled in by default, but must be enabled at compile time
! 2132: with \'./configure --enable-delayed-ack\'.
! 2133: .RE
! 2134: .PP
! 2135: The
! 2136: .I do-forward-updates
! 2137: statement
! 2138: .RS 0.25i
! 2139: .PP
! 2140: .B do-forward-updates \fIflag\fB;\fR
! 2141: .PP
! 2142: The \fIdo-forward-updates\fR statement instructs the DHCP server as
! 2143: to whether it should attempt to update a DHCP client's A record
! 2144: when the client acquires or renews a lease. This statement has no
! 2145: effect unless DNS updates are enabled and \fBddns-update-style\fR is
! 2146: set to \fBinterim\fR. Forward updates are enabled by default. If
! 2147: this statement is used to disable forward updates, the DHCP server
! 2148: will never attempt to update the client's A record, and will only ever
! 2149: attempt to update the client's PTR record if the client supplies an
! 2150: FQDN that should be placed in the PTR record using the fqdn option.
! 2151: If forward updates are enabled, the DHCP server will still honor the
! 2152: setting of the \fBclient-updates\fR flag.
! 2153: .RE
! 2154: .PP
! 2155: The
! 2156: .I dynamic-bootp-lease-cutoff
! 2157: statement
! 2158: .RS 0.25i
! 2159: .PP
! 2160: .B dynamic-bootp-lease-cutoff \fIdate\fB;\fR
! 2161: .PP
! 2162: The \fIdynamic-bootp-lease-cutoff\fR statement sets the ending time
! 2163: for all leases assigned dynamically to BOOTP clients. Because BOOTP
! 2164: clients do not have any way of renewing leases, and don't know that
! 2165: their leases could expire, by default dhcpd assigns infinite leases
! 2166: to all BOOTP clients. However, it may make sense in some situations
! 2167: to set a cutoff date for all BOOTP leases - for example, the end of a
! 2168: school term, or the time at night when a facility is closed and all
! 2169: machines are required to be powered off.
! 2170: .PP
! 2171: .I Date
! 2172: should be the date on which all assigned BOOTP leases will end. The
! 2173: date is specified in the form:
! 2174: .PP
! 2175: .ce 1
! 2176: W YYYY/MM/DD HH:MM:SS
! 2177: .PP
! 2178: W is the day of the week expressed as a number
! 2179: from zero (Sunday) to six (Saturday). YYYY is the year, including the
! 2180: century. MM is the month expressed as a number from 1 to 12. DD is
! 2181: the day of the month, counting from 1. HH is the hour, from zero to
! 2182: 23. MM is the minute and SS is the second. The time is always in
! 2183: Coordinated Universal Time (UTC), not local time.
! 2184: .RE
! 2185: .PP
! 2186: The
! 2187: .I dynamic-bootp-lease-length
! 2188: statement
! 2189: .RS 0.25i
! 2190: .PP
! 2191: .B dynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR
! 2192: .PP
! 2193: The \fIdynamic-bootp-lease-length\fR statement is used to set the
! 2194: length of leases dynamically assigned to BOOTP clients. At some
! 2195: sites, it may be possible to assume that a lease is no longer in
! 2196: use if its holder has not used BOOTP or DHCP to get its address within
! 2197: a certain time period. The period is specified in \fIlength\fR as a
! 2198: number of seconds. If a client reboots using BOOTP during the
! 2199: timeout period, the lease duration is reset to \fIlength\fR, so a
! 2200: BOOTP client that boots frequently enough will never lose its lease.
! 2201: Needless to say, this parameter should be adjusted with extreme
! 2202: caution.
! 2203: .RE
! 2204: .PP
! 2205: The
! 2206: .I filename
! 2207: statement
! 2208: .RS 0.25i
! 2209: .PP
! 2210: .B filename\fR \fB"\fR\fIfilename\fR\fB";\fR
! 2211: .PP
! 2212: The \fIfilename\fR statement can be used to specify the name of the
! 2213: initial boot file which is to be loaded by a client. The
! 2214: .I filename
! 2215: should be a filename recognizable to whatever file transfer protocol
! 2216: the client can be expected to use to load the file.
! 2217: .RE
! 2218: .PP
! 2219: The
! 2220: .I fixed-address
! 2221: declaration
! 2222: .RS 0.25i
! 2223: .PP
! 2224: .B fixed-address address\fR [\fB,\fR \fIaddress\fR ... ]\fB;\fR
! 2225: .PP
! 2226: The \fIfixed-address\fR declaration is used to assign one or more fixed
! 2227: IP addresses to a client. It should only appear in a \fIhost\fR
! 2228: declaration. If more than one address is supplied, then when the
! 2229: client boots, it will be assigned the address that corresponds to the
! 2230: network on which it is booting. If none of the addresses in the
! 2231: \fIfixed-address\fR statement are valid for the network to which the client
! 2232: is connected, that client will not match the \fIhost\fR declaration
! 2233: containing that \fIfixed-address\fR declaration. Each \fIaddress\fR
! 2234: in the \fIfixed-address\fR declaration should be either an IP address or
! 2235: a domain name that resolves to one or more IP addresses.
! 2236: .RE
! 2237: .PP
! 2238: The
! 2239: .I fixed-address6
! 2240: declaration
! 2241: .RS 0.25i
! 2242: .PP
! 2243: .B fixed-address6 ip6-address\fR ;\fR
! 2244: .PP
! 2245: The \fIfixed-address6\fR declaration is used to assign a fixed
! 2246: IPv6 addresses to a client. It should only appear in a \fIhost\fR
! 2247: declaration.
! 2248: .RE
! 2249: .PP
! 2250: The
! 2251: .I get-lease-hostnames
! 2252: statement
! 2253: .RS 0.25i
! 2254: .PP
! 2255: .B get-lease-hostnames\fR \fIflag\fR\fB;\fR
! 2256: .PP
! 2257: The \fIget-lease-hostnames\fR statement is used to tell dhcpd whether
! 2258: or not to look up the domain name corresponding to the IP address of
! 2259: each address in the lease pool and use that address for the DHCP
! 2260: \fIhostname\fR option. If \fIflag\fR is true, then this lookup is
! 2261: done for all addresses in the current scope. By default, or if
! 2262: \fIflag\fR is false, no lookups are done.
! 2263: .RE
! 2264: .PP
! 2265: The
! 2266: .I hardware
! 2267: statement
! 2268: .RS 0.25i
! 2269: .PP
! 2270: .B hardware \fIhardware-type hardware-address\fB;\fR
! 2271: .PP
! 2272: In order for a BOOTP client to be recognized, its network hardware
! 2273: address must be declared using a \fIhardware\fR clause in the
! 2274: .I host
! 2275: statement.
! 2276: .I hardware-type
! 2277: must be the name of a physical hardware interface type. Currently,
! 2278: only the
! 2279: .B ethernet
! 2280: and
! 2281: .B token-ring
! 2282: types are recognized, although support for a
! 2283: .B fddi
! 2284: hardware type (and others) would also be desirable.
! 2285: The
! 2286: .I hardware-address
! 2287: should be a set of hexadecimal octets (numbers from 0 through ff)
! 2288: separated by colons. The \fIhardware\fR statement may also be used
! 2289: for DHCP clients.
! 2290: .RE
! 2291: .PP
! 2292: The
! 2293: .I host-identifier option
! 2294: statement
! 2295: .RS 0.25i
! 2296: .PP
! 2297: .B host-identifier option \fIoption-name option-data\fB;\fR
! 2298: .PP
! 2299: This identifies a DHCPv6 client in a
! 2300: .I host
! 2301: statement.
! 2302: .I option-name
! 2303: is any option, and
! 2304: .I option-data
! 2305: is the value for the option that the client will send. The
! 2306: .I option-data
! 2307: must be a constant value.
! 2308: .RE
! 2309: .PP
! 2310: The
! 2311: .I infinite-is-reserved
! 2312: statement
! 2313: .RS 0.25i
! 2314: .PP
! 2315: .B infinite-is-reserved \fIflag\fB;\fR
! 2316: .PP
! 2317: ISC DHCP now supports \'reserved\' leases. See the section on RESERVED LEASES
! 2318: below. If this \fIflag\fR is on, the server will automatically reserve leases
! 2319: allocated to clients which requested an infinite (0xffffffff) lease-time.
! 2320: .PP
! 2321: The default is off.
! 2322: .RE
! 2323: .PP
! 2324: The
! 2325: .I lease-file-name
! 2326: statement
! 2327: .RS 0.25i
! 2328: .PP
! 2329: .B lease-file-name \fIname\fB;\fR
! 2330: .PP
! 2331: .I Name
! 2332: should be the name of the DHCP server's lease file. By default, this
! 2333: is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer
! 2334: scope of the configuration file - if it appears in some other scope,
! 2335: it will have no effect. Furthermore, it has no effect if overridden
! 2336: by the
! 2337: .B -lf
! 2338: flag or the
! 2339: .B PATH_DHCPD_DB
! 2340: environment variable.
! 2341: .RE
! 2342: .PP
! 2343: The
! 2344: .I limit-addrs-per-ia
! 2345: statement
! 2346: .RS 0.25i
! 2347: .PP
! 2348: .B limit-addrs-per-ia \fInumber\fB;\fR
! 2349: .PP
! 2350: By default, the DHCPv6 server will limit clients to one IAADDR per IA
! 2351: option, meaning one address. If you wish to permit clients to hang onto
! 2352: multiple addresses at a time, configure a larger \fInumber\fR here.
! 2353: .PP
! 2354: Note that there is no present method to configure the server to forcibly
! 2355: configure the client with one IP address per each subnet on a shared network.
! 2356: This is left to future work.
! 2357: .RE
! 2358: .PP
! 2359: The
! 2360: .I dhcpv6-lease-file-name
! 2361: statement
! 2362: .RS 0.25i
! 2363: .PP
! 2364: .B dhcpv6-lease-file-name \fIname\fB;\fR
! 2365: .PP
! 2366: .I Name
! 2367: is the name of the lease file to use if and only if the server is running
! 2368: in DHCPv6 mode. By default, this is DBDIR/dhcpd6.leases. This statement,
! 2369: like
! 2370: .I lease-file-name,
! 2371: \fBmust\fR appear in the outer scope of the configuration file. It
! 2372: has no effect if overridden by the
! 2373: .B -lf
! 2374: flag or the
! 2375: .B PATH_DHCPD6_DB
! 2376: environment variable. If
! 2377: .I dhcpv6-lease-file-name
! 2378: is not specified, but
! 2379: .I lease-file-name
! 2380: is, the latter value will be used.
! 2381: .RE
! 2382: .PP
! 2383: The
! 2384: .I local-port
! 2385: statement
! 2386: .RS 0.25i
! 2387: .PP
! 2388: .B local-port \fIport\fB;\fR
! 2389: .PP
! 2390: This statement causes the DHCP server to listen for DHCP requests on
! 2391: the UDP port specified in \fIport\fR, rather than on port 67.
! 2392: .RE
! 2393: .PP
! 2394: The
! 2395: .I local-address
! 2396: statement
! 2397: .RS 0.25i
! 2398: .PP
! 2399: .B local-address \fIaddress\fB;\fR
! 2400: .PP
! 2401: This statement causes the DHCP server to listen for DHCP requests sent
! 2402: to the specified \fIaddress\fR, rather than requests sent to all addresses.
! 2403: Since serving directly attached DHCP clients implies that the server must
! 2404: respond to requests sent to the all-ones IP address, this option cannot be
! 2405: used if clients are on directly attached networks...it is only realistically
! 2406: useful for a server whose only clients are reached via unicasts, such as via
! 2407: DHCP relay agents.
! 2408: .PP
! 2409: Note: This statement is only effective if the server was compiled using
! 2410: the USE_SOCKETS #define statement, which is default on a small number of
! 2411: operating systems, and must be explicitly chosen at compile-time for all
! 2412: others. You can be sure if your server is compiled with USE_SOCKETS if
! 2413: you see lines of this format at startup:
! 2414: .PP
! 2415: Listening on Socket/eth0
! 2416: .PP
! 2417: Note also that since this bind()s all DHCP sockets to the specified
! 2418: address, that only one address may be supported in a daemon at a given
! 2419: time.
! 2420: .RE
! 2421: .PP
! 2422: The
! 2423: .I log-facility
! 2424: statement
! 2425: .RS 0.25i
! 2426: .PP
! 2427: .B log-facility \fIfacility\fB;\fR
! 2428: .PP
! 2429: This statement causes the DHCP server to do all of its logging on the
! 2430: specified log facility once the dhcpd.conf file has been read. By
! 2431: default the DHCP server logs to the daemon facility. Possible log
! 2432: facilities include auth, authpriv, cron, daemon, ftp, kern, lpr, mail,
! 2433: mark, news, ntp, security, syslog, user, uucp, and local0 through
! 2434: local7. Not all of these facilities are available on all systems,
! 2435: and there may be other facilities available on other systems.
! 2436: .PP
! 2437: In addition to setting this value, you may need to modify your
! 2438: .I syslog.conf
! 2439: file to configure logging of the DHCP server. For example, you might
! 2440: add a line like this:
! 2441: .PP
! 2442: .nf
! 2443: local7.debug /var/log/dhcpd.log
! 2444: .fi
! 2445: .PP
! 2446: The syntax of the \fIsyslog.conf\fR file may be different on some
! 2447: operating systems - consult the \fIsyslog.conf\fR manual page to be
! 2448: sure. To get syslog to start logging to the new file, you must first
! 2449: create the file with correct ownership and permissions (usually, the
! 2450: same owner and permissions of your /var/log/messages or
! 2451: /usr/adm/messages file should be fine) and send a SIGHUP to syslogd.
! 2452: Some systems support log rollover using a shell script or program
! 2453: called newsyslog or logrotate, and you may be able to configure this
! 2454: as well so that your log file doesn't grow uncontrollably.
! 2455: .PP
! 2456: Because the \fIlog-facility\fR setting is controlled by the dhcpd.conf
! 2457: file, log messages printed while parsing the dhcpd.conf file or before
! 2458: parsing it are logged to the default log facility. To prevent this,
! 2459: see the README file included with this distribution, which describes
! 2460: how to change the default log facility. When this parameter is used,
! 2461: the DHCP server prints its startup message a second time after parsing
! 2462: the configuration file, so that the log will be as complete as
! 2463: possible.
! 2464: .RE
! 2465: .PP
! 2466: The
! 2467: .I max-lease-time
! 2468: statement
! 2469: .RS 0.25i
! 2470: .PP
! 2471: .B max-lease-time \fItime\fR\fB;\fR
! 2472: .PP
! 2473: .I Time
! 2474: should be the maximum length in seconds that will be assigned to a
! 2475: lease.
! 2476: If not defined, the default maximum lease time is 86400.
! 2477: The only exception to this is that Dynamic BOOTP lease
! 2478: lengths, which are not specified by the client, are not limited by
! 2479: this maximum.
! 2480: .RE
! 2481: .PP
! 2482: The
! 2483: .I min-lease-time
! 2484: statement
! 2485: .RS 0.25i
! 2486: .PP
! 2487: .B min-lease-time \fItime\fR\fB;\fR
! 2488: .PP
! 2489: .I Time
! 2490: should be the minimum length in seconds that will be assigned to a
! 2491: lease.
! 2492: The default is the minimum of 300 seconds or
! 2493: \fBmax-lease-time\fR.
! 2494: .RE
! 2495: .PP
! 2496: The
! 2497: .I min-secs
! 2498: statement
! 2499: .RS 0.25i
! 2500: .PP
! 2501: .B min-secs \fIseconds\fR\fB;\fR
! 2502: .PP
! 2503: .I Seconds
! 2504: should be the minimum number of seconds since a client began trying to
! 2505: acquire a new lease before the DHCP server will respond to its request.
! 2506: The number of seconds is based on what the client reports, and the maximum
! 2507: value that the client can report is 255 seconds. Generally, setting this
! 2508: to one will result in the DHCP server not responding to the client's first
! 2509: request, but always responding to its second request.
! 2510: .PP
! 2511: This can be used
! 2512: to set up a secondary DHCP server which never offers an address to a client
! 2513: until the primary server has been given a chance to do so. If the primary
! 2514: server is down, the client will bind to the secondary server, but otherwise
! 2515: clients should always bind to the primary. Note that this does not, by
! 2516: itself, permit a primary server and a secondary server to share a pool of
! 2517: dynamically-allocatable addresses.
! 2518: .RE
! 2519: .PP
! 2520: The
! 2521: .I next-server
! 2522: statement
! 2523: .RS 0.25i
! 2524: .PP
! 2525: .B next-server\fR \fIserver-name\fR\fB;\fR
! 2526: .PP
! 2527: The \fInext-server\fR statement is used to specify the host address of
! 2528: the server from which the initial boot file (specified in the
! 2529: \fIfilename\fR statement) is to be loaded. \fIServer-name\fR should
! 2530: be a numeric IP address or a domain name.
! 2531: .RE
! 2532: .PP
! 2533: The
! 2534: .I omapi-port
! 2535: statement
! 2536: .RS 0.25i
! 2537: .PP
! 2538: .B omapi-port\fR \fIport\fR\fB;\fR
! 2539: .PP
! 2540: The \fIomapi-port\fR statement causes the DHCP server to listen for
! 2541: OMAPI connections on the specified port. This statement is required
! 2542: to enable the OMAPI protocol, which is used to examine and modify the
! 2543: state of the DHCP server as it is running.
! 2544: .RE
! 2545: .PP
! 2546: The
! 2547: .I one-lease-per-client
! 2548: statement
! 2549: .RS 0.25i
! 2550: .PP
! 2551: .B one-lease-per-client \fIflag\fR\fB;\fR
! 2552: .PP
! 2553: If this flag is enabled, whenever a client sends a DHCPREQUEST for a
! 2554: particular lease, the server will automatically free any other leases
! 2555: the client holds. This presumes that when the client sends a
! 2556: DHCPREQUEST, it has forgotten any lease not mentioned in the
! 2557: DHCPREQUEST - i.e., the client has only a single network interface
! 2558: .I and
! 2559: it does not remember leases it's holding on networks to which it is
! 2560: not currently attached. Neither of these assumptions are guaranteed
! 2561: or provable, so we urge caution in the use of this statement.
! 2562: .RE
! 2563: .PP
! 2564: The
! 2565: .I pid-file-name
! 2566: statement
! 2567: .RS 0.25i
! 2568: .PP
! 2569: .B pid-file-name
! 2570: .I name\fR\fB;\fR
! 2571: .PP
! 2572: .I Name
! 2573: should be the name of the DHCP server's process ID file. This is the
! 2574: file in which the DHCP server's process ID is stored when the server
! 2575: starts. By default, this is RUNDIR/dhcpd.pid. Like the
! 2576: .I lease-file-name
! 2577: statement, this statement must appear in the outer scope
! 2578: of the configuration file. It has no effect if overridden by the
! 2579: .B -pf
! 2580: flag or the
! 2581: .B PATH_DHCPD_PID
! 2582: environment variable.
! 2583: .PP
! 2584: The
! 2585: .I dhcpv6-pid-file-name
! 2586: statement
! 2587: .RS 0.25i
! 2588: .PP
! 2589: .B dhcpv6-pid-file-name \fIname\fB;\fR
! 2590: .PP
! 2591: .I Name
! 2592: is the name of the pid file to use if and only if the server is running
! 2593: in DHCPv6 mode. By default, this is DBDIR/dhcpd6.pid. This statement,
! 2594: like
! 2595: .I pid-file-name,
! 2596: \fBmust\fR appear in the outer scope of the configuration file. It
! 2597: has no effect if overridden by the
! 2598: .B -pf
! 2599: flag or the
! 2600: .B PATH_DHCPD6_PID
! 2601: environment variable. If
! 2602: .I dhcpv6-pid-file-name
! 2603: is not specified, but
! 2604: .I pid-file-name
! 2605: is, the latter value will be used.
! 2606: .RE
! 2607: .PP
! 2608: The
! 2609: .I ping-check
! 2610: statement
! 2611: .RS 0.25i
! 2612: .PP
! 2613: .B ping-check
! 2614: .I flag\fR\fB;\fR
! 2615: .PP
! 2616: When the DHCP server is considering dynamically allocating an IP
! 2617: address to a client, it first sends an ICMP Echo request (a \fIping\fR)
! 2618: to the address being assigned. It waits for a second, and if no
! 2619: ICMP Echo response has been heard, it assigns the address. If a
! 2620: response \fIis\fR heard, the lease is abandoned, and the server does
! 2621: not respond to the client.
! 2622: .PP
! 2623: This \fIping check\fR introduces a default one-second delay in responding
! 2624: to DHCPDISCOVER messages, which can be a problem for some clients. The
! 2625: default delay of one second may be configured using the ping-timeout
! 2626: parameter. The ping-check configuration parameter can be used to control
! 2627: checking - if its value is false, no ping check is done.
! 2628: .RE
! 2629: .PP
! 2630: The
! 2631: .I ping-timeout
! 2632: statement
! 2633: .RS 0.25i
! 2634: .PP
! 2635: .B ping-timeout
! 2636: .I seconds\fR\fB;\fR
! 2637: .PP
! 2638: If the DHCP server determined it should send an ICMP echo request (a
! 2639: \fIping\fR) because the ping-check statement is true, ping-timeout allows
! 2640: you to configure how many seconds the DHCP server should wait for an
! 2641: ICMP Echo response to be heard, if no ICMP Echo response has been received
! 2642: before the timeout expires, it assigns the address. If a response \fIis\fR
! 2643: heard, the lease is abandoned, and the server does not respond to the client.
! 2644: If no value is set, ping-timeout defaults to 1 second.
! 2645: .RE
! 2646: .PP
! 2647: The
! 2648: .I preferred-lifetime
! 2649: statement
! 2650: .RS 0.25i
! 2651: .PP
! 2652: .B preferred-lifetime
! 2653: .I seconds\fR\fB;\fR
! 2654: .PP
! 2655: IPv6 addresses have \'valid\' and \'preferred\' lifetimes. The valid lifetime
! 2656: determines at what point at lease might be said to have expired, and is no
! 2657: longer useable. A preferred lifetime is an advisory condition to help
! 2658: applications move off of the address and onto currently valid addresses
! 2659: (should there still be any open TCP sockets or similar).
! 2660: .PP
! 2661: The preferred lifetime defaults to the renew+rebind timers, or 3/4 the
! 2662: default lease time if none were specified.
! 2663: .RE
! 2664: .PP
! 2665: The
! 2666: .I remote-port
! 2667: statement
! 2668: .RS 0.25i
! 2669: .PP
! 2670: .B remote-port \fIport\fB;\fR
! 2671: .PP
! 2672: This statement causes the DHCP server to transmit DHCP responses to DHCP
! 2673: clients upon the UDP port specified in \fIport\fR, rather than on port 68.
! 2674: In the event that the UDP response is transmitted to a DHCP Relay, the
! 2675: server generally uses the \fBlocal-port\fR configuration value. Should the
! 2676: DHCP Relay happen to be addressed as 127.0.0.1, however, the DHCP Server
! 2677: transmits its response to the \fBremote-port\fR configuration value. This
! 2678: is generally only useful for testing purposes, and this configuration value
! 2679: should generally not be used.
! 2680: .RE
! 2681: .PP
! 2682: The
! 2683: .I server-identifier
! 2684: statement
! 2685: .RS 0.25i
! 2686: .PP
! 2687: .B server-identifier \fIhostname\fR\fB;\fR
! 2688: .PP
! 2689: The server-identifier statement can be used to define the value that
! 2690: is sent in the DHCP Server Identifier option for a given scope. The
! 2691: value specified \fBmust\fR be an IP address for the DHCP server, and
! 2692: must be reachable by all clients served by a particular scope.
! 2693: .PP
! 2694: The use of the server-identifier statement is not recommended - the only
! 2695: reason to use it is to force a value other than the default value to be
! 2696: sent on occasions where the default value would be incorrect. The default
! 2697: value is the first IP address associated with the physical network interface
! 2698: on which the request arrived.
! 2699: .PP
! 2700: The usual case where the
! 2701: \fIserver-identifier\fR statement needs to be sent is when a physical
! 2702: interface has more than one IP address, and the one being sent by default
! 2703: isn't appropriate for some or all clients served by that interface.
! 2704: Another common case is when an alias is defined for the purpose of
! 2705: having a consistent IP address for the DHCP server, and it is desired
! 2706: that the clients use this IP address when contacting the server.
! 2707: .PP
! 2708: Supplying a value for the dhcp-server-identifier option is equivalent
! 2709: to using the server-identifier statement.
! 2710: .RE
! 2711: .PP
! 2712: The
! 2713: .I server-duid
! 2714: statement
! 2715: .RS 0.25i
! 2716: .PP
! 2717: .B server-duid \fILLT\fR [ \fIhardware-type\fR \fItimestamp\fR \fIhardware-address\fR ] \fB;\fR
! 2718:
! 2719: .B server-duid \fIEN\fR \fIenterprise-number\fR \fIenterprise-identifier\fR \fB;\fR
! 2720:
! 2721: .B server-duid \fILL\fR [ \fIhardware-type\fR \fIhardware-address\fR ] \fB;\fR
! 2722: .PP
! 2723: The server-duid statement configures the server DUID. You may pick either
! 2724: LLT (link local address plus time), EN (enterprise), or LL (link local).
! 2725: .PP
! 2726: If you choose LLT or LL, you may specify the exact contents of the DUID.
! 2727: Otherwise the server will generate a DUID of the specified type.
! 2728: .PP
! 2729: If you choose EN, you must include the enterprise number and the
! 2730: enterprise-identifier.
! 2731: .PP
! 2732: The default server-duid type is LLT.
! 2733: .RE
! 2734: .PP
! 2735: The
! 2736: .I server-name
! 2737: statement
! 2738: .RS 0.25i
! 2739: .PP
! 2740: .B server-name "\fIname\fB";\fR
! 2741: .PP
! 2742: The \fIserver-name\fR statement can be used to inform the client of
! 2743: the name of the server from which it is booting. \fIName\fR should
! 2744: be the name that will be provided to the client.
! 2745: .RE
! 2746: .PP
! 2747: The
! 2748: .I site-option-space
! 2749: statement
! 2750: .RS 0.25i
! 2751: .PP
! 2752: .B site-option-space "\fIname\fB";\fR
! 2753: .PP
! 2754: The \fIsite-option-space\fR statement can be used to determine from
! 2755: what option space site-local options will be taken. This can be used
! 2756: in much the same way as the \fIvendor-option-space\fR statement.
! 2757: Site-local options in DHCP are those options whose numeric codes are
! 2758: greater than 224. These options are intended for site-specific
! 2759: uses, but are frequently used by vendors of embedded hardware that
! 2760: contains DHCP clients. Because site-specific options are allocated
! 2761: on an ad hoc basis, it is quite possible that one vendor's DHCP client
! 2762: might use the same option code that another vendor's client uses, for
! 2763: different purposes. The \fIsite-option-space\fR option can be used
! 2764: to assign a different set of site-specific options for each such
! 2765: vendor, using conditional evaluation (see \fBdhcp-eval (5)\fR for
! 2766: details).
! 2767: .RE
! 2768: .PP
! 2769: The
! 2770: .I stash-agent-options
! 2771: statement
! 2772: .RS 0.25i
! 2773: .PP
! 2774: .B stash-agent-options \fIflag\fB;\fR
! 2775: .PP
! 2776: If the \fIstash-agent-options\fR parameter is true for a given client,
! 2777: the server will record the relay agent information options sent during
! 2778: the client's initial DHCPREQUEST message when the client was in the
! 2779: SELECTING state and behave as if those options are included in all
! 2780: subsequent DHCPREQUEST messages sent in the RENEWING state. This
! 2781: works around a problem with relay agent information options, which is
! 2782: that they usually not appear in DHCPREQUEST messages sent by the
! 2783: client in the RENEWING state, because such messages are unicast
! 2784: directly to the server and not sent through a relay agent.
! 2785: .RE
! 2786: .PP
! 2787: The
! 2788: .I update-conflict-detection
! 2789: statement
! 2790: .RS 0.25i
! 2791: .PP
! 2792: .B update-conflict-detection \fIflag\fB;\fR
! 2793: .PP
! 2794: If the \fIupdate-conflict-detection\fR parameter is true, the server will
! 2795: perform standard DHCID multiple-client, one-name conflict detection. If
! 2796: the parameter has been set false, the server will skip this check and
! 2797: instead simply tear down any previous bindings to install the new
! 2798: binding without question. The default is true.
! 2799: .RE
! 2800: .PP
! 2801: The
! 2802: .I update-optimization
! 2803: statement
! 2804: .RS 0.25i
! 2805: .PP
! 2806: .B update-optimization \fIflag\fB;\fR
! 2807: .PP
! 2808: If the \fIupdate-optimization\fR parameter is false for a given client,
! 2809: the server will attempt a DNS update for that client each time the
! 2810: client renews its lease, rather than only attempting an update when it
! 2811: appears to be necessary. This will allow the DNS to heal from
! 2812: database inconsistencies more easily, but the cost is that the DHCP
! 2813: server must do many more DNS updates. We recommend leaving this option
! 2814: enabled, which is the default. This option only affects the behavior of
! 2815: the interim DNS update scheme, and has no effect on the ad-hoc DNS update
! 2816: scheme. If this parameter is not specified, or is true, the DHCP server
! 2817: will only update when the client information changes, the client gets a
! 2818: different lease, or the client's lease expires.
! 2819: .RE
! 2820: .PP
! 2821: The
! 2822: .I update-static-leases
! 2823: statement
! 2824: .RS 0.25i
! 2825: .PP
! 2826: .B update-static-leases \fIflag\fB;\fR
! 2827: .PP
! 2828: The \fIupdate-static-leases\fR flag, if enabled, causes the DHCP
! 2829: server to do DNS updates for clients even if those clients are being
! 2830: assigned their IP address using a \fIfixed-address\fR statement - that
! 2831: is, the client is being given a static assignment. This can only
! 2832: work with the \fIinterim\fR DNS update scheme. It is not
! 2833: recommended because the DHCP server has no way to tell that the update
! 2834: has been done, and therefore will not delete the record when it is not
! 2835: in use. Also, the server must attempt the update each time the
! 2836: client renews its lease, which could have a significant performance
! 2837: impact in environments that place heavy demands on the DHCP server.
! 2838: .RE
! 2839: .PP
! 2840: The
! 2841: .I use-host-decl-names
! 2842: statement
! 2843: .RS 0.25i
! 2844: .PP
! 2845: .B use-host-decl-names \fIflag\fB;\fR
! 2846: .PP
! 2847: If the \fIuse-host-decl-names\fR parameter is true in a given scope,
! 2848: then for every host declaration within that scope, the name provided
! 2849: for the host declaration will be supplied to the client as its
! 2850: hostname. So, for example,
! 2851: .PP
! 2852: .nf
! 2853: group {
! 2854: use-host-decl-names on;
! 2855:
! 2856: host joe {
! 2857: hardware ethernet 08:00:2b:4c:29:32;
! 2858: fixed-address joe.fugue.com;
! 2859: }
! 2860: }
! 2861:
! 2862: is equivalent to
! 2863:
! 2864: host joe {
! 2865: hardware ethernet 08:00:2b:4c:29:32;
! 2866: fixed-address joe.fugue.com;
! 2867: option host-name "joe";
! 2868: }
! 2869: .fi
! 2870: .PP
! 2871: An \fIoption host-name\fR statement within a host declaration will
! 2872: override the use of the name in the host declaration.
! 2873: .PP
! 2874: It should be noted here that most DHCP clients completely ignore the
! 2875: host-name option sent by the DHCP server, and there is no way to
! 2876: configure them not to do this. So you generally have a choice of
! 2877: either not having any hostname to client IP address mapping that the
! 2878: client will recognize, or doing DNS updates. It is beyond
! 2879: the scope of this document to describe how to make this
! 2880: determination.
! 2881: .RE
! 2882: .PP
! 2883: The
! 2884: .I use-lease-addr-for-default-route
! 2885: statement
! 2886: .RS 0.25i
! 2887: .PP
! 2888: .B use-lease-addr-for-default-route \fIflag\fR\fB;\fR
! 2889: .PP
! 2890: If the \fIuse-lease-addr-for-default-route\fR parameter is true in a
! 2891: given scope, then instead of sending the value specified in the
! 2892: routers option (or sending no value at all), the IP address of the
! 2893: lease being assigned is sent to the client. This supposedly causes
! 2894: Win95 machines to ARP for all IP addresses, which can be helpful if
! 2895: your router is configured for proxy ARP. The use of this feature is
! 2896: not recommended, because it won't work for many DHCP clients.
! 2897: .RE
! 2898: .PP
! 2899: The
! 2900: .I vendor-option-space
! 2901: statement
! 2902: .RS 0.25i
! 2903: .PP
! 2904: .B vendor-option-space \fIstring\fR\fB;\fR
! 2905: .PP
! 2906: The \fIvendor-option-space\fR parameter determines from what option
! 2907: space vendor options are taken. The use of this configuration
! 2908: parameter is illustrated in the \fBdhcp-options(5)\fR manual page, in
! 2909: the \fIVENDOR ENCAPSULATED OPTIONS\fR section.
! 2910: .RE
! 2911: .SH SETTING PARAMETER VALUES USING EXPRESSIONS
! 2912: Sometimes it's helpful to be able to set the value of a DHCP server
! 2913: parameter based on some value that the client has sent. To do this,
! 2914: you can use expression evaluation. The
! 2915: .B dhcp-eval(5)
! 2916: manual page describes how to write expressions. To assign the result
! 2917: of an evaluation to an option, define the option as follows:
! 2918: .nf
! 2919: .sp 1
! 2920: \fImy-parameter \fB= \fIexpression \fB;\fR
! 2921: .fi
! 2922: .PP
! 2923: For example:
! 2924: .nf
! 2925: .sp 1
! 2926: ddns-hostname = binary-to-ascii (16, 8, "-",
! 2927: substring (hardware, 1, 6));
! 2928: .fi
! 2929: .RE
! 2930: .SH RESERVED LEASES
! 2931: It's often useful to allocate a single address to a single client, in
! 2932: approximate perpetuity. Host statements with \fBfixed-address\fR clauses
! 2933: exist to a certain extent to serve this purpose, but because host statements
! 2934: are intended to approximate \'static configuration\', they suffer from not
! 2935: being referenced in a littany of other Server Services, such as dynamic DNS,
! 2936: failover, \'on events\' and so forth.
! 2937: .PP
! 2938: If a standard dynamic lease, as from any range statement, is marked
! 2939: \'reserved\', then the server will only allocate this lease to the client it
! 2940: is identified by (be that by client identifier or hardware address).
! 2941: .PP
! 2942: In practice, this means that the lease follows the normal state engine, enters
! 2943: ACTIVE state when the client is bound to it, expires, or is released, and any
! 2944: events or services that would normally be supplied during these events are
! 2945: processed normally, as with any other dynamic lease. The only difference
! 2946: is that failover servers treat reserved leases as special when they enter
! 2947: the FREE or BACKUP states - each server applies the lease into the state it
! 2948: may allocate from - and the leases are not placed on the queue for allocation
! 2949: to other clients. Instead they may only be \'found\' by client identity. The
! 2950: result is that the lease is only offered to the returning client.
! 2951: .PP
! 2952: Care should probably be taken to ensure that the client only has one lease
! 2953: within a given subnet that it is identified by.
! 2954: .PP
! 2955: Leases may be set \'reserved\' either through OMAPI, or through the
! 2956: \'infinite-is-reserved\' configuration option (if this is applicable to your
! 2957: environment and mixture of clients).
! 2958: .PP
! 2959: It should also be noted that leases marked \'reserved\' are effectively treated
! 2960: the same as leases marked \'bootp\'.
! 2961: .RE
! 2962: .SH REFERENCE: OPTION STATEMENTS
! 2963: DHCP option statements are documented in the
! 2964: .B dhcp-options(5)
! 2965: manual page.
! 2966: .SH REFERENCE: EXPRESSIONS
! 2967: Expressions used in DHCP option statements and elsewhere are
! 2968: documented in the
! 2969: .B dhcp-eval(5)
! 2970: manual page.
! 2971: .SH SEE ALSO
! 2972: dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132, RFC2131.
! 2973: .SH AUTHOR
! 2974: .B dhcpd.conf(5)
! 2975: was written by Ted Lemon
! 2976: under a contract with Vixie Labs. Funding
! 2977: for this project was provided by Internet Systems Consortium.
! 2978: Information about Internet Systems Consortium can be found at
! 2979: .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