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 the three things the router's own services cannot. This is the one catalogue entry that exists to close documented platform gaps, and the UI marks it as such.

The three gaps#

Two of these are things the OPNsense importer reports 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#

Services → Apps → dnsmasq.

set container name dnsmasq image docker.io/jpillora/dnsmasq:latest
set container name dnsmasq network apps address 10.99.0.6
set container name dnsmasq capability net-admin
set container name dnsmasq capability net-bind-service
set container name dnsmasq volume conf source /config/apps/dnsmasq/dnsmasq.conf
set container name dnsmasq volume conf destination /etc/dnsmasq.conf

The conf volume is a file, not a directory: one dnsmasq.conf mounted into the container. Create it before you commit, or the container has nothing to read.

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. Restart the container to pick up a change — Update check and restart.

Step 3 — Forward the domain to it#

Once dnsmasq is running, the DNS page grows a card:

Hand wildcard zones to dnsmasq — VyOS rejects wildcard names in its authoritative zones. Forward the specific domain to dnsmasq and it answers *.domain from one line of its config.

with the container's real address and the router's domain filled in.

set service dns forwarding domain lab.example.com name-server 10.99.0.6

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. Plan that deliberately: 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 forwarding line is missing or wrong.

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#

delete service dns forwarding domain lab.example.com
delete container name dnsmasq

The configuration file under /config/apps/dnsmasq stays behind.