dhcpd.conf - dhcpd configuration file
The dhcpd.conf file contains configuration information for
dhcpd(8), 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(8). The file may
contain extra
tabs and newlines for formatting purposes. Keywords in the
file are
case-insensitive. Comments may be placed anywhere within
the file (except
within quotes). Comments begin with the `#' character
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 say how to do something (e.g., how long
a lease to
offer), whether to do something (e.g., should dhcpd(8) provide addresses
to unknown clients), or what parameters to provide to the
client (e.g.,
use gateway 220.177.244.7).
Declarations are used to describe the topology of the network, 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 declaration.
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 parameters 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 subnet
to which the
dhcp server is connected, there must be one subnet declaration, which
tells dhcpd(8) 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 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 ethernet 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
declaration.
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 departments on the same subnet. For clients which
will be declared
explicitly with host declarations, these declarations 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 declaration (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(8) 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 network 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(8)
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.
A typical dhcpd.conf file will look something like this:
Example 1
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...
range 204.254.239.42 204.254.239.62;
}
}
subnet 204.254.239.64 netmask 255.255.255.224 {
subnet-specific parameters...
range 204.254.239.74 204.254.239.94;
}
group {
group-specific parameters...
host zappo.test.isc.org {
host-specific parameters...
}
host beppo.test.isc.org {
host-specific parameters...
}
host harpo.test.isc.org {
host-specific parameters...
}
}
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:
Example 2
option domain-name "isc.org";
option domain-name-servers ns1.isc.org, ns2.isc.org;
As you can see in Example 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 Example 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 ``accounting.isc.org'' instead of
just ``isc.org''.
The most obvious reason for having subnet-specific parameters as shown in
Example 1 is that each subnet, of necessity, 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 legitimate 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 Example 1 there is also a group statement, which provides
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 supplied
to these hosts:
option domain-name "test.isc.org";
Also, given the domain they're in, these are probably test
machines. If
we wanted to test the DHCP leasing mechanism, we might set
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(8) will give out), or specify client parameters that
are not optional in the DHCP protocol (for example, servername and filename).
In Example 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-Terminals.
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";
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 ncd5 { hardware ethernet 0:c0:c3:11:90:23; }
host ncd6 { hardware ethernet 0:c0:c3:91:a7:8; }
host ncd7 { 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 physical 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(8) with enough
information
to tell whether or not an IP address is on that subnet. It
may also be
used to provide subnet-specific 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 declaration, 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 dynamically, 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 single 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
specified.
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 otherwise, then a host
statement
must be specified without a fixed-address clause. hostname
should be a
name identifying 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 network
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(8) to various sorts of requests.
The unknown-clients keyword
allow unknown-clients;
deny unknown-clients;
The unknown-clients flag is used to tell dhcpd(8) whether or
not to dynamically
assign addresses to 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(8) 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(8) 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 an 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 an fddi hardware type (and others) would
also be desirable.
The hardware-address should be a set of hexadecimal octets
(numbers from 0 through ff) separated by colons. The
hardware statement
may also be used for 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 booting, that client will
not match
the host declaration containing 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
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(8) assigns 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 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 get-lease-hostnames statement
get-lease-hostnames flag;
The get-lease-hostnames statement is used to tell dhcpd(8)
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;
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;
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 configuration
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 forget
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 - either a
shared-network
statement or a subnet statement that is not contained within
a sharednetwork
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 authoritative
for some host declarations 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 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.
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 your 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 RFC 1048-style responses, but do
not follow RFC
1048 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 ``(nonrfc1048)'' printed
with each BOOTREQUEST that is logged.
If you want to send RFC 1048 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 for a given scope.
The value
specified must be an IP address for the DHCP server, and
must be reachable
by all clients served by a particular scope.
The use of the server-identifier statement is not recommended - 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 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.
REFERENCE: OPTION STATEMENTS
DHCP option statements are documented in the dhcp-options(5)
manual page.
dhcp-options(5), dhcpd.leases(5), dhcpd(8)
RFC 2132, RFC 2131.
dhcpd(8) was written by Ted Lemon <mellon@vix.com> under a
contract with
Vixie Labs.
The current implementation was reworked by
Henning Brauer <henning@openbsd.org>.
OpenBSD 3.6 January 1, 1995
[ Back ] |
