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.

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:

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, server-name 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 download (the
filename parameter) and the address of the server from
which to download 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:

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 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 and
netmask should be specified as numeric IP addresses.
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.

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.

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-timetime;

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

hardwarehardware-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 hardware interface
type. Currently, the ethernet,
token-ring and fddi physical
interface types are recognized, although support for DHCP-over-IPSec virtual
interface type ipsec-tunnel is provided. 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-serverserver-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-addressaddress [, 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.

Clients with fixed addresses are not assigned DHCP leases, and may
therefore not be used with the -ACL table options of
dhcpd(8).

The dynamic-bootp-lease-cutoff
statement

dynamic-bootp-lease-cutoffdate;

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-lengthlength;

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-hostnamesflag;

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-namesflag;

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,

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 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
authoritative for some host declarations and not others.

The use-lease-addr-for-default-route
statement

use-lease-addr-for-default-routeflag;

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-rfc1048flag;

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
“(non-rfc1048)” 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-identifierhostname;

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.