Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DHCPD.CONF(5)		    BSD	File Formats Manual		 DHCPD.CONF(5)

     dhcpd.conf	-- DHCP	server 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	(ex-
     cept 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

     Declarations are used to describe the topology of the network, to de-
     scribe 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 spec-
     ified before any declarations which depend	on those parameters may	be

     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 installa-
     tions 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	decla-
     rations 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 sub-
     net operates.  For	example, if there is a site-wide requirement that
     8-bit subnet masks	be used, but a department with a single	physical Eth-
     ernet 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

     Some sites	may have departments which have	clients	on more	than one sub-
     net, but it may be	desirable to offer those clients a uniform set of pa-
     rameters 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) contain-
     ing 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 net-

     A typical dhcpd.conf file will look something like	this:

     Example 1

	   global parameters...

	   shared-network ISC-BIGGIE {
	     shared-network-specific parameters	...
	     subnet netmask {
	       subnet-specific parameters ...
	     subnet netmask {
	       subnet-specific parameters ...

	   subnet netmask {
	     subnet-specific parameters	...

	   group {
	     group-specific parameters ...
	     host {
	       host-specific parameters	...
	     host {
	       host-specific parameters	...
	     host {
	       host-specific parameters	...

     Notice that at the	beginning of the file, there's a place for global pa-
     rameters.	These might be things like the organization's domain name, the
     addresses of the name servers (if they are	common to the entire organiza-
     tion), and	so on.	So, for	example:

     Example 2

	   option domain-name "";
	   option domain-name-servers,;

     As	you can	see in Example 2, it's legal to	specify	host addresses in pa-
     rameters as hostnames rather than as numeric IP addresses.

     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	net-
     work ISC-BIGGIE supports an entire	department - perhaps the accounting
     department.  If accounting	has its	own domain, then a shared-network-spe-
     cific parameter might be:

	   option domain-name "";

     All subnet	declarations appearing in the shared-network declaration would
     then have the domain-name option set to "" instead of
     just "".

     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;

     Note that the address here	is specified numerically.  This	is not re-
     quired - if you have a different hostname for each	interface on your
     router, it's perfectly legitimate to use the hostname for that interface
     instead of	the numeric address.  However, in many cases there may be only
     one hostname for all of a router's	IP addresses, and it would not be ap-
     propriate to use that name	here.

     In	Example	1 there	is also	a group	statement, which provides common pa-
     rameters for a set	of three hosts - zappo,	beppo and harpo.  As you can
     see, these	hosts are all in the domain, so it	might make
     sense for a group-specific	parameter to override the domain name supplied
     to	these hosts:

	   option domain-name "";

     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	corre-
     spond 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 file-

     In	Example	1, each	host had host-specific parameters.  These could	in-
     clude 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 ac-
     cording to	the scope in which the parameter appears.

     Imagine that you have a site with a lot of	NCD X-Terminals.  These	termi-
     nals 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; }

     The shared-network	statement informs the DHCP server that some IP subnets
     actually share the	same physical network:

	   shared-network name {

     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 pa-
     rameters provided at the subnet or	host level override them.  If any sub-
     net 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 hostname	(although it
     will never	be used	as such), or it	may be any arbitrary name, enclosed in

     The subnet	statement provides dhcpd(8) with enough	information to tell
     whether or	not an IP address is on	that subnet:

	   subnet subnet-number	netmask	netmask	{

     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 ad-
     dresses.  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 gives the lowest and highest IP addresses in a	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.  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.

     There must	be at least one	host statement for every BOOTP client that is
     to	be served:

	   host	hostname {

     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

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

     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	ad-
     dress 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 is used simply	to apply one or	more parameters	to a
     group of declarations:

	   group {

     It	can be used to group hosts, shared networks, subnets, or even other

     The allow and deny	statements can be used to control the behaviour	of
     dhcpd(8) to various sorts of requests.

     The unknown-clients flag tells dhcpd(8) whether or	not to dynamically as-
     sign addresses to unknown clients:

	   allow unknown-clients;
	   deny	unknown-clients;

     Dynamic address assignment	to unknown clients is allowed by default.

     The bootp flag tells dhcpd(8) whether or not to respond to	bootp queries:

	   allow bootp;
	   deny	bootp;

     Bootp queries are allowed by default.

     The booting flag tells dhcpd(8) whether or	not to respond to queries from
     a particular client:

	   allow booting;
	   deny	booting;

     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

     The default-lease-time statement specifies	the time in seconds that will
     be	assigned to a lease if the client requesting the lease does not	ask
     for a specific expiration time:

	   default-lease-time time;

     The max-lease-time	statement specifies the	maximum	time in	seconds	that
     will be assigned to a lease if the	client requesting the lease asks for a
     specific expiration time:

	   max-lease-time time;

     The hardware statement allows a BOOTP client to be	recognized in a	host

	   hardware hardware-type hardware-address;

     hardware-type must	be the name of a hardware interface type.  Currently,
     the ethernet, token-ring and fddi physical	interface types	are recog-
     nized, although support for DHCP-over-IPsec virtual interface type
     ipsec-tunnel is provided.	The hardware-address should be a set of	hexa-
     decimal octets (numbers from 0 through ff)	separated by colons.  The
     hardware statement	may also be used for DHCP clients.

     The filename statement can	be used	to specify the name of the initial
     boot file which is	to be loaded by	a client:

	   filename "filename";

     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 can be used to inform the client	of the name of
     the server	from which it is booting:

	   server-name "name";

     name should be the	name that will be provided to the client.

     The next-server statement specifies the host address of the server	from
     which the initial boot file (specified in the filename statement) is to
     be	loaded:

	   next-server server-name;

     server-name should	be a numeric IP	address	or a hostname.	If no
     next-server parameter applies to a	given client, the DHCP server's	IP ad-
     dress is used.

     The fixed-address statement assigns one or	more fixed IP addresses	to a

	   fixed-address address [, address ...];

     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	con-
     taining that fixed-address	statement.  Each address should	be either an
     IP	address	or a hostname which resolves to	one or more IP addresses.

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

     The dynamic-bootp-lease-cutoff statement sets the ending time for all
     leases assigned dynamically to BOOTP clients:

	   dynamic-bootp-lease-cutoff date;

     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 situa-
     tions 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 ma-
     chines 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 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 lo-
     cal time.

     The dynamic-bootp-lease-length statement sets the length of leases	dynam-
     ically assigned to	BOOTP clients:

	   dynamic-bootp-lease-length length;

     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 fre-
     quently enough will never lose its	lease.	Needless to say, this parame-
     ter should	be adjusted with extreme caution.

     The get-lease-hostnames statement tells dhcpd(8) whether or not to	look
     up	the hostname corresponding to the IP address of	each address in	the
     lease pool	and use	that address for the DHCP hostname option:

	   get-lease-hostnames flag;

     If	flag is	true, then this	lookup is done for all addresses in the	cur-
     rent scope.  By default, or if flag is false, no lookups are done.

     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:

	   use-host-decl-names flag;

     So, for example:

	   group {
	     use-host-decl-names on;

	     host joe {
	       hardware	ethernet 08:00:2b:4c:29:32;

     is	equivalent to:

	   host	joe {
	     hardware ethernet 08:00:2b:4c:29:32;
	     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:

	   not authoritative;

     The DHCP server will normally assume that the configuration information
     about a given network segment is known to be correct and is authorita-
     tive.  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 re-
     spond 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 au-
     thority, 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 authori-
     tative for	others,	nor is it meaningful to	specify	that the server	is au-
     thoritative 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 fea-
     ture, you probably	want it	enabled	for a whole bunch of Windows 95	ma-
     chines, and you want to override it for a few other machines.  Unfortu-
     nately, if	the opposite happens to	be true	for your site, you are proba-
     bly 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 "(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 can be used to define the value that is
     sent in the DHCP Server Identifier	option for a given scope:

	   server-identifier hostname;

     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	de-
     fault 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 pur-
     pose of having a consistent IP address for	the DHCP server, and it	is de-
     sired 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.

     The echo-client-id	statement controls RFC 6842 compliant behavior and has
     a default value of	true:

	   echo-client-id flag;

     Some devices, especially old printers, require echo-client-id to be

     When echo-client-id is true dhcpd(8) copies option	dhcp-client-identifier
     (code 61) from DHCP DISCOVER or REQUEST messages into the DHCP ACK	or NAK
     reply sent	to the client.

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

     dhcp-options(5), dhcpd.leases(5), dhcpd(8)

     R.	Droms, Dynamic Host Configuration Protocol, RFC	2131, March 1997.

     S.	Alexander and R. Droms,	DHCP Options and BOOTP Vendor Extensions, RFC
     2132, March 1997.

     M.	Patrick, DHCP Relay Agent Information Option, RFC 3046,	January	2001.

     B.	Patel, B. Aboba, S. Kelly, and V. Gupta, Dynamic Host Configuration
     Protocol (DHCPv4) Configuration of	IPsec Tunnel Mode, RFC 3456, January

     dhcpd(8) was written by Ted Lemon <>	under a	contract with
     Vixie Labs.

     The current implementation	was reworked by	Henning	Brauer

BSD				 July 3, 2018				   BSD


Want to link to this manual page? Use this URL:

home | help