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

FreeBSD Manual Pages


home | help
DHCPD(8)		  BSD System Manager's Manual		      DHCPD(8)

     dhcpd -- Dynamic Host Configuration Protocol (DHCP) server

     dhcpd [-dfn] [-A abandoned_ip_table] [-C changed_ip_table]
	   [-c config-file] [-L	leased_ip_table] [-l lease-file]
	   [-u[bind_address]] [-Y synctarget] [-y synclisten] [if0 [...	ifN]]

     dhcpd implements the Dynamic Host Configuration Protocol (DHCP) and the
     Internet Bootstrap	Protocol (BOOTP).  DHCP	allows hosts on	a TCP/IP net-
     work to request and be assigned IP	addresses, and also to discover	infor-
     mation about the network to which they are	attached.  BOOTP provides sim-
     ilar functionality, with certain restrictions.

     The DHCP protocol allows a	host which is unknown to the network adminis-
     trator to be automatically	assigned a new IP address out of a pool	of IP
     addresses for its network.	 In order for this to work, the	network	admin-
     istrator allocates	address	pools in each subnet and enters	them into the
     dhcpd.conf(5) file.

     On	startup, dhcpd reads the dhcpd.conf file and stores a list of avail-
     able addresses on each subnet in memory.  When a client requests an ad-
     dress using the DHCP protocol, dhcpd allocates an address for it.	Each
     client is assigned	a lease, which expires after an	amount of time chosen
     by	the administrator (by default, one day).  When a leased	IP address is
     assigned to a new hardware	address, dhcpd may delete the leased IP	from
     certain pf(4) tables.  Before leases expire, the clients to which leases
     are assigned are expected to renew	them in	order to continue to use the
     addresses.	 Once a	lease has expired, the client to which that lease was
     assigned is no longer permitted to	use the	leased IP address.

     In	order to keep track of leases across system reboots and	server
     restarts, dhcpd keeps a list of leases it has assigned in the
     dhcpd.leases(5) file.  Before dhcpd grants	a lease	to a host, it records
     the lease in this file and	makes sure that	the contents of	the file are
     flushed to	disk.  This ensures that even in the event of a	system crash,
     dhcpd will	not forget about a lease that it has assigned.	On startup,
     after reading the dhcpd.conf file,	dhcpd reads the	dhcpd.leases file to
     refresh its memory	about what leases have been assigned.

     BOOTP support is also provided by this server.  Unlike DHCP, the BOOTP
     protocol does not provide a protocol for recovering dynamically-assigned
     addresses once they are no	longer needed.	It is still possible to	dynam-
     ically assign addresses to	BOOTP clients, but some	administrative process
     for reclaiming addresses is required.  By default,	leases are granted to
     BOOTP clients in perpetuity, although the network administrator may set
     an	earlier	cutoff date or a shorter lease length for BOOTP	leases if that
     makes sense.

     BOOTP clients may also be served in the old standard way, which is	simply
     to	provide	a declaration in the dhcpd.conf	file for each BOOTP client,
     permanently assigning an address to each client.

     Whenever changes are made to the dhcpd.conf file, dhcpd must be
     restarted.	 Because the DHCP server database is not as lightweight	as a
     BOOTP database, dhcpd does	not automatically restart itself when it sees
     a change to the dhcpd.conf	file.

     DHCP traffic always bypasses IPsec.  Otherwise there could	be situations
     when a server has an IPsec	SA for the client and sends replies over that,
     which a newly booted client would not be able to grasp.

     The names of the network interfaces on which dhcpd	should listen for
     broadcasts	may be specified on the	command	line.  This should be done on
     systems where dhcpd is unable to identify non-broadcast interfaces, but
     should not	be required on other systems.  If no interface names are spec-
     ified on the command line,	and the	-u option is not given,	dhcpd will
     identify all network interfaces which are up, eliminating non-broadcast
     interfaces	if possible, and listen	for DHCP broadcasts on each interface.

     The options are as	follows:

     -A	abandoned_ip_table
	     When an address is	abandoned for some reason, add it to the pf(4)
	     table named abandoned_ip_table.  This can be used to defend
	     against machines "camping"	on an address without obtaining	a
	     lease.  When an address is	properly leased, dhcpd will remove the
	     address from this table.

     -C	changed_ip_table
	     When an address is	leased to a different hardware address,	delete
	     it	from the pf(4) table named changed_ip_table.  This feature
	     complements the overload table in a stateful pf(4)	rule.  If a
	     host appears to be	misbehaving, it	can be quarantined by using
	     the overload feature.  When the address is	leased to a different
	     machine, dhcpd can	remove the address from	the overload table,
	     thus allowing a well-behaved machine to reuse the address.

     -c	config-file
	     Use an alternate configuration file, config-file.	Because	of the
	     importance	of using the same lease	database at all	times when
	     running dhcpd in production, this option should be	used only for
	     testing database files in a non-production	environment.

     -d	     Do	not daemonize.	If this	option is specified, dhcpd will	run in
	     the foreground and	log to stderr.

     -f	     An	alias for -d.

     -L	leased_ip_table
	     When an address is	leased dhcpd will insert it into the pf(4) ta-
	     ble named leased_ip_table.	 Addresses are removed from the	table
	     when the lease expires.  Combined with the	table of abandoned ad-
	     dresses, this can help enforce a requirement to use DHCP on a
	     network, or can place DHCP	users in a different class of service.
	     Users are cautioned against placing much trust in Ethernet	or IP
	     addresses;	ifconfig(8) can	be used	to trivially change the	inter-
	     face's address, and on a busy DHCP	network, IP addresses will
	     likely be quickly recycled.

     -l	lease-file
	     Use an alternate lease file, lease-file.  Because of the impor-
	     tance of using the	same lease database at all times when running
	     dhcpd in production, this option should be	used only for testing
	     lease files in a non-production environment.

     -n	     Only test configuration, do not run dhcpd.

	     Use a UDP socket instead of BPF for receiving and sending pack-
	     ets.  Only	DHCPINFORM messages can	be handled on this socket;
	     other messages are	discarded.  With this option, dhcpd can	answer
	     DHCPINFORM	from clients on	non Ethernet interfaces	such as	tun(4)
	     or	pppx(4).  If bind_address is specified,	dhcpd will bind	to
	     that address; otherwise the limited broadcast address
	     ( is used as the default.

     -Y	synctarget
	     Add target	synctarget to receive synchronisation messages.
	     synctarget	can be either an IPv4 address for unicast messages or
	     a network interface name followed optionally by a colon and a nu-
	     meric TTL value for multicast messages to the group
	     If	the multicast TTL is not specified, a default value of 1 is
	     used.  This option	can be specified multiple times.  See also

     -y	synclisten
	     Listen on synclisten for incoming synchronisation messages.  The
	     format for	synclisten is the same as for synctarget, above.  This
	     option can	be specified only once.	 See also SYNCHRONISATION be-

     The syntax	of the dhcpd.conf(5) file is discussed separately.  This sec-
     tion should be used as an overview	of the configuration process, and the
     dhcpd.conf(5) documentation should	be consulted for detailed reference

	  dhcpd	needs to know the subnet numbers and netmasks of all subnets
	  for which it will be providing service.  In addition,	in order to
	  dynamically allocate addresses, it must be assigned one or more
	  ranges of addresses on each subnet which it can in turn assign to
	  client hosts as they boot.  Thus, a very simple configuration	pro-
	  viding DHCP support might look like this:

		subnet netmask {

	  Multiple address ranges may be specified like	this:

		subnet netmask {

	  If a subnet will only	be provided with BOOTP service and no dynamic
	  address assignment, the range	clause can be left out entirely, but
	  the subnet statement must appear.

     Lease Lengths
	  DHCP leases can be assigned almost any length	from zero seconds to
	  infinity.  What lease	length makes sense for any given subnet, or
	  for any given	installation, will vary	depending on the kinds of
	  hosts	being served.

	  For example, in an office environment	where systems are added	from
	  time to time and removed from	time to	time, but move relatively in-
	  frequently, it might make sense to allow lease times of a month or
	  more.	 In a final test environment on	a manufacturing	floor, it may
	  make more sense to assign a maximum lease length of 30 minutes -
	  enough time to go through a simple test procedure on a network ap-
	  pliance before packaging it up for delivery.

	  It is	possible to specify two	lease lengths: the default length that
	  will be assigned if a	client doesn't ask for any particular lease
	  length, and a	maximum	lease length.  These are specified as clauses
	  to the subnet	command:

		subnet netmask {
		  default-lease-time 600;
		  max-lease-time 7200;

	  This particular subnet declaration specifies a default lease time of
	  600 seconds (ten minutes), and a maximum lease time of 7200 seconds
	  (two hours).	Other common values would be 86400 (one	day), 604800
	  (one week) and 2592000 (30 days).

	  Each subnet need not have the	same lease - in	the case of an office
	  environment and a manufacturing environment served by	the same DHCP
	  server, it might make	sense to have widely disparate values for de-
	  fault	and maximum lease times	on each	subnet.

     BOOTP Support
	  Each BOOTP client must be explicitly declared	in the dhcpd.conf(5)
	  file.	 A very	basic client declaration will specify the client net-
	  work interface's hardware address and	the IP address to assign to
	  that client.	If the client needs to be able to load a boot file
	  from the server, that	file's name must be specified.	A simple BOOTP
	  client declaration might look	like this:

		host haagen {
		  hardware ethernet 08:00:2b:4c:59:23;
		  filename "haagen.boot";

	  DHCP (and also BOOTP with Vendor Extensions) provides	a mechanism
	  whereby the server can provide the client with information about how
	  to configure its network interface (e.g., subnet mask), and also how
	  the client can access	various	network	services (e.g.,	DNS, IP
	  routers, and so on).

	  These	options	can be specified on a per-subnet basis and, for	BOOTP
	  clients, also	on a per-client	basis.	In the event that a BOOTP
	  client declaration specifies options that are	also specified in its
	  subnet declaration, the options specified in the client declaration
	  take precedence.  A reasonably complete DHCP configuration might
	  look something like this:

		subnet netmask {
		  default-lease-time 600;
		  max-lease-time 7200;
		  option subnet-mask;
		  option broadcast-address;
		  option routers;
		  option domain-name-servers,;
		  option domain-name "";

	  A BOOTP host on that subnet that needs to be in a different domain
	  and use a different name server might	be declared as follows:

		host haagen {
		  hardware ethernet 08:00:2b:4c:59:23;
		  filename "haagen.boot";
		  option domain-name-servers;
		  option domain-name "";

     A more complete description of the	dhcpd.conf file	syntax is provided in

     dhcpd supports realtime synchronisation of	the lease allocations to a
     number of dhcpd daemons running on	multiple machines, using the -Y	and -y

     The following example will	accept incoming	multicast and unicast synchro-
     nisation messages,	and send outgoing multicast messages through the net-
     work interface em0:

	   # /usr/sbin/dhcpd -y	em0 -Y em0

     The second	example	will increase the multicast TTL	to a value of 2, add
     the unicast targets and, and accept
     incoming unicast messages sent to only.

	   # /usr/sbin/dhcpd -y -Y em0:2 \
		   -Y	-Y

     If	the file /var/db/dhcpd.key exists, dhcpd will calculate	the message-
     digest fingerprint	(checksum) for the file	and use	it as a	shared key to
     authenticate the synchronisation messages.	 The file itself can contain
     any data.	For example, to	create a secure	random key:

	   # dd	if=/dev/random of=/var/db/dhcpd.key bs=2048 count=1

     The file needs to be copied to all	hosts sending or receiving synchroni-
     sation messages.

     All hosts using synchronisation must use the same configuration in	the
     /etc/dhcpd.conf file.

     /etc/dhcpd.conf	      DHCPD configuration file.
     /var/db/dhcpd.leases     DHCPD lease file.

     pf(4), dhcpd.conf(5), dhcpd.leases(5), dhclient(8), dhcrelay(8),

     R.	Droms, Interoperation Between DHCP and BOOTP, RFC 1534,	October	1993.

     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.

     T.	Lemon and S. Cheshire, Encoding	Long Options in	the Dynamic Host
     Configuration Protocol (DHCPv4), RFC 3396,	November 2002.

     T.	Lemon, S. Cheshire, and	B. Volz, The Classless Static Route Option for
     Dynamic Host Configuration	Protocol (DHCP)	version	4, RFC 3442, December

     dhcpd is based on software	from the Internet Software Consortium, written
     by	Ted Lemon <> under a contract with Vixie Labs.  The cur-
     rent implementation was reworked for OpenBSD by Henning Brauer

     We	realize	that it	would be nice if one could send	a SIGHUP to the	server
     and have it reload	the database.  This is not technically impossible, but
     it	would require a	great deal of work, our	resources are extremely	lim-
     ited, and they can	be better spent	elsewhere.  So please don't complain
     about this	on the mailing list unless you're prepared to fund a project
     to	implement this feature,	or prepared to do it yourself.

BSD				August 29, 2017				   BSD


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

home | help