DHCPD(8) FreeBSD System Manager's Manual DHCPD(8)
NAME
dhcpd - Dynamic Host Configuration Protocol (DHCP) daemon
SYNOPSIS
dhcpd [-dfnv] [-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]]
DESCRIPTION
dhcpd implements the Dynamic Host Configuration Protocol (DHCP) and the
Internet Bootstrap Protocol (BOOTP). DHCP allows hosts on a TCP/IP
network to request and be assigned IP addresses, and also to discover
information about the network to which they are attached. BOOTP provides
similar functionality, with certain restrictions.
The DHCP protocol allows a host which is unknown to the network
administrator 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
administrator 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
available addresses on each subnet in memory. When a client requests an
address 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 address
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.
Whenever changes are made to the dhcpd.conf file, dhcpd must be
restarted.
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.
When dhcpd starts up, it identifies all network interfaces in all routing
domains, eliminating non-broadcast interfaces if possible, and listens
for DHCP broadcasts on each interface. The names of the network
interfaces on which dhcpd should listen for broadcasts may also be
specified on the command line on systems where dhcpd is unable to
identify non-broadcast interfaces.
dhcpd normally runs in routing domain 0. In order to run in another
rdomain(4), dhcpd needs to be started with a list of interfaces which
share the same routing domain, which allows dhcpd to set its own routing
domain accordingly.
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 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)
table named leased_ip_table. Addresses are removed from the
table when the lease expires. Combined with the table of
abandoned addresses, 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 interface'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
importance 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.
-u[bind_address]
Use a UDP socket instead of BPF for receiving and sending
packets. 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
(255.255.255.255) is used as the default.
-v Produce more verbose output.
-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
numeric TTL value for multicast messages to the group
224.0.1.240. If the multicast TTL is not specified, a default
value of 1 is used. This option can be specified multiple times.
See also SYNCHRONISATION below.
-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
below.
BOOTP
dhcpd also provides BOOTP support. 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 dynamically 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.
CONFIGURATION
The syntax of the dhcpd.conf(5) file is discussed separately. This
section should be used as an overview of the configuration process, and
the dhcpd.conf(5) documentation should be consulted for detailed
reference information.
Subnets
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
providing DHCP support might look like this:
subnet 239.252.197.0 netmask 255.255.255.0 {
range 239.252.197.10 239.252.197.250;
}
Multiple address ranges may be specified like this:
subnet 239.252.197.0 netmask 255.255.255.0 {
range 239.252.197.10 239.252.197.107;
range 239.252.197.113 239.252.197.250;
}
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
infrequently, 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
appliance 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 239.252.197.0 netmask 255.255.255.0 {
range 239.252.197.10 239.252.197.107;
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
default 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
network 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;
fixed-address 239.252.197.9;
filename "haagen.boot";
}
Options
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 239.252.197.0 netmask 255.255.255.0 {
range 239.252.197.10 239.252.197.250;
default-lease-time 600;
max-lease-time 7200;
option subnet-mask 255.255.255.0;
option broadcast-address 239.252.197.255;
option routers 239.252.197.1;
option domain-name-servers 239.252.197.2, 239.252.197.3;
option domain-name "isc.org";
}
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;
fixed-address 239.252.197.9;
filename "haagen.boot";
option domain-name-servers 192.5.5.1;
option domain-name "vix.com";
}
A more complete description of the dhcpd.conf file syntax is provided in
dhcpd.conf(5).
SYNCHRONISATION
dhcpd supports realtime synchronisation of the lease allocations to a
number of dhcpd daemons running on multiple machines, using the -Y and -y
options.
The following example will accept incoming multicast and unicast
synchronisation messages, and send outgoing multicast messages through
the network 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 foo.somewhere.org and bar.somewhere.org, and accept
incoming unicast messages sent to example.somewhere.org only.
# /usr/sbin/dhcpd -y example.somewhere.org -Y em0:2 \
-Y foo.somewhere.org -Y bar.somewhere.org
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
synchronisation messages.
All hosts using synchronisation must use the same configuration in the
/etc/dhcpd.conf file.
FILES
/etc/dhcpd.conf DHCPD configuration file.
/var/db/dhcpd.leases DHCPD lease file.
SEE ALSO
pf(4), rdomain(4), dhcpd.conf(5), dhcpd.leases(5), dhcpleased(8),
dhcrelay(8), pxeboot(8)
STANDARDS
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
2002.
AUTHORS
dhcpd is based on software from the Internet Software Consortium, written
by Ted Lemon <
[email protected]> under a contract with Vixie Labs. The
current implementation was reworked for OpenBSD by Henning Brauer
<
[email protected]>.
BUGS
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
limited, 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.
FreeBSD 14.1-RELEASE-p8 June 27, 2024 FreeBSD 14.1-RELEASE-p8