dhcpd.conf(4CC)

NAME | DESCRIPTION | EXAMPLES | DECLARATIONS | ALLOW and DENY | PARAMETERS | OPTION STATEMENTS | ATTRIBUTES | SEE ALSO | AUTHOR

NAME

dhcpd.conf- dhcpd configuration file

DESCRIPTION

The dhcpd.conf file contains configuration information for dhcpd, the Internet Software Consortium DHCP Server.

The dhcpd.conf file is a free-form ASCII text file. It is parsed 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-insensitive. Comments are 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 either say how to do something (for example, how long a lease to offer), whether to do something (for example, should dhcpd provide addresses to unknown clients), or what parameters to provide to the client (for example, 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 specifying any declarations depending on those parameters.

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 client must have a host declaration. If parameters are to be applied to a group of declarations not related strictly on a per-subnet basis, the group declaration can be used.

For every subnet to be served, and for every subnet to which the DHCP server is connected, there must be one subnet declaration telling 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 a department with a single physical ethernet network expands to the point where it has more than 254 nodes, it is 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 can be enclosed in a shared-network declaration.

Some sites may have departments that have clients on more than one subnet, but it is desirable to offer those clients a uniform set of parameters different from what is offered to clients from other departments on the same subnet. For clients that are declared explicitly with host declarations, these declarations can be closed in a group declaration along with the parameters 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:

1. Consulting that client's host declaration (if any).

2. Consulting the group declaration (if any) that enclosed that host declaration.

3. Consulting the subnet declaration for the subnet on which the client is booting.

4. Consulting the shared-network declaration (if any) containing that subnet.

5. Consulting the top-level parameters that can be specified outside of any declaration.

When dhcpd tries to find a host declaration for a client, it first looks for a host declaration that has a fixed-address parameter matching 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 that has no fixed-address parameter. If no such entry is found, dhcpd behaves 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

dhcpd.conf

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...
 }
 }

Note that at the beginning of the file there is a place for global parameters such as the organization's domain name and the addresses of the name servers (if they are common to the entire organization. ) For example:

Global parameters

option domain-name "isc.org";
option domain-name-servers ns1.isc.org, ns2.isc.org;

As you can see in the second example, it is 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 the first example, you can see that both the shared-network statement and the subnet statements can have parameters. Suppose that the shared network ISC-BIGGIE supports an entire 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 the first example is that each subnet has its own router. For the first subnet, for example, there would 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 is perfectly legitimate to use the domain name for that interface instead of the numeric address. However, in many cases there is only one domain name for all of a router's IP addresses, and it would not be appropriate to use that name here.

In the first example 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. In this case it would be useful 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 are 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 behavior of the DHCP server (such as how long a lease dhcpd will assign), or specify client parameters that are not optional in the DHCP protocol (such as server-name and filename).

In the first example, each host had host-specific parameters. These could include 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 many 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 is 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 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; }
}

DECLARATIONS

shared-network

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 can be any arbitrary name, enclosed in quotes.

subnet

subnet subnet-number netmask netmask {
 [ parameters ]
 [ declarations ]
}

The subnet statement is used to provide dhcpd with enough information to verify 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 can be dynamically allocated to clients booting on that subnet. These addresses are specified using the range declaration.

The subnet-number should be an IP address or domain name that resolves to the subnet number of the subnet being described. The netmask should be an IP address or domain name that 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 subnet specified.

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.

range

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 can be specified if addresses in the specified range can be assigned dynamically to BOOTP clients as well as DHCP clients. When specifying a single address, high-address can be omitted.

host

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 can be specified in the fixed-address parameter, or more than one host statement can be specified.

If client-specific boot parameters must change based on the network to which the client is attached, multiple host statements should be used.

If a client is to be booted using a fixed address where this is possible, but should be allocated a dynamic address if this is not possible, 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, the default 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 will boot using the BOOTP protocol.

group

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.

ALLOW and DENY

The allow and deny statements can be used to control the behavior of dhcpd to various sorts of requests.

unknown-clients

allow unknown-clients;
deny unknown-clients;

The unknown-clients flag is used to tell dhcpd whether or not to assign addresses to unknown clients dynamically. Dynamic address assignment to unknown clients is allowed by default.

bootp

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.

booting

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 an address from the DHCP server.

PARAMETERS

default-lease-time

default-lease-time time;

Time is 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.

max-lease-time

max-lease-time time;

Time is the maximum length in seconds that will be assigned to a lease if the client requesting the lease asks for a specific expiration time.

hardware

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. The hardware-address is a set of hexadecimal octets (numbers from 0 through ff) separated by colons. The hardware statement may also be used for DHCP clients.

filename

filename "filename"

The filename statement can be used to specify the name of the initial boot file that is to be loaded by a client. The filename should be a filename recognizable to the file transfer protocol the client is using to load the file.

server-name

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.

next-server

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.

fixed-address

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 when the client boots, it will be assigned an address corresponding 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 that resolves to one or more IP addresses.

dynamic-bootp- lease-cutoff

dynamic-bootp-lease-cutoff date;

The dynamic-bootp-lease-cutoff statement sets the ending time for all leases assigned dynamically to BOOTP clients. BOOTP clients do not have any way of renewing leases, and do not know that their leases can expire, so by default dhcpd assigns infinite leases to all BOOTP clients. It is sometimes necessary to set a cut-off 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 is 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), .

dynamic-bootp- lease-length

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 is 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 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. This parameter should be adjusted with extreme caution.

get-lease-hostnames

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 performed.

use-host-decl-names

use-host-decl-names flag;

If the use-host-decl-names parameter is true in a given scope, for every host declaration within that scope, the name provided for the host declaration will be supplied to the client as its hostname. 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.

authoritative

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. 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 attempt 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, 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, it is more appropriate to declare authority on a per-network-segment basis.

The most specific scope of the concept of authority 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.

use-lease-addr-for- default-route

use-lease-addr-for-default-route flag;

If the use-lease-addr-for-default-route parameter is true in a given scope, 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 causes Windows 95 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 a routers option statement is in the scope, the routers option will be preferred. This is for sites with a majority of Windows 95 machines, and you override it for a minority of machines. If the opposite happens to be true for your site, it is better not to use this flag.

always-reply-rfc1048

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 the message "(non-rfc1048)" in the server log printed with each BOOTREQUEST that is logged.

If you want to send RFC1048 options to this type of 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.

server-identifier

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 is not 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.

OPTION STATEMENTS

DHCP option statements are documented in the dhcp-options(4CC) manual page.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

dhcpd.leases(4CC)

RFC2132, RFC2131

AUTHOR

dhcpd.conf was originally written by Ted Lemon <mellon@vix.com> under a contract with Vixie Labs. Funding for this project was provided by the Internet Software Consortium. Information about the Internet Software Consortium can be found at http://www.isc.org/isc.

ChorusOS 5.0  Last Revised December 2001

NAME | DESCRIPTION | EXAMPLES | DECLARATIONS | ALLOW and DENY | PARAMETERS | OPTION STATEMENTS | ATTRIBUTES | SEE ALSO | AUTHOR