MAN page from Mandrake 9.X dhcp-server-3.0-1.rc12.2mdk.i586.rpm
dhcpd.conf
Section: File Formats (5)
Index NAME
dhcpd.conf - dhcpd configuration file
DESCRIPTION
The dhcpd.conf file contains configuration information for
dhcpd,the Internet Software Consortium DHCP Server.
The dhcpd.conf file is a free-form ASCII text file. It is parsed bythe recursive-descent parser built into dhcpd. The file may containextra tabs and newlines for formatting purposes. Keywords in the fileare case-insensitive. Comments may be placed anywhere within thefile (except within quotes). Comments begin with the # character andend at the end of the line.
The file essentially consists of a list of statements. Statementsfall into two broad categories - parameters and declarations.
Parameter statements either say how to do something (e.g., how long alease to offer), whether to do something (e.g., should dhcpd provideaddresses to unknown clients), or what parameters to provide to theclient (e.g., use gateway 220.177.244.7).
Declarations are used to describe the topology of thenetwork, to describe clients on the network, to provide addresses thatcan be assigned to clients, or to apply a group of parameters to agroup of declarations. In any group of parameters and declarations,all parameters must be specified before any declarations which dependon those parameters may be specified.
Declarations about network topology include the shared-networkand the subnet declarations. If clients on a subnet are to beassigned addressesdynamically, a range declaration must appear within thesubnet declaration. For clients with statically assignedaddresses, or for installations where only known clients will beserved, each such client must have a host declaration. Ifparameters are to be applied to a group of declarations which are notrelated strictly on a per-subnet basis, the group declarationcan be used.
For every subnet which will be served, and for every subnetto which the dhcp server is connected, there must be one subnetdeclaration, which tells dhcpd how to recognize that an address is onthat subnet. A subnet declaration is required for each subneteven if no addresses will be dynamically allocated on that subnet.
Some installations have physical networks on which more than one IPsubnet operates. For example, if there is a site-wide requirementthat 8-bit subnet masks be used, but a department with a singlephysical ethernet network expands to the point where it has more than254 nodes, it may be necessary to run two 8-bit subnets on the sameethernet until such time as a new physical network can be added. Inthis case, the subnet declarations for these two networks must beenclosed in a shared-network declaration.
Some sites may have departments which have clients on more than onesubnet, but it may be desirable to offer those clients a uniform setof parameters which are different than what would be offered toclients from other departments on the same subnet. For clients whichwill be declared explicitly with host declarations, thesedeclarations can be enclosed in a group declaration along withthe parameters which are common to that department. For clientswhose addresses will be dynamically assigned, class declarations andconditional declarations may be used to group parameter assignmentsbased on information the client sends.
When a client is to be booted, its boot parameters are determined byconsulting that client's host declaration (if any), and thenconsulting any class declarations matching the client,followed by the pool, subnet and shared-networkdeclarations for the IP address assigned to the client. Each ofthese declarations itself appears within a lexical scope, and alldeclarations at less specific lexical scopes are also consulted forclient option declarations. Scopes are never consideredtwice, and if parameters are declared in more than one scope, theparameter declared in the most specific scope is the one that isused.
When dhcpd tries to find a host declaration for a client, itfirst looks for a host declaration which has afixed-address declaration that lists an IP address that is validfor the subnet or shared network on which the client is booting. Ifit doesn't find any such entry, it tries to find an entry which hasno fixed-address declaration.
EXAMPLES
A typical dhcpd.conf file will look something like this:
global parameters...subnet 204.254.239.0 netmask 255.255.255.224 { subnet-specific parameters... range 204.254.239.10 204.254.239.30;}subnet 204.254.239.32 netmask 255.255.255.224 { subnet-specific parameters... range 204.254.239.42 204.254.239.62;}subnet 204.254.239.64 netmask 255.255.255.224 { subnet-specific parameters... range 204.254.239.74 204.254.239.94;}group { group-specific parameters... host zappo.test.isc.org { host-specific parameters... } host beppo.test.isc.org { host-specific parameters... } host harpo.test.isc.org { host-specific parameters... }}Figure 1
Notice that at the beginning of the file, there's a placefor global parameters. These might be things like the organization'sdomain name, the addresses of the name servers (if they are common tothe entire organization), and so on. So, for example:
option domain-name "isc.org"; option domain-name-servers ns1.isc.org, ns2.isc.org;Figure 2
As you can see in Figure 2, you can specify host addresses inparameters using their domain names rather than their numeric IPaddresses. If a given hostname resolves to more than one IP address(for example, if that host has two ethernet interfaces), then wherepossible, both addresses are supplied to the client.
The most obvious reason for having subnet-specific parameters asshown in Figure 1 is that each subnet, of necessity, has its ownrouter. So for the first subnet, for example, there should besomething like:
option routers 204.254.239.1;
Note that the address here is specified numerically. This is notrequired - if you have a different domain name for each interface onyour router, it's perfectly legitimate to use the domain name for thatinterface instead of the numeric address. However, in many casesthere may be only one domain name for all of a router's IP addresses, andit would not be appropriate to use that name here.
In Figure 1 there is also a group statement, which providescommon parameters for a set of three hosts - zappo, beppo and harpo.As you can see, these hosts are all in the test.isc.org domain, so itmight make sense for a group-specific parameter to override the domainname supplied to these hosts:
option domain-name "test.isc.org";
Also, given the domain they're in, these are probably test machines.If we wanted to test the DHCP leasing mechanism, we might set thelease timeout somewhat shorter than the default:
max-lease-time 120; default-lease-time 120;
You may have noticed that while some parameters start with theoption keyword, some do not. Parameters starting with theoption keyword correspond to actual DHCP options, whileparameters that do not start with the option keyword either controlthe behavior of the DHCP server (e.g., how long a lease dhcpd willgive out), or specify client parameters that are not optional in theDHCP protocol (for example, server-name and filename).
In Figure 1, each host had host-specific parameters. Thesecould include such things as the hostname option, the name of afile to upload (the filename parameter) and the address of theserver from which to upload the file (the next-serverparameter). In general, any parameter can appear anywhere thatparameters are allowed, and will be applied according to the scope inwhich the parameter appears.
Imagine that you have a site with a lot of NCD X-Terminals. Theseterminals come in a variety of models, and you want to specify theboot files for each model. One way to do this would be to have hostdeclarations for each server and group them by model:
group { filename "Xncd19r"; next-server ncd-booter; host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; } host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; } host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }}group { filename "Xncd19c"; next-server ncd-booter; host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; } host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }}group { filename "XncdHMX"; next-server ncd-booter; host ncd1 { hardware ethernet 0:c0:c3:11:90:23; } host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; } host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }} ADDRESS POOLS
Thepooldeclaration can be used to specify a pool of addresses that will betreated differently than another pool of addresses, even on the samenetwork segment or subnet. For example, you may want to provide alarge set of addresses that can be assigned to DHCP clients that areregistered to your DHCP server, while providing a smaller set ofaddresses, possibly with short lease times, that are available forunknown clients. If you have a firewall, you may be able to arrangefor addresses from one pool to be allowed access to the Internet,while addresses in another pool are not, thus encouraging users toregister their DHCP clients. To do this, you would set up a pair ofpool declarations:
subnet 10.0.0.0 netmask 255.255.255.0 { option routers 10.0.0.254; # Unknown clients get this pool. pool { option domain-name-servers bogus.example.com; max-lease-time 300; range 10.0.0.200 10.0.0.253; allow unknown clients; } # Known clients get this pool. pool { option domain-name-servers ns1.example.com, ns2.example.com; max-lease-time 28800; range 10.0.0.5 10.0.0.199; deny unknown clients; }}It is also possible to set up entirely different subnets for known andunknown clients - address pools exist at the level of shared networks,so address ranges within pool declarations can be on differentsubnets.
As you can see in the preceding example, pools can have permit liststhat control which clients are allowed access to the pool and whicharen't. Each entry in a pool's permit list is introduced with theallowor deny keyword. If a pool has a permit list, then only thoseclients that match specific entries on the permit list will beeligible to be assigned addresses from the pool. If a pool has adeny list, then only those clients that do not match any entries onthe deny list will be eligible. If both permit and deny lists existfor a pool, then only clients that match the permit list and do notmatch the deny list will be allowed access.
DYNAMIC ADDRESS ALLOCATION
Address allocation is actually only done when a client is in the INITstate and has sent a DHCPDISCOVER message. If the client thinks ithas a valid lease and sends a DHCPREQUEST to initiate or renew thatlease, the server has only three choices - it can ignore theDHCPREQUEST, send a DHCPNAK to tell the client it should stop usingthe address, or send a DHCPACK, telling the client to go ahead and usethe address for a while.
If the server finds the address the client is requesting, and thataddress is available to the client, the server will send a DHCPACK.If the address is no longer available, or the client isn't permittedto have it, the server will send a DHCPNAK. If the server knowsnothing about the address, it will remain silent, unless the addressis incorrect for the network segment to which the client has beenattached and the server is authoritative for that network segment, inwhich case the server will send a DHCPNAK even though it doesn't knowabout the address.
There may be a host declaration matching the client's identification.If that host declaration contains a fixed-address declaration that lists an IP address that is valid for the network segment to which theclient is connected. In this case, the DHCP server will never dodynamic address allocation. In this case, the client is requiredto take the address specified in the host declaration. If theclient sends a DHCPREQUEST for some other address, the server will respondwith a DHCPNAK.
When the DHCP server allocates a new address for a client (remember,this only happens if the client has sent a DHCPDISCOVER), it firstlooks to see if the client already has a valid lease on an IP address,or if there is an old IP address the client had before that hasn't yetbeen reassigned. In that case, the server will take that address andcheck it to see if the client is still permitted to use it. If theclient is no longer permitted to use it, the lease is freed if theserver thought it was still in use - the fact that the client has senta DHCPDISCOVER proves to the server that the client is no longer usingthe lease.
If no existing lease is found, or if the client is forbidden toreceive the existing lease, then the server will look in the list ofaddress pools for the network segment to which the client is attachedfor a lease that is not in use and that the client is permitted tohave. It looks through each pool declaration in sequence (allrangedeclarations that appear outside of pool declarations are grouped intoa single pool with no permit list). If the permit list for the poolallows the client to be allocated an address from that pool, the poolis examined to see if there is an address available. If so, then theclient is tentatively assigned that address. Otherwise, the nextpool is tested. If no addresses are found that can be assigned tothe client, no response is sent to the client.
If an address is found that the client is permitted to have, and thathas never been assigned to any client before, the address isimmediately allocated to the client. If the address is available forallocation but has been previously assigned to a different client, theserver will keep looking in hopes of finding an address that has neverbefore been assigned to a client.
The DHCP server generates the list of available IP addresses from ahash table. This means that the addresses are not sorted in anyparticular order, and so it is not possible to predict the order inwhich the DHCP server will allocate IP addresses. Users of previousversions of the ISC DHCP server may have become accustomed to the DHCPserver allocating IP addresses in ascending order, but this is nolonger possible, and there is no way to configure this behavior withversion 3 of the ISC DHCP server.
IP ADDRESS CONFLICT PREVENTION
The DHCP server checks IP addresses to see if they are in use beforeallocating them to clients. It does this by sending an ICMP Echorequest message to the IP address being allocated. If no ICMP Echoreply is received within a second, the address is assumed to be free.This is only done for leases that have been specified in rangestatements, and only when the lease is thought by the DHCP server tobe free - i.e., the DHCP server or its failover peer has not listedthe lease as in use.
If a response is received to an ICMP Echo request, the DHCP serverassumes that there is a configuration error - the IP address is in useby some host on the network that is not a DHCP client. It marks theaddress as abandoned, and will not assign it to clients.
If a DHCP client tries to get an IP address, but none are available,but there are abandoned IP addresses, then the DHCP server willattempt to reclaim an abandoned IP address. It marks one IP addressas free, and then does the same ICMP Echo request check describedpreviously. If there is no answer to the ICMP Echo request, theaddress is assigned to the client.
The DHCP server does not cycle through abandoned IP addresses if thefirst IP address it tries to reclaim is free. Rather, when the nextDHCPDISCOVER comes in from the client, it will attempt a newallocation using the same method described here, and will typicallytry a new IP address.
DHCP FAILOVER
This version of the ISC DHCP server supports the DHCP failoverprotocol as documented in draft-ietf-dhc-failover-07.txt. This isnot a final protocol document, and we have not done interoperabilitytesting with other vendors' implementations of this protocol, so youmust not assume that this implementation conforms to the standard.If you wish to use the failover protocol, make sure that both failoverpeers are running the same version of the ISC DHCP server.
The failover protocol allows two DHCP servers (and no more than two)to share a common address pool. Each server will have about half ofthe available IP addresses in the pool at any given time forallocation. If one server fails, the other server will continue torenew leases out of the pool, and will allocate new addresses out ofthe roughly half of available addresses that it had whencommunications with the other server were lost.
It is possible during a prolonged failure to tell the remaining serverthat the other server is down, in which case the remaining server will(over time) reclaim all the addresses the other server had availablefor allocation, and begin to reuse them. This is called putting theserver into the PARTNER-DOWN state.
You can put the server into the PARTNER-DOWN state either by using theomshell (1)command or by stopping the server, editing the last peer statedeclaration in the lease file, and restarting the server. If you usethis last method, be sure to leave the date and time of the start ofthe state blank:
failover peer name state {my state partner-down;peer state state at date;}When the other server comes back online, it should automaticallydetect that it has been offline and request a complete update from theserver that was running in the PARTNER-DOWN state, and then bothservers will resume processing together.
It is possible to get into a dangerous situation: if you put oneserver into the PARTNER-DOWN state, and then *that* server goes down,and the other server comes back up, the other server will not knowthat the first server was in the PARTNER-DOWN state, and may issueaddresses previously issued by the other server to different clients,resulting in IP address conflicts. Before putting a server intoPARTNER-DOWN state, therefore, makesurethat the other server will not restart automatically.
The failover protocol defines a primary server role and a secondaryserver role. There are some differences in how primaries andsecondaries act, but most of the differences simply have to do withproviding a way for each peer to behave in the opposite way from theother. So one server must be configured as primary, and the othermust be configured as secondary, and it doesn't matter too much whichone is which.
FAILOVER STARTUP
When a server starts that has not previously communicated with itsfailover peer, it must establish communications with its failover peerand synchronize with it before it can serve clients. This can happeneither because you have just configured your DHCP servers to performfailover for the first time, or because one of your failover servershas failed catastrophically and lost its database.
The initial recovery process is designed to ensure that when onefailover peer loses its database and then resynchronizes, any leasesthat the failed server gave out before it failed will be honored.When the failed server starts up, it notices that it has no savedfailover state, and attempts to contact its peer.
When it has established contact, it asks the peer for a complete copyits peer's lease database. The peer then sends its complete database,and sends a message indicating that it is done. The failed serverthen waits until MCLT has passed, and once MCLT has passed bothservers make the transition back into normal operation. This waitingperiod ensures that any leases the failed server may have given outwhile out of contact with its partner will have expired.
While the failed server is recovering, its partner remains in thepartner-down state, which means that it is serving all clients. Thefailed server provides no service at all to DHCP clients until it hasmade the transition into normal operation.
In the case where both servers detect that they have never beforecommunicated with their partner, they both come up in this recoverystate and follow the procedure we have just described. In this case,no service will be provided to DHCP clients until MCLT has expired.
CONFIGURING FAILOVER
In order to configure failover, you need to write a peer declarationthat configures the failover protocol, and you need to write peerreferences in each pool declaration for which you want to dofailover. You do not have to do failover for all pools on a givennetwork segment. You must not tell one server it's doing failoveron a particular address pool and tell the other it is not. You mustnot have any common address pools on which you are not doingfailover. A pool declaration that utilizes failover would look like this:
pool { failover peer "foo"; deny dynamic bootp clients; pool specific parameters};Dynamic BOOTP leases are not compatible with failover, and, as such,you need to disallow BOOTP in pools that you are using failover for.
The server currently does very little sanity checking, so if youconfigure it wrong, it will just fail in odd ways. I would recommendtherefore that you either do failover or don't do failover, but don'tdo any mixed pools. Also, use the same master configuration file forboth servers, and have a separate file that contains the peerdeclaration and includes the master file. This will help you to avoidconfiguration mismatches. As our implementation evolves, this willbecome less of a problem. A basic sample dhcpd.conf file for aprimary server might look like this:
failover peer "foo" { primary; address anthrax.rc.vix.com; port 519; peer address trantor.rc.vix.com; peer port 520; max-response-delay 60; max-unacked-updates 10; mclt 3600; split 128; load balance max seconds 3;}include "/etc/dhcpd.master";The statements in the peer declaration are as follows:
The primaryandsecondarystatements
[ primary | secondary ];
This determines whether the server is primary or secondary, asdescribed earlier under DHCP FAILOVER.
The addressstatement
address address;
The address statement declares the IP address or DNS name on which theserver should listen for connections from its failover peer, and also thevalue to use for the DHCP Failover Protocol server identifier. Because thisvalue is used as an identifier, it may not be omitted.
The peer addressstatement
peer address address;
The peer address statement declares the IP address or DNS name towhich the server should connect to reach its failover peer for failovermessages.
The portstatement
port port-number;
The port statement declares the TCP port on which the servershould listen for connections from its failover peer. This statementmay not currently be omitted, because the failover protocol does notyet have a reserved TCP port number.
The peer portstatement
peer port port-number;
The peer port statement declares the TCP port to which theserver should connect to reach its failover peer for failovermessages. This statement may not be omitted because the failoverprotocol does not yet have a reserved TCP port number. The portnumber declared in the peer port statement may be the same asthe port number declared in the port statement.
The max-response-delaystatement
max-response-delay seconds;
The max-response-delay statement tells the DHCP server howmany seconds may pass without receiving a message from its failoverpeer before it assumes that connection has failed. This numbershould be small enough that a transient network failure that breaksthe connection will not result in the servers being out ofcommunication for a long time, but large enough that the server isn'tconstantly making and breaking connections. This parameter must bespecified.
The max-unacked-updatesstatement
max-unacked-updates count;
The max-unacked-updates statement tells the DHCP server howmany BNDUPD messages it can send before it receives a BNDACKfrom the failover peer. We don't have enough operational experienceto say what a good value for this is, but 10 seems to work. Thisparameter must be specified.
The mcltstatement
mclt seconds;
The mclt statement defines the Maximum Client Lead Time. Itmust be specified on the primary, and may not be specified on thesecondary. This is the length of time for which a lease may berenewed by either failover peer without contacting the other. Thelonger you set this, the longer it will take for the running server torecover IP addresses after moving into PARTNER-DOWN state. Theshorter you set it, the more load your servers will experience whenthey are not communicating. A value of something like 3600 isprobably reasonable, but again bear in mind that we have no realoperational experience with this.
The splitstatement
split index;
The split statement specifies the split between the primary andsecondary for the purposes of load balancing. Whenever a clientmakes a DHCP request, the DHCP server runs a hash on the clientidentification. If the hash comes out to less than the split value,the primary answers. If it comes out to equal to or more than thesplit, the secondary answers. The only meaningful value is 128, and canonly be configured on the primary.
The hbastatement
hba colon-separated-hex-list;
The hba statement specifies the split between the primary andsecondary as a bitmap rather than a cutoff, which theoretically allowsfor finer-grained control. In practice, there is probably no needfor such fine-grained control, however. An example hba statement:
hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff: 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;
This is equivalent to a split 128; statement. You must only havesplit or hba defined, never both. For most cases, thefine-grained control that hba offers isn't necessary, and splitshould be used. As such, the use of hba is deprecated.
The load balance max secondsstatement
load balance max seconds seconds;
This statement allows you to configure a cutoff after which loadbalancing is disabled. The cutoff is based on the number of secondssince the client sent its first DHCPDISCOVER or DHCPREQUEST message,and only works with clients that correctly implement the secsfield - fortunately most clients do. We recommend setting this tosomething like 3 or 5. The effect of this is that if one of thefailover peers gets into a state where it is responding to failovermessages but not responding to some client requests, the otherfailover peer will take over its client load automatically as theclients retry.
CLIENT CLASSING
Clients can be separated into classes, and treated differentlydepending on what class they are in. This separation can be doneeither with a conditional statement, or with a match statement withinthe class declaration. It is possible to specify a limit on thetotal number of clients within a particular class or subclass that mayhold leases at one time, and it is possible to specify automaticsubclassing based on the contents of the client packet.
To add clients to classes based on conditional evaluation, you canspecify a matching expression in the class statement:
class "ras-clients" { match if substring (option dhcp-client-identifier, 1, 3) = "RAS";}Note that whether you use matching expressions or add statements (orboth) to classify clients, you must always write a class declarationfor any class that you use. If there will be no match statement andno in-scope statements for a class, the declaration should look likethis:
class "ras-clients" {} SUBCLASSES
In addition to classes, it is possible to declare subclasses. Asubclass is a class with the same name as a regular class, but with aspecific submatch expression which is hashed for quick matching.This is essentially a speed hack - the main difference between fiveclasses with match expressions and one class with five subclasses isthat it will be quicker to find the subclasses. Subclasses work asfollows:
class "allocation-class-1" { match pick-first-value (option dhcp-client-identifier, hardware);}class "allocation-class-2" { match pick-first-value (option dhcp-client-identifier, hardware);}subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;subclass "allocation-class-1" 1:0:0:c4:aa:29:44;subnet 10.0.0.0 netmask 255.255.255.0 { pool { allow members of "allocation-class-1"; range 10.0.0.11 10.0.0.50; } pool { allow members of "allocation-class-2"; range 10.0.0.51 10.0.0.100; }}The data following the class name in the subclass declaration is aconstant value to use in matching the match expression for the class.When class matching is done, the server will evaluate the matchexpression and then look the result up in the hash table. If itfinds a match, the client is considered a member of both the class andthe subclass.
Subclasses can be declared with or without scope. In the aboveexample, the sole purpose of the subclass is to allow some clientsaccess to one address pool, while other clients are given access tothe other pool, so these subclasses are declared without scopes. Ifpart of the purpose of the subclass were to define different parametervalues for some clients, you might want to declare some subclasseswith scopes.
In the above example, if you had a single client that needed someconfiguration parameters, while most didn't, you might write thefollowing subclass declaration for that client:
subclass "allocation-class-2" 1:08:00:2b:a1:11:31 { option root-path "samsara:/var/diskless/alphapc"; filename "/tftpboot/netbsd.alphapc-diskless";}In this example, we've used subclassing as a way to control addressallocation on a per-client basis. However, it's also possible to usesubclassing in ways that are not specific to clients - for example, touse the value of the vendor-class-identifier option to determine whatvalues to send in the vendor-encapsulated-options option. An exampleof this is shown under the VENDOR ENCAPSULATED OPTIONS head in thedhcp-options(5)manual page.
PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION
You may specify a limit to the number of clients in a class that canbe assigned leases. The effect of this will be to make it difficultfor a new client in a class to get an address. Once a class withsuch a limit has reached its limit, the only way a new client in thatclass can get a lease is for an existing client to relinquish itslease, either by letting it expire, or by sending a DHCPRELEASEpacket. Classes with lease limits are specified as follows:
class "limited-1" { lease limit 4;}This will produce a class in which a maximum of four members may holda lease at one time.
SPAWNING CLASSES
It is possible to declare aspawning class.A spawning class is a class that automatically produces subclassesbased on what the client sends. The reason that spawning classeswere created was to make it possible to create lease-limited classeson the fly. The envisioned application is a cable-modem environmentwhere the ISP wishes to provide clients at a particular site with morethan one IP address, but does not wish to provide such clients withtheir own subnet, nor give them an unlimited number of IP addressesfrom the network segment to which they are connected.
Many cable modem head-end systems can be configured to add a RelayAgent Information option to DHCP packets when relaying them to theDHCP server. These systems typically add a circuit ID or remote IDoption that uniquely identifies the customer site. To take advantageof this, you can write a class declaration as follows:
class "customer" { spawn with option agent.circuit-id; lease limit 4;}Now whenever a request comes in from a customer site, the circuit IDoption will be checked against the class's hash table. If a subclassis found that matches the circuit ID, the client will be classified inthat subclass and treated accordingly. If no subclass is foundmatching the circuit ID, a new one will be created and logged in thedhcpd.leasesfile, and the client will be classified in this new class. Once theclient has been classified, it will be treated according to the rulesof the class, including, in this case, being subject to the per-sitelimit of four leases.
The use of the subclass spawning mechanism is not restricted to relayagent options - this particular example is given only because it is afairly straightforward one.
COMBINING MATCH, MATCH IF AND SPAWN WITH
In some cases, it may be useful to use one expression to assign aclient to a particular class, and a second expression to put it into asubclass of that class. This can be done by combining the matchif and spawn with statements, or the match if andmatch statements. For example:
class "jr-cable-modems" { match if option dhcp-vendor-identifier = "jrcm"; spawn with option agent.circuit-id; lease limit 4;}class "dv-dsl-modems" { match if opton dhcp-vendor-identifier = "dvdsl"; spawn with option agent.circuit-id; lease limit 16;}This allows you to have two classes that both have the same spawnwith expression without getting the clients in the two classesconfused with each other.
DYNAMIC DNS UPDATES
The DHCP server has the ability to dynamically update the Domain NameSystem. Within the configuration files, you can define how you wantthe Domain Name System to be updated. These updates are RFC 2136compliant so any DNS server supporting RFC 2136 should be able toaccept updates from the DHCP server.
Two DNS update schemes are currently implemented, and another isplanned. The two that are currently available are the ad-hoc DNSupdate mode and the interim DHCP-DNS interaction draft update mode.If and when the DHCP-DNS interaction draft and the DHCID draft make itthrough the IETF standards process, there will be a third mode, whichwill be the standard DNS update method. The DHCP server must beconfigured to use one of the two currently-supported methods, or notto do dns updates. This can be done with theddns-update-styleconfiguration parameter.
THE AD-HOC DNS UPDATE SCHEME
The ad-hoc Dynamic DNS update scheme is
now deprecatedand
does not work.In future releases of the ISC DHCP server, this scheme will not likely beavailable. The interim scheme works, allows for failover, and should now beused. The following description is left here for informational purposesonly.
The ad-hoc Dynamic DNS update scheme implemented in this version ofthe ISC DHCP server is a prototype design, which does nothave much to do with the standard update method that is beingstandardized in the IETF DHC working group, but rather implements somevery basic, yet useful, update capabilities. This modedoes not workwith thefailover protocolbecause it does not account for the possibility of two different DHCPservers updating the same set of DNS records.
For the ad-hoc DNS update method, the client's FQDN is derived in twoparts. First, the hostname is determined. Then, the domain name isdetermined, and appended to the hostname.
The DHCP server determines the client's hostname by first looking fora ddns-hostname configuration option, and using that if it ispresent. If no such option is present, the server looks for avalid hostname in the FQDN option sent by the client. If one isfound, it is used; otherwise, if the client sent a host-name option,that is used. Otherwise, if there is a host declaration that appliesto the client, the name from that declaration will be used. If noneof these applies, the server will not have a hostname for the client,and will not be able to do a DNS update.
The domain name is determined based strictly on the serverconfiguration, not on what the client sends. First, if there is a ddns-domainnameconfiguration option, it is used. Second, if there is adomain-name option configured, that is used. Otherwise, theserver will not do the DNS update.
The client's fully-qualified domain name, derived as we havedescribed, is used as the name on which an "A" record will be stored.The A record will contain the IP address that the client was assignedin its lease. If there is already an A record with the same name inthe DNS server, no update of either the A or PTR records will occur -this prevents a client from claiming that its hostname is the name ofsome network server. For example, if you have a fileserver called"fs.sneedville.edu", and the client claims its hostname is "fs", noDNS update will be done for that client, and an error message will belogged.
If the A record update succeeds, a PTR record update for the assignedIP address will be done, pointing to the A record. This update isunconditional - it will be done even if another PTR record of the samename exists. Since the IP address has been assigned to the DHCPserver, this should be safe.
Please note that the current implementation assumes clients only havea single network interface. A client with two network interfaceswill see unpredictable behavior. This is considered a bug, and willbe fixed in a later release. It may be helpful to enable theone-lease-per-clientparameter so that roaming clients do not trigger this same behavior.
The DHCP protocol normally involves a four-packet exchange - first theclient sends a DHCPDISCOVER message, then the server sends aDHCPOFFER, then the client sends a DHCPREQUEST, then the server sendsa DHCPACK. In the current version of the server, the server will doa DNS update after it has received the DHCPREQUEST, and before it hassent the DHCPACK. It only sends the DNS update if it has not sentone for the client's address before, in order to minimize the impacton the DHCP server.
When the client's lease expires, the DHCP server (if it is operatingat the time, or when next it operates) will remove the client's A andPTR records from the DNS database. If the client releases its leaseby sending a DHCPRELEASE message, the server will likewise remove theA and PTR records.
THE INTERIM DNS UPDATE SCHEME
The interim DNS update scheme operates mostly according to severaldrafts that are being considered by the IETF and are expected tobecome standards, but are not yet standards, and may not bestandardized exactly as currently proposed. These are:
draft-ietf-dhc-ddns-resolution-??.txt
draft-ietf-dhc-fqdn-option-??.txt
draft-ietf-dnsext-dhcid-rr-??.txt
Because our implementation is slightly different than the standard, wewill briefly document the operation of this update style here.
The first point to understand about this style of DNS update is thatunlike the ad-hoc style, the DHCP server does not necessarilyalways update both the A and the PTR records. The FQDN optionincludes a flag which, when sent by the client, indicates that theclient wishes to update its own A record. In that case, the servercan be configured either to honor the client's intentions or ignorethem. This is done with the statement allow client-updates; orthe statement ignore client-updates;. By default, clientupdates are allowed.
If the server is configured to allow client updates, then if theclient sends a fully-qualified domain name in the FQDN option, theserver will use that name the client sent in the FQDN option to updatethe PTR record. For example, let us say that the client is a visitorfrom the "radish.org" domain, whose hostname is "jschmoe". Theserver is for the "example.org" domain. The DHCP client indicates inthe FQDN option that its FQDN is "jschmoe.radish.org.". It alsoindicates that it wants to update its own A record. The DHCP servertherefore does not attempt to set up an A record for the client, butdoes set up a PTR record for the IP address that it assigns theclient, pointing at jschmoe.radish.org. Once the DHCP client has anIP address, it can update its own A record, assuming that the"radish.org" DNS server will allow it to do so.
If the server is configured not to allow client updates, or if theclient doesn't want to do its own update, the server will simplychoose a name for the client, possibly using the hostname supplied bythe client ("jschmoe" in the previous example). It will use its owndomain name for the client, just as in the ad-hoc update scheme.It will then update both the A and PTR record, using the name that itchose for the client. If the client sends a fully-qualified domainname in the fqdn option, the server uses only the leftmost part of thedomain name - in the example above, "jschmoe" instead of"jschmoe.radish.org".
The other difference between the ad-hoc scheme and the interimscheme is that with the interim scheme, a method is used thatallows more than one DHCP server to update the DNS database withoutaccidentally deleting A records that shouldn't be deleted nor failingto add A records that should be added. The scheme works as follows:
When the DHCP server issues a client a new lease, it creates a textstring that is an MD5 hash over the DHCP client's identification (seedraft-ietf-dnsext-dhcid-rr-??.txt for details). The update adds an Arecord with the name the server chose and a TXT record containing thehashed identifier string (hashid). If this update succeeds, theserver is done.
If the update fails because the A record already exists, then the DHCPserver attempts to add the A record with the prerequisite that theremust be a TXT record in the same name as the new A record, and thatTXT record's contents must be equal to hashid. If this updatesucceeds, then the client has its A record and PTR record. If itfails, then the name the client has been assigned (or requested) is inuse, and can't be used by the client. At this point the DHCP servergives up trying to do a DNS update for the client until the clientchooses a new name.
The interim DNS update scheme is called interim for two reasons.First, it does not quite follow the drafts. The current versions ofthe drafts call for a new DHCID RRtype, but this is not yetavailable. The interim DNS update scheme uses a TXT recordinstead. Also, the existing ddns-resolution draft calls for the DHCPserver to put a DHCID RR on the PTR record, but the interimupdate method does not do this. It is our position that this is notuseful, and we are working with the author in hopes of removing itfrom the next version of the draft, or better understanding why it isconsidered useful.
In addition to these differences, the server also does not update veryaggressively. Because each DNS update involves a round trip to theDNS server, there is a cost associated with doing updates even if theydo not actually modify the DNS database. So the DHCP server trackswhether or not it has updated the record in the past (this informationis stored on the lease) and does not attempt to update records that itthinks it has already updated.
This can lead to cases where the DHCP server adds a record, and thenthe record is deleted through some other mechanism, but the servernever again updates the DNS because it thinks the data is alreadythere. In this case the data can be removed from the lease throughoperator intervention, and once this has been done, the DNS will beupdated the next time the client renews.
DYNAMIC DNS UPDATE SECURITY
When you set your DNS server up to allow updates from the DHCP server,you may be exposing it to unauthorized updates. To avoid this, youshould use TSIG signatures - a method of cryptographically signingupdates using a shared secret key. As long as you protect thesecrecy of this key, your updates should also be secure. Note,however, that the DHCP protocol itself provides no security, and thatclients can therefore provide information to the DHCP server which theDHCP server will then use in its updates, with the constraintsdescribed previously.
The DNS server must be configured to allow updates for any zone thatthe DHCP server will be updating. For example, let us say thatclients in the sneedville.edu domain will be assigned addresses on the10.10.17.0/24 subnet. In that case, you will need a key declarationfor the TSIG key you will be using, and also two zone declarations -one for the zone containing A records that will be updates and one forthe zone containing PTR records - for ISC BIND, something like this:
key DHCP_UPDATER { algorithm HMAC-MD5.SIG-ALG.REG.INT; secret pRP5FapFoJ95JEL06sv4PQ==;};zone "example.org" { type master; file "example.org.db"; allow-update { key DHCP_UPDATER; };};zone "17.10.10.in-addr.arpa" { type master; file "10.10.17.db"; allow-update { key DHCP_UPDATER; };};You will also have to configure your DHCP server to do updates tothese zones. To do so, you need to add something like this to yourdhcpd.conf file:
key DHCP_UPDATER { algorithm HMAC-MD5.SIG-ALG.REG.INT; secret pRP5FapFoJ95JEL06sv4PQ==;};zone EXAMPLE.ORG. { primary 127.0.0.1; key DHCP_UPDATER;}zone 17.127.10.in-addr.arpa. { primary 127.0.0.1; key DHCP_UPDATER;}The primary statement specifies the IP address of the nameserver whose zone information is to be updated.
Note that the zone declarations have to correspond to authorityrecords in your name server - in the above example, there must be anSOA record for "example.org." and for "17.10.10.in-addr.arpa.". Forexample, if there were a subdoman "foo.example.org" with no separateSOA, you could not write a zone declaration for "foo.example.org." Also keep in mind that zone names in your DHCP configuration should end in a"."; this is the preferred syntax. If you do not end your zone name in a".", the DHCP server will figure it out. Also note that in the DHCPconfiguration, zone names are not encapsulated in quotes where there are inthe DNS configuration.
You should choose your own secret key, of course. The ISC BIND 8 and9 distributions come with a program for generating secret keys calleddnssec-keygen. The version that comes with BIND 9 is likely to produce asubstantially more random key, so we recommend you use that one evenif you are not using BIND 9 as your DNS server. If you are using BIND 9'sdnssec-keygen, the above key would be created as follows:
dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER
If you are using the BIND 8 dnskeygen program, the following command willgenerate a key as seen above:
dnskeygen -H 128 -u -c -n DHCP_UPDATER
You may wish to enable logging of DNS updates on your DNS server.To do so, you might write a logging statement like the following:
logging { channel update_debug { file "/var/log/update-debug.log"; severity debug 3; print-category yes; print-severity yes; print-time yes; }; channel security_info { file "/var/log/named-auth.info"; severity info; print-category yes; print-severity yes; print-time yes; }; category update { update_debug; }; category security { security_info; };};You must create the /var/log/named-auth.info and/var/log/update-debug.log files before starting the name server. Formore information on configuring ISC BIND, consult the documentationthat accompanies it.
REFERENCE: EVENTS
There are three kinds of events that can happen regarding a lease, andit is possible to declare statements that occur when any of theseevents happen. These events are the commit event, when the serverhas made a commitment of a certain lease to a client, the releaseevent, when the client has released the server from its commitment,and the expiry event, when the commitment expires.
To declare a set of statements to execute when an event happens, youmust use the on statement, followed by the name of the event,followed by a series of statements to execute when the event happens,enclosed in braces. Events are used to implement DNSupdates, so you should not define your own event handlers if you areusing the built-in DNS update mechanism.
The built-in version of the DNS update mechanism is in a textstring towards the top of server/dhcpd.c. If you want to use eventsfor things other than DNS updates, and you also want DNS updates, youwill have to start out by copying this code into your dhcpd.conf fileand modifying it.
REFERENCE: DECLARATIONS
The shared-networkstatement
shared-network name { [ parameters ] [ declarations ] }The shared-network statement is used to inform the DHCP serverthat some IP subnets actually share the same physical network. Anysubnets in a shared network should be declared within ashared-network statement. Parameters specified in theshared-network statement will be used when booting clients onthose subnets unless parameters provided at the subnet or host leveloverride them. If any subnet in a shared network has addressesavailable for dynamic allocation, those addresses are collected into acommon pool for that shared network and assigned to clients as needed.There is no way to distinguish on which subnet of a shared network aclient should boot.
Nameshould be the name of the shared network. This name is used whenprinting debugging messages, so it should be descriptive for theshared network. The name may have the syntax of a valid domain name(although it will never be used as such), or it may be any arbitraryname, enclosed in quotes.
The subnetstatement
subnet subnet-number netmask netmask { [ parameters ] [ declarations ] }The subnet statement is used to provide dhcpd with enoughinformation to tell whether or not an IP address is on that subnet.It may also be used to provide subnet-specific parameters and tospecify what addresses may be dynamically allocated to clients bootingon that subnet. Such addresses are specified using the rangedeclaration.
Thesubnet-numbershould be an IP address or domain name which resolves to the subnetnumber of the subnet being described. The netmaskshould be an IP address or domain name which resolves to the subnet maskof the subnet being described. The subnet number, together with thenetmask, are sufficient to determine whether any given IP address ison the specified subnet.
Although a netmask must be given with every subnet declaration, it isrecommended that if there is any variance in subnet masks at a site, asubnet-mask option statement be used in each subnet declaration to setthe desired subnet mask, since any subnet-mask option statement willoverride the subnet mask declared in the subnet statement.
Therangestatement
range [ dynamic-bootp ] low-address [ high-address];
For any subnet on which addresses will be assigned dynamically, theremust be at least one range statement. The range statementgives the lowest and highest IP addresses in a range. All IPaddresses in the range should be in the subnet in which therange statement is declared. The dynamic-bootp flag maybe specified if addresses in the specified range may be dynamicallyassigned to BOOTP clients as well as DHCP clients. When specifying asingle address, high-address can be omitted.
Thehoststatement
host hostname { [ parameters ] [ declarations ] }Thehostdeclaration provides a scope in which to provide configuration information abouta specific client, and also provides a way to assign a client a fixed address.The host declaration provides a way for the DHCP server to identify a DHCP orBOOTP client, and also a way to assign the client a static IP address.
If it is desirable to be able to boot a DHCP or BOOTPclient on more than one subnet with fixed addresses, more than oneaddress may be specified in thefixed-addressdeclaration, or more than onehoststatement may be specified.
If client-specific boot parameters must change based on the networkto which the client is attached, then multiple hostdeclaration shouldbe used.
If a client is to be booted using a fixed address if it'spossible, but should be allocated a dynamic address otherwise, then ahostdeclaration must be specified without afixed-addressdeclaration.hostnameshould be a name identifying the host. If a hostname option isnot specified for the host, hostname is used.
Host declarations are matched to actual DHCP or BOOTP clientsby matching the dhcp-client-identifier option specified in thehost declaration to the one supplied by the client, or, if thehost declaration or the client does not provide adhcp-client-identifier option, by matching the hardwareparameter in the host declaration to the network hardwareaddress supplied by the client. BOOTP clients do not normallyprovide a dhcp-client-identifier, so the hardware address mustbe used for all clients that may boot using the BOOTP protocol.
Please be aware thatonlythe dhcp-client-identifier option and the hardware address can beused to match a host declaration. For example, it is not possible to matcha host declaration to a host-name option. This is because thehost-name option cannot be guaranteed to be unique for any given client,whereas both the hardware address and dhcp-client-identifier optionare at least theoretically guaranteed to be unique to a given client.
Thegroupstatement
group { [ parameters ] [ declarations ] }The group statement is used simply to apply one or more parameters toa group of declarations. It can be used to group hosts, sharednetworks, subnets, or even other groups.
REFERENCE: ALLOW AND DENY
The
allowand
denystatements can be used to control the response of the DHCP server tovarious sorts of requests. The allow and deny keywords actually havedifferent meanings depending on the context. In a pool context, thesekeywords can be used to set up access lists for address allocationpools. In other contexts, the keywords simply control general serverbehavior with respect to clients based on scope. In a non-poolcontext, the
ignorekeyword can be used in place of the
denykeyword to prevent logging of denied requests.
ALLOW DENY AND IGNORE IN SCOPE
The following usages of allow and deny will work in any scope,although it is not recommended that they be used in pooldeclarations.
Theunknown-clientskeyword
allow unknown-clients;
deny unknown-clients;
ignore unknown-clients;
The unknown-clients flag is used to tell dhcpd whetheror not to dynamically assign addresses to unknown clients. Dynamicaddress assignment to unknown clients is allowed by default.An unknown client is simply a client that has no host declaration.
The use of this option is now deprecated. If you are trying torestrict access on your network to known clients, you should use denyunknown clients; inside of your address pool, as described under theheading ALLOW AND DENY WITHIN POOL DECLARAIONS.
Thebootpkeyword
allow bootp;
deny bootp;
ignore bootp;
The bootp flag is used to tell dhcpd whetheror not to respond to bootp queries. Bootp queries are allowedby default.
This option does not satisfy the requirement of failover peers for denyingdynamic bootp clients. The deny dynamic bootp clients; option shouldbe used instead. See the ALLOW AND DENY WITHIN POOL DECLARATIONS sectionof this man page for more details.
Thebootingkeyword
allow booting;
deny booting;
ignore booting;
The booting flag is used to tell dhcpd whether or not to respondto queries from a particular client. This keyword only has meaningwhen it appears in a host declaration. By default, booting isallowed, but if it is disabled for a particular client, thenthat client will not be able to get and address from the DHCP server.
Theduplicateskeyword
allow duplicates;
deny duplicates;
Host declarations can match client messages based on the DHCP ClientIdentifer option or based on the client's network hardware type andMAC address. If the MAC address is used, the host declaration willmatch any client with that MAC address - even clients with differentclient identifiers. This doesn't normally happen, but is possiblewhen one computer has more than one operating system installed on it -for example, Microsoft Windows and NetBSD or Linux.
The duplicates flag tells the DHCP server that if a request isreceived from a client that matches the MAC address of a hostdeclaration, any other leases matching that MAC address should bediscarded by the server, even if the UID is not the same. This is aviolation of the DHCP protocol, but can prevent clients whose clientidentifiers change regularly from holding many leases at the same time.By default, duplicates are allowed.
Thedeclineskeyword
allow declines;
deny declines;
ignore declines;
The DHCPDECLINE message is used by DHCP clients to indicate that thelease the server has offered is not valid. When the server receivesa DHCPDECLINE for a particular address, it normally abandons thataddress, assuming that some unauthorized system is using it.Unfortunately, a malicious or buggy client can, using DHCPDECLINEmessages, completely exhaust the DHCP server's allocation pool. Theserver will reclaim these leases, but while the client is runningthrough the pool, it may cause serious thrashing in the DNS, and itwill also cause the DHCP server to forget old DHCP client addressallocations.
The declines flag tells the DHCP server whether or not to honorDHCPDECLINE messages. If it is set to deny or ignore ina particular scope, the DHCP server will not respond to DHCPDECLINEmessages.
Theclient-updateskeyword
allow client-updates;
deny client-updates;
The client-updates flag tells the DHCP server whether or not tohonor the client's intention to do its own update of its A record.This is only relevant when doing interim DNS updates. See thedocumentation under the heading THE INTERIM DNS UPDATE SCHEME fordetails.
ALLOW AND DENY WITHIN POOL DECLARATIONS
The uses of the allow and deny keywords shown in the previous sectionwork pretty much the same way whether the client is sending aDHCPDISCOVER or a DHCPREQUEST message - an address will be allocatedto the client (either the old address it's requesting, or a newaddress) and then that address will be tested to see if it's okay tolet the client have it. If the client requested it, and it's notokay, the server will send a DHCPNAK message. Otherwise, the serverwill simply not respond to the client. If it is okay to give theaddress to the client, the server will send a DHCPACK message.
The primary motivation behind pool declarations is to have addressallocation pools whose allocation policies are different. A clientmay be denied access to one pool, but allowed access to another poolon the same network segment. In order for this to work, accesscontrol has to be done during address allocation, not after addressallocation is done.
When a DHCPREQUEST message is processed, address allocation simplyconsists of looking up the address the client is requesting and seeingif it's still available for the client. If it is, then the DHCPserver checks both the address pool permit lists and the relevantin-scope allow and deny statements to see if it's okay to give thelease to the client. In the case of a DHCPDISCOVER message, theallocation process is done as described previously in the ADDRESSALLOCATION section.
When declaring permit lists for address allocation pools, thefollowing syntaxes are recognized following the allow or deny keywords:
known clients;
If specified, this statement either allows or prevents allocation fromthis pool to any client that
