dhcpd.conf(5)dhcpd.conf(5)NAMEdhcpd.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 by the recursive-descent parser built into
dhcpd. The file may contain extra tabs and newlines for
formatting purposes. Keywords in the file are case-insen-
sitive. Comments may be placed anywhere within the file
(except within quotes). Comments begin with the # char-
acter and end at the end of the line.
The file essentially consists of a list of statements.
Statements fall into two broad categories - parameters and
declarations.
Parameter statements either say how to do something (e.g.,
how long a lease to offer), whether to do something (e.g.,
should dhcpd provide addresses to unknown clients), or
what parameters to provide to the client (e.g., use gate-
way 220.177.244.7).
Declarations are used to describe the topology of the net-
work, to describe clients on the network, to provide
addresses that can be assigned to clients, or to apply a
group of parameters to a group of declarations. In any
group of parameters and declarations, all parameters must
be specified before any declarations which depend on those
parameters may be specified.
Declarations about network topology include the
shared-network and the subnet declarations. If clients
on a subnet are to be assigned addresses dynamically, a
range declaration must appear within the subnet declara-
tion. For clients with statically assigned addresses, or
for installations where only known clients will be served,
each such client must have a host declaration. If param-
eters are to be applied to a group of declarations which
are not related strictly on a per-subnet basis, the group
declaration can be used.
For every subnet which will be served, and for every sub-
net to which the dhcp server is connected, there must be
one subnet declaration, which tells dhcpd how to recognize
that an address is on that subnet. A subnet declaration
is required for each subnet even if no addresses will be
dynamically allocated on that subnet.
Some installations have physical networks on which more
than one IP subnet operates. For example, if there is a
site-wide requirement that 8-bit subnet masks be used, but
1
dhcpd.conf(5)dhcpd.conf(5)
a department with a single physical ethernet network
expands to the point where it has more than 254 nodes, it
may be necessary to run two 8-bit subnets on the same eth-
ernet until such time as a new physical network can be
added. In this case, the subnet declarations for these
two networks must be enclosed in a shared-network declara-
tion.
Some sites may have departments which have clients on more
than one subnet, but it may be desirable to offer those
clients a uniform set of parameters which are different
than what would be offered to clients from other depart-
ments on the same subnet. For clients which will be
declared explicitly with host declarations, these declara-
tions can be enclosed in a group declaration along with
the parameters which are common to that department. For
clients whose addresses will be dynamically assigned,
class declarations and conditional declarations may be
used to group parameter assignments based on information
the client sends.
When a client is to be booted, its boot parameters are
determined by consulting that client's host declaration
(if any), and then consulting any class declarations
matching the client, followed by the pool, subnet and
shared-network declarations for the IP address assigned to
the client. Each of these declarations itself appears
within a lexical scope, and all declarations at less spe-
cific lexical scopes are also consulted for client option
declarations. Scopes are never considered twice, and if
parameters are declared in more than one scope, the param-
eter declared in the most specific scope is the one that
is used.
When dhcpd tries to find a host declaration for a client,
it first looks for a host declaration which has a fixed-
address parameter which matches the subnet or shared net-
work on which the client is booting. If it doesn't find
any such entry, it then tries to find an entry which has
no fixed-address parameter.
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;
2
dhcpd.conf(5)dhcpd.conf(5)
}
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 place
for global parameters. These might be things like the
organization's domain name, the addresses of the name
servers (if they are common to the 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
in parameters using their domain names rather than their
numeric IP addresses. If a given hostname resolves to
more than one IP address (for example, if that host has
two ethernet interfaces), then where possible, both
addresses are supplied to the client.
The most obvious reason for having subnet-specific parame-
ters as shown in Figure 1 is that each subnet, of neces-
sity, has its own router. So for the first subnet, for
example, there should be something like:
option routers 204.254.239.1;
Note that the address here is specified numerically.
This is not required - if you have a different domain name
for each interface on your router, it's perfectly legiti-
mate to use the domain name for that interface instead of
the numeric address. However, in many cases there may be
only one domain name for all of a router's IP addresses,
3
dhcpd.conf(5)dhcpd.conf(5)
and it would not be appropriate to use that name here.
In Figure 1 there is also a group statement, which pro-
vides common 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 it might make sense for a
group-specific parameter to override the domain name sup-
plied 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 mecha-
nism, we might set the lease timeout somewhat shorter than
the default:
max-lease-time 120;
default-lease-time 120;
You may have noticed that while some parameters start with
the option keyword, some do not. Parameters starting
with the option keyword correspond to actual DHCP options,
while parameters that do not start with the option keyword
either control the behavior of the DHCP server (e.g., how
long a lease dhcpd will give out), or specify client
parameters that are not optional in the DHCP protocol (for
example, server-name and filename).
In Figure 1, each host had host-specific parameters.
These could include such things as the hostname option,
the name of a file to upload (the filename parameter) and
the address of the server from which to upload the file
(the next-server parameter). In general, any parameter
can appear anywhere that parameters are allowed, and will
be applied according to the scope in which the parameter
appears.
Imagine that you have a site with a lot of NCD X-Termi-
nals. These terminals come in a variety of models, and
you want to specify the boot files for each model. One
way to do this would be to have host declarations 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";
4
dhcpd.conf(5)dhcpd.conf(5)
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
The pool declaration can be used to specify a pool of
addresses that will be treated differently than another
pool of addresses, even on the same network segment or
subnet. For example, you may want to provide a large set
of addresses that can be assigned to DHCP clients that are
registered to your DHCP server, while providing a smaller
set of addresses, possibly with short lease times, that
are available for unknown clients. If you have a fire-
wall, you may be able to arrange for addresses from one
pool to be allowed access to the Internet, while addresses
in another pool are not, thus encouraging users to regis-
ter their DHCP clients. To do this, you would set up a
pair of pool 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 and unknown clients - address pools exist at the
level of shared networks, so address ranges within pool
declarations can be on different subnets.
5
dhcpd.conf(5)dhcpd.conf(5)
As you can see in the preceding example, pools can have
permit lists that control which clients are allowed access
to the pool and which aren't. Each entry in a pool's per-
mit list is introduced with the allow or deny keyword.
If a pool has a permit list, then only those clients that
match specific entries on the permit list will be eligible
to be assigned addresses from the pool. If a pool has a
deny list, then only those clients that do not match any
entries on the deny list will be eligible. If both per-
mit and deny lists exist for a pool, then only clients
that match the permit list and do not match the deny list
will be allowed access.
DYNAMIC ADDRESS ALLOCATION
Address allocation is actually only done when a client is
in the INIT state and has sent a DHCPDISCOVER message. If
the client thinks it has a valid lease and sends a DHCPRE-
QUEST to initiate or renew that lease, the server has only
three choices - it can ignore the DHCPREQUEST, send a
DHCPNAK to tell the client it should stop using the
address, or send a DHCPACK, telling the client to go ahead
and use the address for a while.
If the server finds the address the client is requesting,
and that address is available to the client, the server
will send a DHCPACK. If the address is no longer avail-
able, or the client isn't permitted to have it, the server
will send a DHCPNAK. If the server knows nothing about
the address, it will remain silent, unless the address is
incorrect for the network segment to which the client has
been attached and the server is authoritative for that
network segment, in which case the server will send a
DHCPNAK even though it doesn't know about the address.
There may be a host declaration matching the client's
identification, and that host declaration contains a
fixed-address declaration that is valid for the network
segment to which the client is connected. In this case,
the DHCP server will never do dynamic address allocation.
In this case, the client is required to take the address
specified in the host declaration. If the client is
requesting some other address, the server will respond
with 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 first looks 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 yet been
reassigned. In that case, the server will take that
address and check it to see if the client is still permit-
ted to use it. If the client is no longer permitted to
use it, the lease is freed if the server thought it was
still in use - the fact that the client has sent a
6
dhcpd.conf(5)dhcpd.conf(5)
DHCPDISCOVER proves to the server that the client is no
longer using the lease.
If no existing lease is found, or if the client is forbid-
den to receive the existing lease, then the server will
look in the list of address pools for the network segment
to which the client is attached for a lease that is not in
use and that the client is permitted to have. It looks
through each pool declaration in sequence (all range dec-
larations that appear outside of pool declarations are
grouped into a single pool with no permit list). If the
permit list for the pool allows the client to be allocated
an address from that pool, the pool is examined to see if
there is an address available. If so, then the client is
tentatively assigned that address. Otherwise, the next
pool is tested. If no addresses are found that can be
assigned to the client, no response is sent to the client.
If an address is found that the client is permitted to
have, and that has never been assigned to any client
before, the address is immediately allocated to the
client. If the address is available for allocation but
has been previously assigned to a different client, the
server will keep looking in hopes of finding an address
that has never before been assigned to a client.
IP ADDRESS CONFLICT PREVENTION
The DHCP server checks IP addresses to see if they are in
use before allocating them to clients. It does this by
sending an ICMP Echo request message to the IP address
being allocated. If no ICMP Echo reply is received
within a second, the address is assumed to be free. This
is only done for leases that have been specified in range
statements, and only when the lease is thought by the DHCP
server to be free - i.e., the DHCP server or its failover
peer has not listed the lease as in use.
If a response is received to an ICMP Echo request, the
DHCP server assumes that there is a configuration error -
the IP address is in use by some host on the network that
is not a DHCP client. It marks the address 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 will attempt to reclaim an abandoned IP
address. It marks one IP address as free, and then does
the same ICMP Echo request check described previously.
If there is no answer to the ICMP Echo request, the
address is assigned to the client.
The DHCP server does not cycle through abandoned IP
addresses if the first IP address it tries to reclaim is
free. Rather, when the next DHCPDISCOVER comes in from
7
dhcpd.conf(5)dhcpd.conf(5)
the client, it will attempt a new allocation using the
same method described here, and will typically try a new
IP address.
DHCP FAILOVER
This version of the ISC DHCP server supports the DHCP
failover protocol as documented in draft-ietf-dhc-
failover-07.txt. This is not a final protocol document,
and we have not done interoperability testing with other
vendors' implementations of this protocol, so you must not
assume that this implementation conforms to the standard.
If you wish to use the failover protocol, make sure that
both failover peers 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 of the available IP addresses in the
pool at any given time for allocation. If one server
fails, the other server will continue to renew leases out
of the pool, and will allocate new addresses out of the
roughly half of available addresses that it had when com-
munications with the other server were lost.
It is possible during a prolonged failure to tell the
remaining server that the other server is down, in which
case the remaining server will (over time) reclaim all the
addresses the other server had available for allocation,
and begin to reuse them. This is called putting the
server into the PARTNER-DOWN state.
You can put the server into the PARTNER-DOWN state either
by using the omshell (8) command or by stopping the
server, editing the last peer state declaration in the
lease file, and restarting the server. If you use this
last method, be sure to leave the date and time of the
start of the state blank:
failover peer name state {
my state partner-down;
peer state state at date;
}
When the other server comes back online, it should auto-
matically detect that it has been offline and request a
complete update from the server that was running in the
PARTNER-DOWN state, and then both servers will resume pro-
cessing together.
It is possible to get into a dangerous situation: if you
put one server into the PARTNER-DOWN state, and then
*that* server goes down, and the other server comes back
up, the other server will not know that the first server
was in the PARTNER-DOWN state, and may issue addresses
8
dhcpd.conf(5)dhcpd.conf(5)
previously issued by the other server to different
clients, resulting in IP address conflicts. Before
putting a server into PARTNER-DOWN state, therefore, make
sure that the other server will not restart automatically.
The failover protocol defines a primary server role and a
secondary server role. There are some differences in how
primaries and secondaries act, but most of the differences
simply have to do with providing a way for each peer to
behave in the opposite way from the other. So one server
must be configured as primary, and the other must be con-
figured as secondary, and it doesn't matter too much which
one is which.
FAILOVER STARTUP
When a server starts that has not previously communicated
with its failover peer, it must establish communications
with its failover peer and synchronize with it before it
can serve clients. This can happen either because you
have just configured your DHCP servers to perform failover
for the first time, or because one of your failover
servers has failed catastrophically and lost its database.
The initial recovery process is designed to ensure that
when one failover peer loses its database and then resyn-
chronizes, any leases that the failed server gave out
before it failed will be honored. When the failed server
starts up, it notices that it has no saved failover state,
and attempts to contact its peer.
When it has established contact, it asks the peer for a
complete copy its peer's lease database. The peer then
sends its complete database, and sends a message indicat-
ing that it is done. The failed server then waits until
MCLT has passed, and once MCLT has passed both servers
make the transition back into normal operation. This
waiting period ensures that any leases the failed server
may have given out while out of contact with its partner
will have expired.
While the failed server is recovering, its partner remains
in the partner-down state, which means that it is serving
all clients. The failed server provides no service at all
to DHCP clients until it has made the transition into nor-
mal operation.
In the case where both servers detect that they have never
before communicated with their partner, they both come up
in this recovery state and follow the procedure we have
just described. In this case, no service will be pro-
vided to DHCP clients until MCLT has expired.
CONFIGURING FAILOVER
In order to configure failover, you need to write a peer
9
dhcpd.conf(5)dhcpd.conf(5)
declaration that configures the failover protocol, and you
need to write peer references in each pool declaration for
which you want to do failover. You do not have to do
failover for all pools on a given network segment. You
must not tell one server it's doing failover on a particu-
lar address pool and tell the other it is not. You must
not have any common address pools on which you are not
doing failover.
The server currently does very little sanity checking,
so if you configure it wrong, it will just fail in odd
ways. I would recommend therefore that you either do
failover or don't do failover, but don't do any mixed
pools. Also, use the same master configuration file for
both servers, and have a seperate file that con-
tains the peer declaration and includes the master file.
This will help you to avoid configuration mismatches. As
our implementation evolves, this will become less of a
problem. A basic sample dhcpd.conf file for a primary
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;
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;
load balance max seconds 3;
}
include "/etc/dhcpd.master";
The statements in the peer declaration are as follows:
The primary and secondary statements
[ primary | secondary ];
This determines whether the server is primary or sec-
ondary, as described earlier under DHCP FAILOVER.
The address statement
address address;
The address statement declares the IP address on which
the server should listen for connections from its
failover peer, and also the value to use for the DHCP
Failover Protocol server identifier. Because this
10
dhcpd.conf(5)dhcpd.conf(5)
value is used as an identifier, it may not be omitted.
The peer address statement
peer address address;
The peer address statement declares the IP address to
which the server should connect to reach its failover
peer for failover messages.
The port statement
port port-number;
The port statement declares the TCP port on which the
server should listen for connections from its failover
peer. This statement may not currently be omitted,
because the failover protocol does not yet have a
reserved TCP port number.
The peer port statement
peer port port-number;
The peer port statement declares the TCP port to which
the server should connect to reach its failover peer
for failover messages. This statement may not be
omitted because the failover protocol does not yet have
a reserved TCP port number. The port number declared
in the peer port statement may be the same as the port
number declared in the port statement.
The max-response-delay statement
max-response-delay seconds;
The max-response-delay statement tells the DHCP server
how many seconds may pass without receiving a message
from its failover peer before it assumes that connec-
tion has failed. This number should be small enough
that a transient network failure that breaks the con-
nection will not result in the servers being out of
communication for a long time, but large enough that
the server isn't constantly making and breaking connec-
tions. This parameter must be specified.
The max-unacked-updates statement
max-unacked-updates count;
The max-unacked-updates statement tells the DHCP server
how many BNDUPD messages it can send before it receives
a BNDACK from the failover peer. We don't have enough
operational experience to say what a good value for
11
dhcpd.conf(5)dhcpd.conf(5)
this is, but 10 seems to work. This parameter must be
specified.
The mclt statement
mclt seconds;
The mclt statement defines the Maximum Client Lead
Time. It must be specified on the primary, and may
not be specified on the secondary. This is the length
of time for which a lease may be renewed by either
failover peer without contacting the other. The
longer you set this, the longer it will take for the
running server to recover IP addresses after moving
into PARTNER-DOWN state. The shorter you set it, the
more load your servers will experience when they are
not communicating. A value of something like 3600 is
probably reasonable, but again bear in mind that we
have no real operational experience with this.
The split statement
split index;
The split statement specifies the split between the
primary and secondary for the purposes of load balanc-
ing. Whenever a client makes a DHCP request, the DHCP
server runs a hash on the client identification. If
the hash comes out to less than the split value, the
primary answers. If it comes out to equal to or more
than the split, the secondary answers. This value
should generally be set to 128, and can only be config-
ured on the primary.
The hba statement
hba colon-seperated-hex-list;
The hba statement specifies the split between the pri-
mary and secondary as a bitmap rather than a cutoff,
which theoretically allows for finer-grained control.
In practice, there is probably no need for 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;
The load balance max seconds statement
load balance max seconds seconds;
This statement allows you to configure a cutoff after
which load balancing is disabled. The cutoff is based
on the number of seconds since the client sent its
12
dhcpd.conf(5)dhcpd.conf(5)
first DHCPDISCOVER or DHCPREQUEST message, and only
works with clients that correctly implement the secs
field - fortunately most clients do. We recommend set-
ting this to something like 3 or 5. The effect of this
is that if one of the failover peers gets into a state
where it is responding to failover messages but not
responding to some client requests, the other failover
peer will take over its client load automatically as
the clients retry.
CLIENT CLASSING
Clients can be seperated into classes, and treated differ-
ently depending on what class they are in. This sepera-
tion can be done either with a conditional statement, or
with a match statement within the class declaration. It
is possible to specify a limit on the total number of
clients within a particular class or subclass that may
hold leases at one time, and it is possible to specify
automatic subclassing based on the contents of the client
packet.
To add clients to classes based on conditional evaluation,
you can specify a matching expression in the class state-
ment:
class "ras-clients" {
match if substring (option dhcp-client-identifier, 1, 3) = "RAS";
}
Note that whether you use matching expressions or add
statements (or both) to classify clients, you must always
write a class declaration for any class that you use. If
there will be no match statement and no in-scope state-
ments for a class, the declaration should look like this:
class "ras-clients" {
}
SUBCLASSES
In addition to classes, it is possible to declare sub-
classes. A subclass is a class with the same name as a
regular class, but with a specific submatch expression
which is hashed for quick matching. This is essentially a
speed hack - the main difference between five classes with
match expressions and one class with five subclasses is
that it will be quicker to find the subclasses. Sub-
classes work as follows:
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);
}
13
dhcpd.conf(5)dhcpd.conf(5)
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 declara-
tion is a constant value to use in matching the match
expression for the class. When class matching is done,
the server will evaluate the match expression and then
look the result up in the hash table. If it finds a
match, the client is considered a member of both the class
and the subclass.
Subclasses can be declared with or without scope. In the
above example, the sole purpose of the subclass is to
allow some clients access to one address pool, while other
clients are given access to the other pool, so these sub-
classes are declared without scopes. If part of the pur-
pose of the subclass were to define different parameter
values for some clients, you might want to declare some
subclasses with scopes.
In the above example, if you had a single client that
needed some configuration parameters, while most didn't,
you might write the following 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 con-
trol address allocation on a per-client basis. However,
it's also possible to use subclassing in ways that are not
specific to clients - for example, to use the value of the
vendor-class-identifier option to determine what values to
send in the vendor-encapsulated-options option. An exam-
ple of this is shown under the VENDOR ENCAPSULATED OPTIONS
head in the dhcp-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 can be assigned leases. The effect of this
14
dhcpd.conf(5)dhcpd.conf(5)
will be to make it difficult for a new client in a class
to get an address. Once a class with such a limit has
reached its limit, the only way a new client in that class
can get a lease is for an existing client to relinquish
its lease, either by letting it expire, or by sending a
DHCPRELEASE packet. Classes with lease limits are speci-
fied as follows:
class "limited-1" {
lease limit 4;
}
This will produce a class in which a maximum of four mem-
bers may hold a lease at one time.
SPAWNING CLASSES
It is possible to declare a spawning class. A spawning
class is a class that automatically produces subclasses
based on what the client sends. The reason that spawning
classes were created was to make it possible to create
lease-limited classes on the fly. The envisioned appli-
cation is a cable-modem environment where the ISP wishes
to provide clients at a particular site with more than one
IP address, but does not wish to provide such clients with
their own subnet, nor give them an unlimited number of IP
addresses from the network segment to which they are con-
nected.
Many cable modem head-end systems can be configured to add
a Relay Agent Information option to DHCP packets when
relaying them to the DHCP server. These systems typi-
cally add a circuit ID or remote ID option that uniquely
identifies the customer site. To take advantage of 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 ID option will be checked against the class's hash
table. If a subclass is found that matches the circuit
ID, the client will be classified in that subclass and
treated accordingly. If no subclass is found matching
the circuit ID, a new one will be created and logged in
the dhcpd.leases file, and the client will be classified
in this new class. Once the client has been classified,
it will be treated according to the rules of the class,
including, in this case, being subject to the per-site
limit of four leases.
The use of the subclass spawning mechanism is not
restricted to relay agent options - this particular
15
dhcpd.conf(5)dhcpd.conf(5)
example is given only because it is a fairly straightfor-
ward one.
COMBINING MATCH, MATCH IF AND SPAWN WITH
In some cases, it may be useful to use one expression to
assign a client to a particular class, and a second
expression to put it into a subclass of that class. This
can be done by combining the match if and spawn with
statements, or the match if and match 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 spawn with expression without getting the clients in
the two classes confused with each other.
DYNAMIC DNS UPDATES
The DHCP server has the ability to dynamically update the
Domain Name System. Within the configuration files, you
can define how you want the Domain Name System to be
updated. These updates are RFC 2136 compliant so any DNS
server supporting RFC 2136 should be able to accept
updates from the DHCP server.
Two DNS update schemes are currently implemented, and
another is planned. The two that are currently available
are the ad-hoc DNS update mode and the interim DHCP-DNS
interaction draft update mode. If and when the DHCP-DNS
interaction draft and the DHCID draft make it through the
IETF standards process, there will be a third mode, which
will be the standard DNS update method. The DHCP server
must be configured to use one of the two currently-sup-
ported methods, or not to do dns updates. This can be
done with the ddns-update-style configuration parameter.
THE AD-HOC DNS UPDATE SCHEME
The ad-hoc Dynamic DNS update scheme implemented in this
version of the ISC DHCP server is a prototype design,
which does not have much to do with the standard update
method that is being standardized in the IETF DHC working
group, but rather implements some very basic, yet useful,
update capabilities. This mode does not work with the
failover protocol because it does not account for the
16
dhcpd.conf(5)dhcpd.conf(5)
possibility of two different DHCP servers updating the
same set of DNS records.
For the ad-hoc DNS update method, the client's FQDN is
derived in two parts. First, the hostname is determined.
Then, the domain name is determined, and appended to the
hostname.
The DHCP server determines the client's hostname by first
looking for a ddns-hostname configuration option, and
using that if it is present. If no such option is pre-
sent, the server looks for a valid hostname in the FQDN
option sent by the client. If one is found, it is used;
otherwise, if the client sent a host-name option, that is
used. Otherwise, if there is a host declaration that
applies to the client, the name from that declaration will
be used. If none of 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 server
configuration, not on what the client sends. First, if
there is a ddns-domainname configuration option, it is
used. Second, if there is a domain-name option config-
ured, that is used. Otherwise, the server will not do the
DNS update.
The client's fully-qualified domain name, derived as we
have described, 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 assigned in its lease. If there is
already an A record with the same name in the 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 of some network server. For example, if you have a
fileserver called "fs.sneedville.edu", and the client
claims its hostname is "fs", no DNS update will be done
for that client, and an error message will be logged.
If the A record update succeeds, a PTR record update for
the assigned IP address will be done, pointing to the A
record. This update is unconditional - it will be done
even if another PTR record of the same name exists.
Since the IP address has been assigned to the DHCP server,
this should be safe.
Please note that the current implementation assumes
clients only have a single network interface. A client
with two network interfaces will see unpredictable behav-
ior. This is considered a bug, and will be fixed in a
later release. It may be helpful to enable the one-
lease-per-client parameter so that roaming clients do not
trigger this same behavior.
17
dhcpd.conf(5)dhcpd.conf(5)
The DHCP protocol normally involves a four-packet exchange
- first the client sends a DHCPDISCOVER message, then the
server sends a DHCPOFFER, then the client sends a DHCPRE-
QUEST, then the server sends a DHCPACK. In the current
version of the server, the server will do a DNS update
after it has received the DHCPREQUEST, and before it has
sent the DHCPACK. It only sends the DNS update if it has
not sent one for the client's address before, in order to
minimize the impact on the DHCP server.
When the client's lease expires, the DHCP server (if it is
operating at the time, or when next it operates) will
remove the client's A and PTR records from the DNS
database. If the client releases its lease by sending a
DHCPRELEASE message, the server will likewise remove the A
and PTR records.
THE INTERIM DNS UPDATE SCHEME
The interim DNS update scheme operates mostly according to
several drafts that are being considered by the IETF and
are expected to become standards, but are not yet stan-
dards, and may not be standardized 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, we will briefly document the operation of this
update style here.
The first point to understand about this style of DNS
update is that unlike the ad-hoc style, the DHCP server
does not necessarily always update both the A and the PTR
records. The FQDN option includes a flag which, when
sent by the client, indicates that the client wishes to
update its own A record. In that case, the server can be
configured either to honor the client's intentions or
ignore them. This is done with the statement allow
client-updates; or the statement ignore client-updates;.
By default, client updates are allowed.
If the server is configured to allow client updates, then
if the client sends a fully-qualified domain name in the
FQDN option, the server will use that name the client sent
in the FQDN option to update the PTR record. For exam-
ple, let us say that the client is a visitor from the
"radish.org" domain, whose hostname is "jschmoe". The
server is for the "example.org" domain. The DHCP client
indicates in the FQDN option that its FQDN is
"jschmoe.radish.org.". It also indicates that it wants
to update its own A record. The DHCP server therefore
does not attempt to set up an A record for the client, but
18
dhcpd.conf(5)dhcpd.conf(5)
does set up a PTR record for the IP address that it
assigns the client, pointing at jschmoe.radish.org. Once
the DHCP client has an IP 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 the client doesn't want to do its own update, the
server will simply choose a name for the client, possibly
using the hostname supplied by the client ("jschmoe" in
the previous example). It will use its own domain 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 it chose for the client. If the client sends a
fully-qualified domain name in the fqdn option, the server
uses only the leftmost part of the domain name - in the
example above, "jschmoe" instead of "jschmoe.radish.org".
The other difference between the ad-hoc scheme and the
interim scheme is that with the interim scheme, a method
is used that allows more than one DHCP server to update
the DNS database without accidentally deleting A records
that shouldn't be deleted nor failing to add A records
that should be added. The scheme works as follows:
When the DHCP server issues a client a new lease, it cre-
ates a text string that is an MD5 hash over the DHCP
client's identification (see draft-ietf-dnsext-dhcid-
rr-??.txt for details). The update adds an A record with
the name the server chose and a TXT record containing the
hashed identifier string (hashid). If this update suc-
ceeds, the server is done.
If the update fails because the A record already exists,
then the DHCP server attempts to add the A record with the
prerequisite that there must be a TXT record in the same
name as the new A record, and that TXT record's contents
must be equal to hashid. If this update succeeds, then
the client has its A record and PTR record. If it fails,
then the name the client has been assigned (or requested)
is in use, and can't be used by the client. At this
point the DHCP server gives up trying to do a DNS update
for the client until the client chooses 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 of the drafts call for a new DHCID
RRtype, but this is not yet available. The interim DNS
update scheme uses a TXT record instead. Also, the
existing ddns-resolution draft calls for the DHCP server
to put a DHCID RR on the PTR record, but the interim
update method does not do this. It is our position that
this is not useful, and we are working with the author in
hopes of removing it from the next version of the draft,
19
dhcpd.conf(5)dhcpd.conf(5)
or better understanding why it is considered useful.
In addition to these differences, the server also does not
update very aggressively. Because each DNS update
involves a round trip to the DNS server, there is a cost
associated with doing updates even if they do not actually
modify the DNS database. So the DHCP server tracks
whether or not it has updated the record in the past (this
information is stored on the lease) and does not attempt
to update records that it thinks it has already updated.
This can lead to cases where the DHCP server adds a
record, and then the record is deleted through some other
mechanism, but the server never again updates the DNS
because it thinks the data is already there. In this
case the data can be removed from the lease through opera-
tor intervention, and once this has been done, the DNS
will be updated 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, you should use TSIG signatures -
a method of cryptographically signing updates using a
shared secret key. As long as you protect the secrecy of
this key, your updates should also be secure. Note, how-
ever, that the DHCP protocol itself provides no security,
and that clients can therefore provide information to the
DHCP server which the DHCP server will then use in its
updates, with the constraints described previously.
The DNS server must be configured to allow updates for any
zone that the DHCP server will be updating. For example,
let us say that clients in the sneedville.edu domain will
be assigned addresses on the 10.10.17.0/24 subnet. In
that case, you will need a key declaration for 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 for the 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;
20
dhcpd.conf(5)dhcpd.conf(5)
file "10.10.17.db";
allow-update { key DHCP_UPDATER; };
};
You will also have to configure your DHCP server to do
updates to these zones. To do so, you need to add some-
thing like this to your dhcpd.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;
}
Note that the zone declarations have to correspond to
authority records in your name server - in the above exam-
ple, there must be an SOA record for "example.org." and
for "17.10.10.in-addr.arpa.". For example, if there were
a subdoman "foo.example.org" with no seperate SOA, you
could not write a zone declaration for "foo.example.org."
Also keep in mind that zone names in your DHCP configura-
tion 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 DHCP configura-
tion, zone names are not encapsulated in quotes where
there are in the DNS configuration.
You should choose your own secret key, of course. The ISC
BIND 8 and 9 distributions come with a program for gener-
ating secret keys called dnssec-keygen. The version that
comes with BIND 9 is likely to produce a substantially
more random key, so we recommend you use that one even if
you are not using BIND 9 as your DNS server. If you are
using BIND 9's dnssec-keygen, the above key would be cre-
ated 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 will
generate 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:
21
dhcpd.conf(5)dhcpd.conf(5)
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. For more information on configuring ISC BIND,
consult the documentation that accompanies it.
REFERENCE: EVENTS
There are three kinds of events that can happen regarding
a lease, and it is possible to declare statements that
occur when any of these events happen. These events are
the commit event, when the server has made a commitment of
a certain lease to a client, the release event, 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, you must 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 DNS updates, so you should
not define your own event handlers if you are using the
built-in DNS update mechanism.
The built-in version of the DNS update mechanism is in a
text string towards the top of server/dhcpd.c. If you
want to use events for things other than DNS updates, and
you also want DNS updates, you will have to start out by
copying this code into your dhcpd.conf file and modifying
it.
REFERENCE: DECLARATIONS
The shared-network statement
shared-network name {
[ parameters ]
22
dhcpd.conf(5)dhcpd.conf(5)
[ declarations ]
}
The shared-network statement is used to inform the DHCP
server that some IP subnets actually share the same physi-
cal network. Any subnets in a shared network should be
declared within a shared-network statement. Parameters
specified in the shared-network statement will be used
when booting clients on those subnets unless parameters
provided at the subnet or host level override them. If
any subnet in a shared network has addresses available for
dynamic allocation, those addresses are collected into a
common pool for that shared network and assigned to
clients as needed. There is no way to distinguish on
which subnet of a shared network a client should boot.
Name should be the name of the shared network. This name
is used when printing debugging messages, so it should be
descriptive for the shared 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 arbitrary name,
enclosed in quotes.
The subnet statement
subnet subnet-number netmask netmask {
[ parameters ]
[ declarations ]
}
The subnet statement is used to provide dhcpd with enough
information to tell whether or not an IP address is on
that subnet. It may also be used to provide subnet-spe-
cific parameters and to specify what addresses may be
dynamically allocated to clients booting on that subnet.
Such addresses are specified using the range declaration.
The subnet-number should be an IP address or domain name
which resolves to the subnet number of the subnet being
described. The netmask should be an IP address or domain
name which resolves to the subnet mask of the subnet being
described. The subnet number, together with the netmask,
are sufficient to determine whether any given IP address
is on the specified subnet.
Although a netmask must be given with every subnet decla-
ration, it is recommended that if there is any variance in
subnet masks at a site, a subnet-mask option statement be
used in each subnet declaration to set the desired subnet
mask, since any subnet-mask option statement will override
the subnet mask declared in the subnet statement.
The range statement
23
dhcpd.conf(5)dhcpd.conf(5)
range [ dynamic-bootp ] low-address [ high-address];
For any subnet on which addresses will be assigned dynami-
cally, there must be at least one range statement. The
range statement gives the lowest and highest IP addresses
in a range. All IP addresses in the range should be in
the subnet in which the range statement is declared. The
dynamic-bootp flag may be specified if addresses in the
specified range may be dynamically assigned to BOOTP
clients as well as DHCP clients. When specifying a sin-
gle address, high-address can be omitted.
The host statement
host hostname {
[ parameters ]
[ declarations ]
}
There must be at least one host statement for every BOOTP
client that is to be served. host statements may also be
specified for DHCP clients, although this is not required
unless booting is only enabled for known hosts.
If it is desirable to be able to boot a DHCP or BOOTP
client on more than one subnet with fixed addresses, more
than one address may be specified in the fixed-address
parameter, or more than one host statement may be speci-
fied.
If client-specific boot parameters must change based on
the network to which the client is attached, then multiple
host statements should be used.
If a client is to be booted using a fixed address if it's
possible, but should be allocated a dynamic address other-
wise, then a host statement must be specified without a
fixed-address clause. hostname should be a name identify-
ing the host. If a hostname option is not specified for
the host, hostname is used.
Host declarations are matched to actual DHCP or BOOTP
clients by matching the dhcp-client-identifier option
specified in the host declaration to the one supplied by
the client, or, if the host declaration or the client does
not provide a dhcp-client-identifier option, by matching
the hardware parameter in the host declaration to the net-
work hardware address supplied by the client. BOOTP
clients do not normally provide a dhcp-client-identifier,
so the hardware address must be used for all clients that
may boot using the BOOTP protocol.
The group statement
24
dhcpd.conf(5)dhcpd.conf(5)
group {
[ parameters ]
[ declarations ]
}
The group statement is used simply to apply one or more
parameters to a group of declarations. It can be used to
group hosts, shared networks, subnets, or even other
groups.
REFERENCE: ALLOW AND DENY
The allow and deny statements can be used to control the
response of the DHCP server to various sorts of requests.
The allow and deny keywords actually have different mean-
ings depending on the context. In a pool context, these
keywords can be used to set up access lists for address
allocation pools. In other contexts, the keywords simply
control general server behavior with respect to clients
based on scope. In a non-pool context, the ignore key-
word can be used in place of the deny keyword 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
pool declarations.
The unknown-clients keyword
allow unknown-clients;
deny unknown-clients;
ignore unknown-clients;
The unknown-clients flag is used to tell dhcpd whether or
not to dynamically assign addresses to unknown clients.
Dynamic address assignment to unknown clients is allowed
by default. An unknown client is simply a client that has
no host declaration.
The bootp keyword
allow bootp;
deny bootp;
ignore bootp;
The bootp flag is used to tell dhcpd whether or not to
respond to bootp queries. Bootp queries are allowed by
default.
The booting keyword
allow booting;
deny booting;
25
dhcpd.conf(5)dhcpd.conf(5)
ignore booting;
The booting flag is used to tell dhcpd whether or not to
respond to queries from a particular client. This keyword
only has meaning when it appears in a host declaration.
By default, booting is allowed, but if it is disabled for
a particular client, then that client will not be able to
get and address from the DHCP server. The duplicates key-
word
allow duplicates;
deny duplicates;
Host declarations can match client messages based on the
DHCP Client Identifer option or based on the client's net-
work hardware type and MAC address. If the MAC address
is used, the host declaration will match any client with
that MAC address - even clients with different client
identifiers. This doesn't normally happen, but is possi-
ble when 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 is received from a client that matches the MAC
address of a host declaration, any other leases matching
that MAC address should be discarded by the server, even
if the UID is not the same. This is a violation of the
DHCP protocol, but can prevent clients whose client iden-
tifiers change regularly from holding many leases at the
same time. By default, duplicates are allowed. The
declines keyword
allow declines;
deny declines;
ignore declines;
The DHCPDECLINE message is used by DHCP clients to indi-
cate that the lease the server has offered is not valid.
When the server receives a DHCPDECLINE for a particular
address, it normally abandons that address, assuming that
some unauthorized system is using it. Unfortunately, a
malicious or buggy client can, using DHCPDECLINE messages,
completely exhaust the DHCP server's allocation pool.
The server will reclaim these leases, but while the client
is running through the pool, it may cause serious thrash-
ing in the DNS, and it will also cause the DHCP server to
forget old DHCP client address allocations.
The declines flag tells the DHCP server whether or not to
honor DHCPDECLINE messages. If it is set to deny or
ignore in a particular scope, the DHCP server will not
respond to DHCPDECLINE messages. The client-updates key-
word
26
dhcpd.conf(5)dhcpd.conf(5)
allow client-updates;
deny client-updates;
The client-updates flag tells the DHCP server whether or
not to honor the client's intention to do its own update
of its A record. This is only relevant when doing interim
DNS updates. See the documentation under the heading THE
INTERIM DNS UPDATE SCHEME for details.
ALLOW AND DENY WITHIN POOL DECLARATIONS
The uses of the allow and deny keywords shown in the pre-
vious section work pretty much the same way whether the
client is sending a DHCPDISCOVER or a DHCPREQUEST message
- an address will be allocated to the client (either the
old address it's requesting, or a new address) and then
that address will be tested to see if it's okay to let the
client have it. If the client requested it, and it's not
okay, the server will send a DHCPNAK message. Otherwise,
the server will simply not respond to the client. If it
is okay to give the address to the client, the server will
send a DHCPACK message.
The primary motivation behind pool declarations is to have
address allocation pools whose allocation policies are
different. A client may be denied access to one pool,
but allowed access to another pool on the same network
segment. In order for this to work, access control has
to be done during address allocation, not after address
allocation is done.
When a DHCPREQUEST message is processed, address alloca-
tion simply consists of looking up the address the client
is requesting and seeing if it's still available for the
client. If it is, then the DHCP server checks both the
address pool permit lists and the relevant in-scope allow
and deny statements to see if it's okay to give the lease
to the client. In the case of a DHCPDISCOVER message, the
allocation process is done as described previously in the
ADDRESS ALLOCATION section.
When declaring permit lists for address allocation pools,
the following syntaxes are recognized following the allow
or deny keywords:
known clients;
If specified, this statement either allows or prevents
allocation from this pool to any client that has a host
declaration (i.e., is known). A client is known if it has
a host declaration in any scope, not just the current
scope.
unknown clients;
27
dhcpd.conf(5)dhcpd.conf(5)
If specified, this statement either allows or prevents
allocation from this pool to any client that has no host
declaration (i.e., is not known).
members of "class";
If specified, this statement either allows or prevents
allocation from this pool to any client that is a member
of the named class.
dynamic bootp clients;
If specified, this statement either allows or prevents
allocation from this pool to any bootp client.
authenticated clients;
If specified, this statement either allows or prevents
allocation from this pool to any client that has been
authenticated using the DHCP authentication protocol.
This is not yet supported.
unauthenticated clients;
If specified, this statement either allows or prevents
allocation from this pool to any client that has not been
authenticated using the DHCP authentication protocol.
This is not yet supported.
all clients;
If specified, this statement either allows or prevents
allocation from this pool to all clients. This can be
used when you want to write a pool declaration for some
reason, but hold it in reserve, or when you want to renum-
ber your network quickly, and thus want the server to
force all clients that have been allocated addresses from
this pool to obtain new addresses immediately when they
next renew.
REFERENCE: PARAMETERS
The always-broadcast statement
always-broadcast flag;
The DHCP and BOOTP protocols both require DHCP and
BOOTP clients to set the broadcast bit in the flags
field of the BOOTP message header. Unfortunately, some
DHCP and BOOTP clients do not do this, and therefore
may not receive responses from the DHCP server. The
DHCP server can be made to always broadcast its
responses to clients by setting this flag to 'on' for
the relevant scope. To avoid creating excess broad-
cast traffic on your network, we recommend that you
28
dhcpd.conf(5)dhcpd.conf(5)
restrict the use of this option to as few clients as
possible. For example, the Microsoft DHCP client is
known not to have this problem, as are the OpenTrans-
port and ISC DHCP clients.
The always-reply-rfc1048 statement
always-reply-rfc1048 flag;
Some BOOTP clients expect RFC1048-style responses, but
do not follow RFC1048 when sending their requests.
You can tell that a client is having this problem if it
is not getting the options you have configured for it
and if you see in the server log the message "(non-
rfc1048)" printed with each BOOTREQUEST that is logged.
If you want to send rfc1048 options to such a client,
you can set the always-reply-rfc1048 option in that
client's host declaration, and the DHCP server will
respond with an RFC-1048-style vendor options field.
This flag can be set in any scope, and will affect all
clients covered by that scope.
The authoritative statement
authoritative;
not authoritative;
The DHCP server will normally assume that the configu-
ration information about a given network segment is not
known to be correct and is not authoritative. This is
so that if a naive user installs a DHCP server not
fully understanding how to configure it, it does not
send spurious DHCPNAK messages to clients that have
obtained addresses from a legitimate DHCP server on the
network.
Network administrators setting up authoritative DHCP
servers for their networks should always write authori-
tative; at the top of their configuration file to indi-
cate that the DHCP server should send DHCPNAK messages
to misconfigured clients. If this is not done,
clients will be unable to get a correct IP address
after changing subnets until their old lease has
expired, which could take quite a long time.
Usually, writing authoritative; at the top level of the
file should be sufficient. However, if a DHCP server
is to be set up so that it is aware of some networks
for which it is authoritative and some networks for
which it is not, it may be more appropriate to declare
authority on a per-network-segment basis.
29
dhcpd.conf(5)dhcpd.conf(5)
Note that the most specific scope for which the concept
of authority makes any sense is the physical network
segment - either a shared-network statement or a subnet
statement that is not contained within a shared-network
statement. It is not meaningful to specify that the
server is authoritative for some subnets within a
shared network, but not authoritative for others, nor
is it meaningful to specify that the server is authori-
tative for some host declarations and not others.
The boot-unknown-clients statement
boot-unknown-clients name;
If the boot-unknown-clients statement is present and
has a value of false or off, then clients for which
there is no host declaration will not be allowed to
obtain IP addresses. If this statement is not present
or has a value of true or on, then clients without host
declarations will be allowed to obtain IP addresses, as
long as those addresses are not restricted by allow and
deny statements within their pool declarations.
The ddns-hostname statement
ddns-hostname name;
The name parameter should be the hostname that will be
used in setting up the client's A and PTR records. If
no ddns-hostname is specified in scope, then the server
will derive the hostname automatically, using an algo-
rithm that varies for each of the different update
methods.
The ddns-domainname statement
ddns-domainname name;
The name parameter should be the domain name that will
be appended to the client's hostname to form a fully-
qualified domain-name (FQDN).
The ddns-rev-domainname statement
ddns-rev-domainname name; The name parameter should be
the domain name that will be appended to the client's
reversed IP address to produce a name for use in the
client's PTR record. By default, this is "in-
addr.arpa.", but the default can be overridden here.
The reversed IP address to which this domain name is
appended is always the IP address of the client, in
dotted quad notation, reversed - for example, if the IP
address assigned to the client is 10.17.92.74, then the
30
dhcpd.conf(5)dhcpd.conf(5)
reversed IP address is 74.92.17.10. So a client with
that IP address would, by default, be given a PTR
record of 10.17.92.74.in-addr.arpa.
The ddns-update-style parameter
ddns-update-style style;
The style parameter must be one of ad-hoc, interim or
none. The ddns-update-style statement is only meaning-
ful in the outer scope - it is evaluated once after
reading the dhcpd.conf file, rather than each time a
client is assigned an IP address, so there is no way to
use different DNS update styles for different clients.
The ddns-updates statement
ddns-updates flag;
The ddns-updates parameter controls whether or not the
server will attempt to do a DNS update when a lease is
confirmed. Set this to off if the server should not
attempt to do updates within a certain scope. The
ddns-updates parameter is on by default. To disable
DNS updates in all scopes, it is preferable to use the
ddns-update-style statement, setting the style to none.
The default-lease-time statement
default-lease-time time;
Time should be the length in seconds that will be
assigned to a lease if the client requesting the lease
does not ask for a specific expiration time.
The dynamic-bootp-lease-cutoff statement
dynamic-bootp-lease-cutoff date;
The dynamic-bootp-lease-cutoff statement sets the end-
ing time for all leases assigned dynamically to BOOTP
clients. Because BOOTP clients do not have any way of
renewing leases, and don't know that their leases could
expire, by default dhcpd assignes infinite leases to
all BOOTP clients. However, it may make sense in some
situations to set a cutoff date for all BOOTP leases -
for example, the end of a school term, or the time at
night when a facility is closed and all machines are
required to be powered off.
Date should be the date on which all assigned BOOTP
leases will end. The date is specified in the form:
W YYYY/MM/DD HH:MM:SS
31
dhcpd.conf(5)dhcpd.conf(5)
W is the day of the week expressed as a number from
zero (Sunday) to six (Saturday). YYYY is the year,
including the century. MM is the month expressed as a
number from 1 to 12. DD is the day of the month,
counting from 1. HH is the hour, from zero to 23. MM
is the minute and SS is the second. The time is always
in Coordinated Universal Time (UTC), not local time.
The dynamic-bootp-lease-length statement
dynamic-bootp-lease-length length;
The dynamic-bootp-lease-length statement is used to set
the length of leases dynamically assigned to BOOTP
clients. At some sites, it may be possible to assume
that a lease is no longer in use if its holder has not
used BOOTP or DHCP to get its address within a certain
time period. The period is specified in length as a
number of seconds. If a client reboots using BOOTP
during the timeout period, the lease duration is reset
to length, so a BOOTP client that boots frequently
enough will never lose its lease. Needless to say,
this parameter should be adjusted with extreme caution.
The filename statement
filename "filename";
The filename statement can be used to specify the name
of the initial boot file which is to be loaded by a
client. The filename should be a filename recognizable
to whatever file transfer protocol the client can be
expected to use to load the file.
The fixed-address statement
fixed-address address [, address ... ];
The fixed-address statement is used to assign one or
more fixed IP addresses to a client. It should only
appear in a host declaration. If more than one address
is supplied, then when the client boots, it will be
assigned the address which corresponds to the network
on which it is booting. If none of the addresses in
the fixed-address statement are on the network on which
the client is booting, that client will not match the
host declaration containing that fixed-address state-
ment. Each address should be either an IP address or a
domain name which resolves to one or more IP addresses.
The get-lease-hostnames statement
get-lease-hostnames flag;
32
dhcpd.conf(5)dhcpd.conf(5)
The get-lease-hostnames statement is used to tell dhcpd
whether or not to look up the domain name corresponding
to the IP address of each address in the lease pool and
use that address for the DHCP hostname option. If flag
is true, then this lookup is done for all addresses in
the current scope. By default, or if flag is false,
no lookups are done.
The hardware statement
hardware hardware-type hardware-address;
In order for a BOOTP client to be recognized, its net-
work hardware address must be declared using a hardware
clause in the host statement. hardware-type must be
the name of a physical hardware interface type. Cur-
rently, only the ethernet and token-ring types are rec-
ognized, although support for a fddi hardware type (and
others) would also be desirable. The hardware-address
should be a set of hexadecimal octets (numbers from 0
through ff) seperated by colons. The hardware state-
ment may also be used for DHCP clients.
The lease-file-name statement
lease-file-name name;
Name should be the name of the DHCP server's lease
file. By default, this is /var/db/dhcpd.leases.
This statement must appear in the outer scope of the
configuration file - if it appears in some other scope,
it will have no effect.
The local-port statement
local-port port;
This statement causes the DHCP server to listen for
DHCP requests on the UDP port specified in port, rather
than on port 67.
The log-facility statement
log-facility facility;
This statement causes the DHCP server to do all of its
logging on the specified log facility once the
dhcpd.conf file has been read. By default the DHCP
server logs to the daemon facility. Possible log
facilities include auth, authpriv, cron, daemon, ftp,
kern, lpr, mail, mark, news, ntp, security, syslog,
user, uucp, and local0 through local7. Not all of
these facilities are available on all systems, and
there may be other facilities available on other
33
dhcpd.conf(5)dhcpd.conf(5)
systems.
In addition to setting this value, you may need to mod-
ify your syslog.conf file to configure logging of the
DHCP server. For example, you might add a line like
this:
local7.debug /var/log/dhcpd.log
The syntax of the syslog.conf file may be different on
some operating systems - consult the syslog.conf manual
page to be sure. To get syslog to start logging to the
new file, you must first create the file with correct
ownership and permissions (usually, the same owner and
permissions of your /var/log/messages or /usr/adm/mes-
sages file should be fine) and send a SIGHUP to sys-
logd. Some systems support log rollover using a shell
script or program called newsyslog or logrotate, and
you may be able to configure this as well so that your
log file doesn't grow uncontrollably.
Because the log-facility setting is controlled by the
dhcpd.conf file, log messages printed while parsing the
dhcpd.conf file or before parsing it are logged to the
default log facility. To prevent this, see the README
file included with this distribution, which describes
how to change the default log facility. When this
parameter is used, the DHCP server prints its startup
message a second time after parsing the configuration
file, so that the log will be as complete as possible.
The max-lease-time statement
max-lease-time time;
Time should be the maximum length in seconds that will
be assigned to a lease. The only exception to this is
that Dynamic BOOTP lease lengths, which are not speci-
fied by the client, are not limited by this maximum.
The min-lease-time statement
min-lease-time time;
Time should be the minimum length in seconds that will
be assigned to a lease.
The min-secs statement
min-secs seconds;
Seconds should be the minimum number of seconds since a
client began trying to acquire a new lease before the
DHCP server will respond to its request. The number of
34
dhcpd.conf(5)dhcpd.conf(5)
seconds is based on what the client reports, and the
maximum value that the client can report is 255 sec-
onds. Generally, setting this to one will result in
the DHCP server not responding to the client's first
request, but always responding to its second request.
This can be used to set up a secondary DHCP server
which never offers an address to a client until the
primary server has been given a chance to do so. If
the primary server is down, the client will bind to the
secondary server, but otherwise clients should always
bind to the primary. Note that this does not, by
itself, permit a primary server and a secondary server
to share a pool of dynamically-allocatable addresses.
The next-server statement
next-server server-name;
The next-server statement is used to specify the host
address of the server from which the initial boot file
(specified in the filename statement) is to be loaded.
Server-name should be a numeric IP address or a domain
name. If no next-server parameter applies to a given
client, the DHCP server's IP address is used.
The omapi-port statement
omapi-port port;
The omapi-port statement causes the DHCP server to lis-
ten for OMAPI connections on the specified port. This
statement is required to enable the OMAPI protocol,
which is used to examine and modify the state of the
DHCP server as it is running.
The one-lease-per-client statement
one-lease-per-client flag;
If this flag is enabled, whenever a client sends a
DHCPREQUEST for a particular lease, the server will
automatically free any other leases the client holds.
This presumes that when the client sends a DHCPREQUEST,
it has forgotten any lease not mentioned in the DHCPRE-
QUEST - i.e., the client has only a single network
interface and it does not remember leases it's holding
on networks to which it is not currently attached.
Neither of these assumptions are guaranteed or prov-
able, so we urge caution in the use of this statement.
The pid-file-name statement
pid-file-name name;
35
dhcpd.conf(5)dhcpd.conf(5)
Name should be the name of the DHCP server's process ID
file. This is the file in which the DHCP server's
process ID is stored when the server starts. By
default, this is /var/run/dhcpd.pid. Like the lease-
file-name statement, this statement must appear in the
outer scope of the configuration file.
The ping-check statement
ping-check flag;
When the DHCP server is considering dynamically allo-
cating an IP address to a client, it first sends an
ICMP Echo request (a ping) to the address being
assigned. It waits for a second, and if no ICMP Echo
response has been heard, it assigns the address. If a
response is heard, the lease is abandoned, and the
server does not respond to the client.
This ping check introduces a one-second delay in
responding to DHCPDISCOVER messages, which can be a
problem for some clients. The ping-check configura-
tion parameter can be used to control checking - if its
value is false, no ping check is done.
The server-identifier statement
server-identifier hostname;
The server-identifier statement can be used to define
the value that is sent in the DHCP Server Identifier
option for a given scope. The value specified must be
an IP address for the DHCP server, and must be reach-
able by all clients served by a particular scope.
The use of the server-identifier statement is not rec-
ommended - the only reason to use it is to force a
value other than the default value to be sent on occa-
sions where the default value would be incorrect. The
default value is the first IP address associated with
the physical network interface on which the request
arrived.
The usual case where the server-identifier statement
needs to be sent is when a physical interface has more
than one IP address, and the one being sent by default
isn't appropriate for some or all clients served by
that interface. Another common case is when an alias
is defined for the purpose of having a consistent IP
address for the DHCP server, and it is desired that the
clients use this IP address when contacting the server.
Supplying a value for the dhcp-server-identifier option
is equivalent to using the server-identifier statement.
36
dhcpd.conf(5)dhcpd.conf(5)
The server-name statement
server-name name ;
The server-name statement can be used to inform the
client of the name of the server from which it is boot-
ing. Name should be the name that will be provided to
the client.
The site-option-space statement
site-option-space name ;
The site-option-space statement can be used to deter-
mine from what option space site-local options will be
taken. This can be used in much the same way as the
vendor-option-space statement. Site-local options in
DHCP are those options whose numeric codes are greater
than 128. These options are intended for site-spe-
cific uses, but are frequently used by vendors of
embedded hardware that contains DHCP clients. Because
site-specific options are allocated on an ad hoc basis,
it is quite possible that one vendor's DHCP client
might use the same option code that another vendor's
client uses, for different purposes. The site-option-
space option can be used to assign a different set of
site-specific options for each such vendor, using con-
ditional evaluation (see dhcp-eval.5 for details).
The stash-agent-options statement
stash-agent-options flag;
If the stash-agent-options parameter is true for a
given client, the server will record the relay agent
information options sent during the client's initial
DHCPREQUEST message when the client was in the SELECT-
ING state and behave as if those options are included
in all subsequent DHCPREQUEST messages sent in the
RENEWING state. This works around a problem with
relay agent information options, which is that they
usually not appear in DHCPREQUEST messages sent by the
client in the RENEWING state, because such messages are
unicast directly to the server and not sent through a
relay agent.
The update-optimization statement
update-optimization flag;
If the update-optimization parameter is false for a
given client, the server will attempt a DNS update for
that client each time the client renews its lease,
rather than only attempting an update when it appears
37
dhcpd.conf(5)dhcpd.conf(5)
to be necessary. This will allow the DNS to heal from
database inconsistencies more easily, but the cost is
that the DHCP server must do many more DNS updates.
We do not recommend enabling this on large networks
with the current DHCP server. This option only
affects the behavior of the interim DNS update scheme,
and has no effect on the ad-hoc DNS update scheme. If
this parameter is not specified, or is false, the DHCP
server will only update when the client information
changes, the client gets a different lease, or the
client's lease expires.
The update-static-leases statement
update-static-leases flag;
The update-static-leases flag, if enabled, causes the
DHCP server to do DNS updates for clients even if those
clients are being assigned their IP address using a
fixed-address statement - that is, the client is being
given a static assignment. This can only work with
the interim DNS update scheme. It is not recommended
because the DHCP server has no way to tell that the
update has been done, and therefore will not delete the
record when it is not in use. Also, the server must
attempt the update each time the client renews its
lease, which could have a significant performance
impact in environments that place heavy demands on the
DHCP server.
The use-host-decl-names statement
use-host-decl-names flag;
If the use-host-decl-names parameter is true in a given
scope, then for every host declaration within that
scope, the name provided for the host declaration will
be supplied to the client as its hostname. So, for
example,
group {
use-host-decl-names on;
host joe {
hardware ethernet 08:00:2b:4c:29:32;
fixed-address joe.fugue.com;
}
}
is equivalent to
host joe {
hardware ethernet 08:00:2b:4c:29:32;
fixed-address joe.fugue.com;
38
dhcpd.conf(5)dhcpd.conf(5)
option host-name "joe";
}
An option host-name statement within a host declaration
will override the use of the name in the host declara-
tion.
It should be noted here that most DHCP clients com-
pletely ignore the host-name option sent by the DHCP
server, and there is no way to configure them not to do
this. So you generally have a choice of either not
having any hostname to client IP address mapping that
the client will recognize, or doing DNS updates. It
is beyond the scope of this document to describe how to
make this determination.
The use-lease-addr-for-default-route statement
use-lease-addr-for-default-route flag;
If the use-lease-addr-for-default-route parameter is
true in a given scope, then instead of sending the
value specified in the routers option (or sending no
value at all), the IP address of the lease being
assigned is sent to the client. This supposedly
causes Win95 machines to ARP for all IP addresses,
which can be helpful if your router is configured for
proxy ARP. The use of this feature is not recom-
mended, because it won't work for many DHCP clients.
The vendor-option-space statement
vendor-option-space string;
The vendor-option-space parameter determines from what
option space vendor options are taken. The use of
this configuration parameter is illustrated in the
dhcp-options(5) manual page, in the VENDOR ENCAPSULATED
OPTIONS section.
SETTING PARAMETER VALUES USING EXPRESSIONS
Sometimes it's helpful to be able to set the value of a
DHCP server parameter based on some value that the client
has sent. To do this, you can use expression evaluation.
The dhcp-eval(5) manual page describes how to write
expressions. To assign the result of an evaluation to an
option, define the option as follows:
my-parameter = expression ;
For example:
ddns-hostname = binary-to-ascii (16, 8, "-",
substring (hardware, 1, 6));
39
dhcpd.conf(5)dhcpd.conf(5)REFERENCE: OPTION STATEMENTS
DHCP option statements are documented in the dhcp-
options(5) manual page.
REFERENCE: EXPRESSIONS
Expressions used in DHCP option statements and elsewhere
are documented in the dhcp-eval(5) manual page.
SEE ALSOdhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5),
RFC2132, RFC2131.
AUTHORdhcpd.conf(5) was written by Ted Lemon <mellon@vix.com>
under a contract with Vixie Labs. Funding for this pro-
ject was provided by the Internet Software Consortium.
Information about the Internet Software Consortium can be
found at http://www.isc.org/isc.
40
