Wildcard DNS, per-host DHCP options and a PXE architecture matrix#

You will end up with dnsmasq running as a container alongside the router's own services, answering what the router's own services cannot.

What the router does itself now#

Wildcard DNS. A record named * in a zone on the DNS page answers for every name in the zone — see Local names. It needs no container.

Per-host DHCP options. A reservation on the DHCP page hands its own DNS servers and default router in place of its scope's — see Give a device the same address every time. dnsmasq is still the answer for options the router cannot set per host, such as a boot file.

The gap that remains#

The OPNsense importer reports an old router's per- architecture boot files as not translated, which is how most people arrive here.

Before you start#

The operator role and a licence.
A decision about scope. dnsmasq can answer one domain, or take DNS wholesale. Start with one domain.
Container support on the router.

Step 1 — Install it#

On Services → Apps, press Install on the dnsmasq card, as in Install an app. Leave Use the router's own network off; this guide uses the address 10.99.0.6 on the app network. The install gives dnsmasq the two permissions it needs, and one storage entry, conf.

The conf volume is a file, not a directory: /config/apps/dnsmasq/dnsmasq.conf on the router, mounted as /etc/dnsmasq.conf in the app. Install creates it, empty, before it saves the change. Press Install, then Apply changes.

Step 2 — Write its configuration#

Everything dnsmasq does here is in that one file, which the entry's notes point at.

/config/apps/dnsmasq/dnsmasq.conf

# Wildcard: everything under lab.example.com answers with one address.
address=/lab.example.com/192.0.2.10

# A per-host DHCP option override, matched on the client.
dhcp-host=00:00:5e:00:53:01,set:printer
dhcp-option=tag:printer,option:dns-server,192.0.2.53

# PXE, per client architecture (RFC 4578 option 93).
dhcp-match=set:efi-x86_64,option:client-arch,7
dhcp-match=set:bios,option:client-arch,0
dhcp-boot=tag:efi-x86_64,bootx64.efi,,192.0.2.50
dhcp-boot=tag:bios,pxelinux.0,,192.0.2.50

It is on /config, so it survives an image upgrade, and it is a plain file you edit from the console or over SSH; the web UI does not edit it. To pick up a change, press Restart on dnsmasq's page — see Update check and restart.

Step 3 — Forward the domain to it#

Once dnsmasq is running, the DNS page shows the app's offer to forward a domain to it, with the container's real address and the router's domain filled in. Or do it yourself: Services → DNS, Forwarding tab, Add domain, the domain lab.example.com and the server 10.99.0.6, with Recursive servers on. Save and apply.

The router's resolver stays in charge of everything else; only that domain goes to dnsmasq. That is the arrangement to prefer: a narrow delegation rather than replacing the router's DNS.

Step 4 — For DHCP, choose one server per segment#

dnsmasq's per-host options only apply to clients dnsmasq is serving. Two DHCP servers on one segment is a race, so on a segment where you need per-host overrides, dnsmasq takes DHCP for that segment and the router's own server does not.

That means the container needs to see the segment's broadcasts, which means host networking rather than a container address — and host networking brings back the port-53 conflict. On a router where dnsmasq handles DHCP on the host network, it usually handles DNS as well, and the router's own forwarder is turned off.

Check it worked#

The wildcard answers:

bash

dig @192.0.2.1 anything.lab.example.com
dig @10.99.0.6 anything.lab.example.com

Both should return 192.0.2.10. The first going somewhere else means the domain is not forwarded, or forwarded to the wrong address.

The container is healthy. The entry's health probe is a TCP connection to port 53. Apps → Installed.

PXE works, which is only really testable by booting something.

Undoing it#

Stop forwarding the domain — click it under Domain forwarding and Delete — and uninstall the app, in the same apply.

Press Uninstall on dnsmasq's page, and apply it with the change above in one Apply changes. The configuration file under /config/apps/dnsmasq stays behind.