DHCP troubleshooting — common failure modes, log analysis, packet capture · OPNsense

DHCP failures are the source of a disproportionate share of “the network is down” incidents. A host that cannot get an IP address is a host that cannot reach anything. The diagnostic discipline is fast: read the logs, capture the wire, identify which side is broken, fix it. The mistakes that waste hours are the opposite: guessing without evidence, changing the wrong configuration, or assuming the client is at fault when the server is.

This lesson covers the diagnostic tools, the common failure modes the operator runs into, and the discipline that finds the cause in minutes rather than hours.

The diagnostic order

A DHCP failure produces one of these symptoms:

Client has no IP at all. Link-local only (169.254.x.x or fe80::...).
Client has wrong IP. Lease came from the wrong scope.
Client has correct IP but cannot reach the Internet. Lease is fine; routing or DNS is broken.

The diagnostic order:

Verify the client sent a Discover. Capture on the client’s segment; look for the DHCP Discover.
Verify the server received the Discover. Look at the firewall logs or capture on the server interface.
Verify the server sent an Offer. Look for the Offer in the capture.
Verify the client received the Offer. Look for the Offer at the client.
Verify the Request and Acknowledge. Complete the four-step exchange.

The first packet that is missing tells the operator where the failure is. No Discover from the client → client-side issue. Discover received but no Offer → server-side issue. Offer sent but not received by client → relay or segmentation issue.

Reading the DHCP logs

OPNsense exposes DHCP logs under System → Log Files → DHCP. The log entries include:

DHCPDISCOVER from client (chaddr = MAC).
DHCPOFFER from server (yiaddr = offered IP, siaddr = server IP).
DHCPREQUEST from client (requested IP).
DHCPACK from server (lease confirmed).
DHCPNAK from server (lease denied, e.g. wrong subnet).
DHCPRELEASE from client (lease given up).

A healthy lease shows the four-step exchange. A failed lease shows the gap:

DHCPDISCOVER without DHCPOFFER → the server did not respond.
DHCPOFFER without DHCPREQUEST → the client did not see or did not accept the offer.
DHCPREQUEST followed by DHCPNAK → the server rejected the request (wrong subnet, no scope, conflict).

Read-only / SafeDHCP log— A DHCP log showing a problematic sequence. The reservation at 192.168.1.50 was honoured for one lease, then a subsequent Discover from the same MAC got a pool address (192.168.1.123). The DHCPNAK at the third entry shows the server rejecting the host\'s request for 192.168.1.50 — likely because the reservation was deleted or the MAC no longer matches. The host eventually accepts the pool address.

$ grep -E 'DHCPOFFER|DHCPACK|DHCPNAK' /var/log/dhcpd.log | tail -10

Jan 15 12:34:56 firewall dhcpd: DHCPOFFER on 192.168.1.50 to aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:34:57 firewall dhcpd: DHCPACK on 192.168.1.50 to aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:01 firewall dhcpd: DHCPDISCOVER from aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:01 firewall dhcpd: DHCPOFFER on 192.168.1.123 to aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:02 firewall dhcpd: DHCPACK on 192.168.1.123 to aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:03 firewall dhcpd: DHCPDISCOVER from aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:03 firewall dhcpd: DHCPNAK on 192.168.1.50 to aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:08 firewall dhcpd: DHCPREQUEST for 192.168.1.123 from aa:bb:cc:11:22:33 (printer-lobby) via igb1
Jan 15 12:35:08 firewall dhcpd: DHCPACK on 192.168.1.123 to aa:bb:cc:11:22:33 (printer-lobby) via igb1

Illustrative output

The DHCPNAK in the capture is the diagnostic gem: the server explicitly rejected the request. The reason is in the log context. Common reasons: the MAC is on a reservation that has been deleted; the requested IP is not in any scope; the host is on a subnet the server does not serve.

Capturing DHCP on the wire

The diagnostic capture:

tcpdump -nei <interface> port 67 or port 68 -vvv

The -vvv flag prints each option. The operator sees:

The DHCP message type (Discover, Offer, Request, Ack).
The client MAC (chaddr).
The offered IP (yiaddr).
The server IP (siaddr).
The relay IP (giaddr), if relayed.
The options (53 = message type, 54 = server ID, 61 = client ID, etc.).

For DHCPv6:

tcpdump -nei <interface> port 546 or port 547 -vvv

The diagnostic question: which of the four messages is missing?

Read-only / SafeDHCP capture— A healthy DHCP exchange: the client sent a Discover; the server responded with an Offer carrying the correct subnet mask (option 1), gateway (option 3), and DNS (option 6). The message types 1 (Discover) and 2 (Offer) are in the option 53 of each packet. A capture that stops after the Discover or that never shows an Offer is the diagnostic: the server is not responding.

$ tcpdump -nei igb1 -c 4 -vvv port 67 or port 68

