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 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
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 may 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,
there is currently no way to group parameter assignments
other than by network topology.
When a client is to be booted, its boot parameters are
determined by first consulting that client's host declara
tion (if any), then consulting the group declaration (if
any) which enclosed that host declaration, then consulting
the subnet declaration for the subnet on which the client
is booting, then consulting the shared-network declaration
(if any) containing that subnet, and finally consulting
the top-level parameters which may be specified outside of
any declaration.
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. If no such entry is found,
then dhcpd acts as if there is no entry in the dhcpd.conf
file for that client, even if there is an entry for that
client on a different subnet or shared network.
EXAMPLES
A typical dhcpd.conf file will look something like this:
global parameters...
shared-network ISC-BIGGIE {
shared-network-specific 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...
}
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, it's legal to specify host
addresses in parameters as domain names rather than as
numeric IP addresses. If a given hostname resolves to
more than one IP address (for example, if that host has
two ethernet interfaces), both addresses are supplied to
the client.
In Figure 1, you can see that both the shared-network
statement and the subnet statements can have parameters.
Let us say that the shared network ISC-BIGGIE supports an
entire department - perhaps the accounting department.
If accounting has its own domain, then a shared-network-
specific parameter might be:
option domain-name "accounting.isc.org";
All subnet declarations appearing in the shared-network
declaration would then have the domain-name option set to
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,
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 behaviour 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 models. One
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; }
}
REFERENCE: DECLARATIONS
The shared-network statement
shared-network name {
[ parameters ]
[ 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
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
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
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
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
behaviour of dhcpd to various sorts of requests.
The unknown-clients keyword
allow unknown-clients;
deny unknown-clients;
Dynamic address assignment to unknown clients is allowed
by default.
The bootp keyword
allow bootp;
deny 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;
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.
REFERENCE: PARAMETERS
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 max-lease-time statement
max-lease-time time;
Time should be the maximum length in seconds that will be
assigned to a lease if the client requesting the lease
asks for a specific expiration time.
The hardware statement
hardware hardware-type hardware-address;
In order for a BOOTP client to be recognized, its network
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. Currently, only the
ethernet and token-ring types are recognized, although
support for a fddi hardware type (and others) would also
be desirable. The hardware-address should be a set of
DHCP clients.
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 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 booting. Name
should be the name that will be provided to the client.
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 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 boot
ing, that client will not match the host declaration con
taining that fixed-address statement. Each address should
be either an IP address or a domain name which resolves to
one or more IP addresses.
The dynamic-bootp-lease-cutoff statement
dynamic-bootp-lease-cutoff date;
The dynamic-bootp-lease-cutoff statement sets the ending
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
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 Greenwich Mean Time
(GMT), 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 num
ber 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 get-lease-hostnames statement
get-lease-hostnames flag;
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 use-host-decl-names statement
use-host-decl-names flag;
the name provided for the host declaration will be sup
plied 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;
option host-name "joe";
}
An option host-name statement within a host declaration
will override the use of the name in the host declaration.
The authoritative statement
authoritative;
not authoritative;
The DHCP server will normally assume that the configura
tion information about a given network segment is known to
be correct and is authoritative. So if a client requests
an IP address on a given network segment that the server
knows is not valid for that segment, the server will
respond with a DHCPNAK message, causing the client to for
get its IP address and try to get a new one.
If a DHCP server is being configured by somebody who is
not the network administrator and who therefore does not
wish to assert this level of authority, then the statement
"not authoritative" should be written in the appropriate
scope in the configuration file.
Usually, writing not 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.
Note that the most specific scope for which the concept of
authority makes any sense is the physical network segment
It is not meaningful to specify that the server is author
itative for some subnets within a shared network, but not
authoritative for others, nor is it meaningful to specify
that the server is authoritative for some host declara
tions and not others.
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 speci
fied 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.
If use-lease-addr-for-default-route is enabled and an
option routers statement are both in scope, the routers
option will be preferred. The rationale for this is that
in situations where you want to use this feature, you
probably want it enabled for a whole bunch of Windows 95
machines, and you want to override it for a few other
machines. Unfortunately, if the opposite happens to be
true for you site, you are probably better off not trying
to use this flag.
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 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
clients served by a particular scope.
The use of the server-identifier statement is not recom
mended - the only reason to use it is to force a value
other than the default value to be sent on occasions where
the default value would be incorrect. The default value
is the first IP address associated with the physical net
work 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 appro
priate 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.
REFERENCE: OPTION STATEMENTS
DHCP option statements are documented in the dhcp-
options(5) manual page.
SEE ALSO
dhcpd.conf(5), dhcpd.leases(5), RFC2132, RFC2131.
AUTHOR
dhcpd(8) was written by Ted Lemon <mellon@vix.com> under a
contract with Vixie Labs. Funding for this project was
provided by the Internet Software Corporation. Informa
tion about the Internet Software Consortium can be found
at http://www.isc.org/isc.
Man(1) output converted with
man2html