dns: Add dnsmasq-to-unbound plugin

[chall37]

Summary

This plugin automatically registers dnsmasq DHCP leases and static host entries in Unbound DNS, enabling local hostname resolution for DHCP clients.

Note: This plugin is intended as a stopgap solution until native integration between Unbound and a supported DHCP service is implemented in OPNsense core.

Related Issues

• Unbound cannot resolve dnsmasq DHCP reservations unless Domain in the reservation is set, contrary to documentation core#8612 - Unbound cannot resolve dnsmasq DHCP reservations unless Domain is set
• wizard: auto configure DHCP/DNS registration query forwarding core#8969 - wizard: auto configure DHCP/DNS registration query forwarding
• Dnsmasq domain override not used for static hostnames: possible regression? core#9277 - Dnsmasq domain override not used for static hostnames

Features

• Watches dnsmasq lease file and static hosts for changes
• Registers A and PTR records in Unbound DNS
• Supports multiple domains via dnsmasq IP-range-to-domain mapping
• Deduplicates records (static entries take precedence over leases)
• Automatic cleanup of stale records
• System status notifications in OPNsense web UI
• Periodic reconciliation to handle Unbound restarts

Requirements

• OPNsense with Unbound DNS resolver enabled (remote control enabled by default)
• dnsmasq plugin installed and configured with DHCP

Testing

Tested on OPNsense 24.7 with:

• DHCP lease registration
• Static host registration
• Domain filtering
• System status notifications
• Service start/stop/restart

[Monviech]

https://docs.opnsense.org/manual/dnsmasq.html#dhcpv4-with-dns-registration

You wrote so much code for something that is already working natively for lots of people, was battle tested, and is the recommended default solution (even by the system wizard in 25.7).

Just saying this PR is DOA.

[chall37]

https://docs.opnsense.org/manual/dnsmasq.html#dhcpv4-with-dns-registration

You wrote so much code for something that is already working natively for lots of people, was battle tested, and is the recommended default solution (even by the system wizard in 25.7).

Just saying this PR is DOA.

https://github.com/chall37/plugins/tree/dnsmasq-to-unbound/dns/dnsmasq-to-unbound#background

There are various issues with dnsmasq integration with unbound, and the fact that it "works natively for lots of people" who don't mind the tradeoffs is why I created this as a plugin (among other reasons).

Making a PR to opnsense-core doesn't make sense for me, because the LOE of exploring the code and balancing the technological requirements with stakeholder expectations is also more than I can take on (though if I did, it would be focused on Kea integration, not dnsmasq). I needed a solution that works now, for myself, rather than trying to impose my personal philosophy and expectations on the core project. A plugin allows me (and potentially others) to maintain a working fix independent of unrelated updates to opnsense-core, provides streamlined deployment, and it lets me leverage the opnsense web ui to view dnsmasq-unbound mappings in realtime, surface status issues through the system status widget, and so forth.

Basically, this is a low-stakes way for me to contribute a working solution, to share a script I wrote to do this, packaged as a plugin. It solved a problem for me, it let me get my feet wet with writing opnsense plugins (just something to do with a little spare time I had), and it's simple enough that I don't mind being the maintainer for the foreseeable future, until it is rendered obsolete by improvements in the core project. If it helps out other folks, great -- if not, that's okay too.

[Monviech]

The whole DNS infrstructure is based around forwarding and recursively querying authoritative name servers.

By saying that one more hop introduces insufferable latency undermines the whole DNS concept that exists for decades.

Are you sure there is no configuration issue that could be fixed in a forwarding setup that we might have missed to document?

[chall37]

To me, adding unnecessary latency is annoying, but again, it's not the primary driver here. The clearest justification for doing things things this way (to me) is that running dnsmasq's dns service violates the clean boundaries between DHCP and DNS that I want on my system. Unbound's role is DNS, and dnsmasq's role is DHCP (in my setup), and I don't want either of them delegating any part of their responsibilities to the other. As to the point that DNS forwards to authoritative name servers, and that's how it should/does function, I say yes! I completely agree. I would like Unbound to be the authoritative DNS server on my network, which is already true for every case except devices configured via DHCP. (Until I wrote this script). To me, the question isn't "why not just keep using dnsmasq's dns server which sort of works for most people," it's "why must I depend on a dns server which sort of works when I have one that works great already set up and running?" I'm not trying to say that my setup or philosophy is somehow perfect; just that this plugin facilitates my personal preference . If other people want a similar setup, then they're welcome to use this plugin.

…

On Mon, Dec 8, 2025 at 21:37 Monviech ***@***.***> wrote: *Monviech* left a comment (opnsense/plugins#5078) <#5078 (comment)> The whole DNS infrstructure is based around forwarding and recursively querying authoritative name servers. By saying that one more hop introduces insufferable latency undermines the whole DNS concept that exists for decades. Are you sure there is no configuration issue that could be fixed in a forwarding setup that we might have missed to document? — Reply to this email directly, view it on GitHub <#5078 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AO5Y7WRGKONPGD2RYEPDOAT4AZNZDAVCNFSM6AAAAACONNGUHCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMZQGQZDGNJZHE> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[AdSchellevis]

dnsmasq primary purpose is a bit in it's name.... but that's besides the point here ;)

It's obviously not a problem to build your own setup in any way you like, I just don't think it's a good idea to expose it in our plugin system.

We have had the "tail isc's leases and dump them into unboud" for years, which was always one of the most problematic components in our stack, mainly due to the fact that you can not warrant synchronicity properly, which means you will be hunted with edge-cases for the rest of your life.

Plugins for single use-cases are fine to exist (one of the reasons why we are so open with our development documentation), just shouldn't be shipped by us to all other users to avoid confusion and future maintenance issues/disappointments.

[chall37]

Totally get it. FWIW, this plugin tags its entries and performs synchronization, deconflicts on ingest, etc. like I said, it's meant solely to bridge the gap between "tail ISC" and "full Kea integration," though obviously shipping anything can result in setting expectations from users. Cheers!

…

On Mon, Dec 8, 2025 at 23:40 Ad Schellevis ***@***.***> wrote: *AdSchellevis* left a comment (opnsense/plugins#5078) <#5078 (comment)> dnsmasq primary purpose is a bit in it's name.... but that's besides the point here ;) It's obviously not a problem to build your own setup in any way you like, I just don't think it's a good idea to expose it in our plugin system. We have had the "tail isc's leases and dump them into unboud" for years, which was always one of the most problematic components in our stack, mainly due to the fact that you can not warrant synchronicity properly, which means you will be hunted with edge-cases for the rest of your life. Plugins for single use-cases are fine to exist (one of the reasons why we are so open with our development documentation), just shouldn't be shipped by us to all other users to avoid confusion and future maintenance issues/disappointments. — Reply to this email directly, view it on GitHub <#5078 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AO5Y7WW22I6XOMMHEPZ3BW34AZ4FRAVCNFSM6AAAAACONNGUHCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTMMZQHAYTAMRWGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>