Troubleshooting

DHCP and DNS problems on a dnsmasq router fall into a few patterns, and dnsmasq's log (journalctl -u dnsmasq) names most of them.

A VLAN with no range

When a VLAN's dhcp-range is missing (here, commented out by mistake), its clients time out without an address, and the router logs no address range available for DHCP request via guest for every attempt. The interface name in the message tells you which VLAN to look at. The same message appears if a range doesn't match the interface's subnet, for example after renumbering a VLAN without updating its range.

Symptoms and causes

Symptom	Check	Likely cause
Client times out; nothing in dnsmasq's log	nft list chain inet filter input counter	The input chain drops DHCP: allow UDP 67 from the VLAN
Client gets 169.254.x.x	Same as above	No DHCP server answered at all
no address range available for DHCP request via guest	grep dhcp-range /etc/dnsmasq.d/*	That VLAN has no range, or the range is in the wrong subnet
Reserved machine gets a pool address	The lease file and dhcp-host	Wrong MAC (VLAN interfaces use the parent's MAC), or an old lease; release and renew
Local names don't resolve	`grep -E "domain	local	expand" /etc/dnsmasq.d/*`	expand-hosts or domain missing, or the client sent no hostname
Names resolve, internet names don't	dnsmasq's log, using nameserver	Wrong upstream in server=, or the router can't reach it
DNS works from the router, not from clients	`ss -lunp \	grep :53`	dnsmasq isn't listening on that VLAN (interface=), or the firewall drops UDP 53
dnsmasq won't start: failed to create listening socket … Address in use	`ss -lunp \	grep :53`	Another DNS server (systemd-resolved, bind9) already owns port 53

When to move on from dnsmasq

dnsmasq is ideal for one router and a few hundred clients. For DHCP across many sites, failover between two DHCP servers, or a database of leases, use Kea; for a validating recursive resolver with fine-grained control, Unbound; for DNS zones you publish to the internet, an authoritative server such as PowerDNS.

Cheat sheets: Network error messages explained, nftables, Common ports.

root@router:~# sed -i 's/^dhcp-range=set:guest/#dhcp-range=set:guest/' /etc/dnsmasq.d/office.conf && systemctl restart dnsmasq

root@guest:~# dhcpcd -4 -1 -t 15 --noipv4ll eth0.20 2>&1 | tail -3
eth0.20: soliciting a DHCP lease
timed out
dhcpcd exited

root@router:~# journalctl -u dnsmasq --no-pager -o cat -n 3 | grep -v "^read"
no address range available for DHCP request via guest
no address range available for DHCP request via guest
no address range available for DHCP request via guest