FreeBSD DHCP Client Lease Lifecycle: Boot, Renewal, and Recovery

FreeBSD’s DHCP client is part of a larger configuration path. dhclient(8) exchanges DHCP messages and tracks leases, but rc(8) decides when it runs, dhclient-script(8) applies the offered settings to the interface and resolver, and the network stack installs addresses and routes. A host can therefore have a running client and still lack a usable default route, or hold a lease while DNS points somewhere unexpected. Diagnose the lifecycle boundary that failed instead of repeatedly restarting the interface.

This guide covers the base-system DHCP client on a FreeBSD host. It does not configure a DHCP server, guarantee a fixed address, or replace an IPv6 router-advertisement design. Treat the DHCP server as the authority for leased values, preserve a console rollback path, and verify the resulting address, route, and resolver state from the host that actually consumes them.

Map the boot-time owner and execution mode

The persistent client request normally lives in /etc/rc.conf under an interface-specific ifconfig_<interface> value:

sysrc ifconfig_em0
sysrc background_dhclient
ifconfig -a
pgrep -laf dhclient

Replace em0 with the interface name present on the target host. A typical configuration is:

sysrc ifconfig_em0=DHCP

The Handbook documents DHCP for ordinary operation and SYNCDHCP when startup must wait until the lease process completes. Background/asynchronous acquisition can let later rc scripts run before an address exists. That shortens boot in a responsive network, but a daemon that binds only during startup may fail before the lease arrives. Synchronous acquisition delays startup and can make boot wait for a missing or slow server. Choose based on the actual dependency graph, not a blanket rule that synchronous mode is always safer.

dhclient can be launched manually, but doing so while rc already owns a client can create two processes competing to configure the same interface. Start by finding the current client process and reading the effective rc configuration to identify how the interface is configured. Do not kill a client or run a second one until you know which service owns it and how that service will restart it.

The configured interface must have a working broadcast path. FreeBSD’s Handbook notes that the bpf(4) device is needed by both the DHCP client and server; GENERIC includes it, while a custom kernel must retain it if DHCP is required. A missing BPF device or a filter that blocks DHCP traffic can look like a silent server timeout rather than an obvious client misconfiguration.

Follow the lease from request to installed state

DHCP uses a time-limited lease. The client requests network parameters; a server can return an address, subnet information, default router, DNS resolver addresses, and other options. The client records leases in a per-interface file such as /var/db/dhclient.leases.em0. That database is written as a sequence of declarations, and a later declaration for a lease supersedes an earlier one. It is useful evidence of what the client learned, but it is not the live kernel state and should not be edited to force an address.

After an offer, dhclient-script(8) performs interface configuration steps. It can set the initial interface state before requesting an address, test a proposed address, and apply the final configuration once a lease is acquired. It can also be invoked when no valid lease is found. This means each incident should compare three things separately: the exchange visible to the client, the saved lease record, and the actual installed interface/route/resolver values.

The default configuration file is /etc/dhclient.conf. Most hosts can use the installed defaults; custom statements should solve a specific client requirement such as a requested option or protocol timer. Before adding a setting, inspect the exact release’s dhclient.conf(5) and confirm the server sends the intended option. A client-side request cannot create a reservation or modify the server’s allocation policy.

The script is the FreeBSD-specific integration boundary and is not intended to be rewritten casually. When local customization is necessary, the manual documents hooks rather than asking administrators to replace /sbin/dhclient-script. A custom hook can introduce ordering, idempotency, and privilege problems. Record what event invokes it, make repeated calls safe, log only the minimum diagnostic data, and preserve the stock script’s interface/resolver behavior unless there is a tested reason to change it.

Inspect live state without changing it

Capture a read-only snapshot before restarting anything:

freebsd-version -kru
ifconfig em0
netstat -rn -f inet
route -n get default
cat /var/db/dhclient.leases.em0
cat /etc/resolv.conf
grep -i dhclient /var/log/messages | tail -80

Check whether the interface is up, has the expected address and prefix, and has a carrier. Then verify the route selected for a real destination and inspect the resolver file used by the host. A lease with the right address does not prove the default route was accepted; an address and route do not prove the DHCP-provided DNS information reached /etc/resolv.conf. If another interface, VPN, local resolver, or configuration manager also owns routes or DNS, determine the intended authority before changing any of them.