12:34:56.789012 0.0.0.0.68 > 255.255.255.255.67: DHCP, length 308
12:34:56.789012   message-type 1 (discover)
12:34:56.789012   client-id option 1, length 7: ether aa:bb:cc:11:22:33
12:34:56.789012   DHCP option 55, length 8: 1 3 6 15 28 51 58 59
12:34:56.789020 192.168.1.1.67 > 192.168.1.50.68: DHCP, length 308
12:34:56.789020   message-type 2 (offer)
12:34:56.789020   your-ip 192.168.1.50
12:34:56.789020   server-ip 192.168.1.1
12:34:56.789020   DHCP option 53, length 1: 2
12:34:56.789020   DHCP option 1, length 4: 255.255.255.0
12:34:56.789020   DHCP option 3, length 4: 192.168.1.1
12:34:56.789020   DHCP option 6, length 4: 192.168.1.1

Illustrative output

Common DHCP failure modes

The diagnostic cheat sheet:

Symptom	Most likely cause	Verification	Fix
Client gets 169.254.x.x	No DHCP response reached the client	Capture on the client segment; check for DHCPDISCOVER	Verify DHCP service is running on the firewall interface
Client gets no IP at all	DHCP service not running or wrong interface	`sockstat -l	grep :67`
Client gets wrong IP	Scope is bound to wrong interface	Check the scope’s interface in GUI	Move the scope to the right interface
Reservation doesn’t work	MAC format wrong	Compare GUI MAC to `arp -an`	Correct the format
DHCP works for some VLANs, not others	Relay not configured on the VLAN	`sockstat -l	grep :67`
DHCPNAK in the log	Server rejected the request	Read the log context (no scope for the subnet)	Add the scope or fix the reservation
Pool exhaustion	More devices than pool size	`dhcpd.conf` pool vs active leases	Expand pool or add subnet
Existing clients don’t see new options	They have old leases	`dhclient -r; dhclient` on a client	Reduce lease time or force renewal
Gateway in DHCP is wrong	Firewall address changed but scope didn’t	`ifconfig` + DHCP option 3 in capture	Update the scope’s gateway option
DNS in DHCP is wrong	DNS server changed but scope didn’t	DHCP option 6 in capture	Update the scope’s DNS option

Common root causes

Five root causes account for most DHCP failures:

DHCP service not enabled on the interface. The service is configured globally but not bound to the right interface. Fix: enable on the interface under Services → DHCPv4 → [Interface].
Firewall rule blocking DHCP. A custom firewall rule on the LAN interface blocks UDP 67/68. Fix: add a permit rule for DHCP before the deny rule.
Scope bound to wrong interface. The scope exists but is associated with the wrong VLAN. Fix: rebind the scope to the correct interface.
Reservation mismatch. The reservation has a typo in the MAC, or the host has a different MAC (virtualisation). Fix: correct the MAC or pin it on the host.
Lease time too long for change propagation. A configuration change takes up to the lease time to reach clients. Fix: reduce the lease time or force a renewal.

The diagnostic discipline

The discipline that finds the cause in minutes:

Capture first. Before changing anything, capture the DHCP exchange on the wire. The capture shows where the failure is.
Read the logs. The OPNsense DHCP log has the answer in most cases. Look for DHCPDISCOVER, DHCPOFFER, DHCPNAK, and the reason.
Identify the side. Client-side (no Discover from the host) or server-side (no Offer from the firewall) or relay-side (no unicast forwarding).
Fix one thing at a time. Change the scope, save, verify. Change the firewall rule, save, verify. Don’t make multiple changes at once; you will not know which one fixed it.
Verify with a fresh lease. Force the client to release and renew. The new lease shows the fix worked.

The temptation is to skip the capture and guess. The cost of guessing is hours of changing the wrong thing. The cost of the capture is 30 seconds.

Recovering from a DHCP outage

When DHCP has been broken for a while, clients have stale or missing leases. The recovery:

Fix the root cause. Restore the service, fix the rule, correct the scope.
Force a renewal. Either reduce the lease time (so clients renew faster) or run dhclient -r; dhclient on each affected client.
Verify. Confirm leases are being granted; confirm the gateway, DNS, and other options are correct.
Document. Add the incident and the root cause to the runbook.

For an estate with many clients (more than can be touched by hand), reducing the lease time is the right approach. Clients renew within the new lease time; the operator does not need to touch each client.

Summary

DHCP failures show up as missing IP, wrong IP, or correct IP with broken routing/DNS.
Capture with tcpdump -nei <iface> port 67 or port 68 -vvv to see the full exchange.
Read the OPNsense DHCP log; the message sequence (Discover → Offer → Request → Ack/NAK) tells the story.
DHCPNAK is the diagnostic, not the problem; the reason is in the log context.
Five root causes: service not bound, firewall rule, wrong scope, reservation mismatch, lease time.
The discipline: capture first, read logs, identify the side, fix one thing at a time, verify.