For packet evidence, use a short capture on the correct broadcast interface during an approved diagnostic window:

tcpdump -ni em0 -vvv 'udp port 67 or udp port 68'

The filter narrows the capture to DHCP’s UDP ports. Protect packet captures: DHCP messages can contain hostnames, client identifiers, and network topology. Look for whether a client request leaves, whether a server reply reaches the interface, and whether retries or a NAK follow. No observed reply can indicate VLAN, relay, firewall, server, or link problems; it does not by itself prove the client binary is defective.

Diagnose common lifecycle failures

The client never starts. Verify the exact interface name, the ifconfig_<interface> rc value, the boot log, and the service owner. Check that a custom kernel provides bpf(4) where required. Do not assume the interface name survived a hardware or virtual-machine change.

The request leaves but no offer returns. Confirm the client is on the expected VLAN and broadcast domain, DHCP relay is configured for a routed network, UDP 67/68 traffic is permitted at the relevant boundaries, and the server has free addresses. Compare packet captures at the client and relay/server when authorized. Changing dhclient.conf cannot repair a blocked relay or exhausted pool.

An address is present but applications fail. Inspect the prefix, selected route, resolver contents, and application bind address. DHCP options may be valid individually but conflict with static routes or another network manager. An old /etc/resolv.conf can survive if a script path failed or a different service owns the file. Do not make resolver files immutable as a workaround; that can block legitimate lease updates.

Boot races with a service. Identify whether that service requires an address, a default route, DNS, or full reachability. Use synchronous acquisition only when waiting at boot is an intended availability tradeoff. If a remote server is down, synchronous mode may delay the whole boot; if asynchronous mode is kept, make consumers retry or start after the needed milestone without treating ordering as proof of connectivity.

A previously working host loses the lease. Preserve the old lease file and logs first. Check link changes, DHCP server identity, NAKs, lease expiration, clock accuracy, and whether a competing static or DHCP client configured the same interface. Do not delete lease history as a first action. The daemon can use stored lease information during startup if the server is unavailable, but an old lease is not a promise that the address is still valid on today’s network.

Apply changes with a rollback path

Plan interface changes through a console or out-of-band management session if SSH depends on that interface. Save current rc settings and state, change one variable, and use the rc system rather than starting a second independent client. A targeted service netif restart em0 may interrupt active connections; it is a change operation, not a harmless test. Schedule it, ensure the lease server is reachable, and write down the restoration command before applying it.

If a manual foreground run is needed for diagnosis, first stop the existing owner using the supported service workflow and use the exact release’s dhclient(8) flags. The -d mode keeps the client in the foreground for output; it is not a way to safely run a second client in parallel. Return control to rc-managed service after the test and verify only one intended process remains.

Do not force a fresh lease by deleting files or repeatedly restarting services until the server-side state is understood. A release/renew action can change an address, reset connections, and invalidate routes or firewall assumptions. Coordinate with the DHCP administrator when the incident involves reservations, stale bindings, pool exhaustion, or a client-identifier change.

Prove the result and keep it observable

Acceptance requires more than a successful DHCPACK line. Confirm the expected address and prefix on the right interface, the default route and required static routes, resolver contents, host reachability, and the application behavior that motivated the change. Reboot or renew only in a maintenance window, then make sure the intended service starts in the correct order and that a later renewal does not undo local policy.

Monitor lease age and renew/rebind failures alongside link state, route presence, resolver health, and application probes. Alert when the last successful lease is too old for the environment, the interface changes address unexpectedly, or DHCP repeatedly succeeds while a required route or resolver is absent. Retain bounded logs and sanitized packet evidence long enough to compare a good renewal with a failed one.

The operational distinction is simple but important: DHCP provides a time-bounded set of network parameters; FreeBSD’s scripts and rc system translate those parameters into host state. Reliable recovery means verifying both the lease authority and every local consumer of the result, while keeping one owner for the interface and a safe way back to the previous configuration.

Related:

Sources: