config: add dns.hostsLocal to keep custom DNS records local

[DL6ER]

What does this implement/fix?

A custom DNS record only ever defines an address. Any other record type for that name - AAAA when you configured an A, or the HTTPS query browsers send - has no local answer, so dnsmasq forwards it upstream. When the name also exists publicly, the public answer comes back and getaddrinfo() prefers the AAAA over our local A. The override silently stops overriding, and only for some clients: dig sends A alone and looks perfectly fine, which is what makes this so hard to diagnose.

We now write one local=/<name>/ line per hostname in dns.hosts, telling dnsmasq the name is ours and that nothing about it should leave the box. The scope is the configured names and their subdomains, so split DNS keeps working - with sub1.example.com and sub2.example.com defined, sub3.example.com and example.com itself still resolve from upstream as before.

The new dns.hostsLocal is on by default. What it changes is a name you have explicitly claimed, and the old behavior is one setting away, whereas the failure it prevents is silent and client-dependent. Set dns.hostsLocal = false to get it back.

How to test the change during review

Point a custom DNS record at a name that also exists publicly with an AAAA record, e.g., dns.hosts = [ "10.0.0.1 sub1.example.com" ], then from a client:

dig @<pi-hole> sub1.example.com A       # local address, as before
dig @<pi-hole> sub1.example.com AAAA    # NODATA, was the public address
getent ahosts sub1.example.com          # local address, was the public one
dig @<pi-hole> sub3.example.com A       # still resolved upstream

grep '^local=' /etc/pihole/dnsmasq.conf shows one line per configured hostname, and pihole-FTL --config dns.hostsLocal false restores the previous behavior.

Automated coverage: test/test_suite.bats asserts the generated local= lines ("Custom DNS records are treated as local"), and test/pihole.toml carries the new key so the template comparison and the config-write accounting in test_final.bats stay exact.

Additional information

Related issue or feature (if applicable): #2841

Pull request in docs with documentation (if applicable): N/A

---

By submitting this pull request, I confirm the following:

1. I have read and understood the contributors guide, as well as this entire template. I understand which branch to base my commits and Pull Requests against.
2. I have commented my proposed changes within the code.
3. I am willing to help maintain this change if there are issues with it later.
4. It is compatible with the EUPL 1.2 license
5. I have squashed any insignificant commits. (git rebase)
6. My change does not modify src/dnsmasq/. That tree is a verbatim copy of upstream dnsmasq and we do not carry anything in it that deviates from upstream. Fixes have to go through the dnsmasq-discuss mailing list first, we merge them once they are in dnsmasq master.

Checklist:

• The code change is tested and works locally.
• I based my code and PRs against the repository's development branch.
• I signed off all commits. Pi-hole enforces the DCO for all contributions
• I signed all my commits. Pi-hole requires signatures to verify authorship
• I have read the above and my PR is ready for review.

[yubiuser]

I think this is a sensible change. Do you think we should expose this setting via UI at the 'Local DNS records' page?

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[github-actions]

Conflicts have been resolved.

[github-actions]

Conflicts have been resolved.

[Copilot]

Pull request overview

Adds the default-enabled dns.hostsLocal option to keep configured custom DNS hostnames and subdomains local.

Changes:

• Generates dnsmasq local= directives.
• Adds configuration, API documentation, and test fixture support.
• Adds tests for generated directives.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Summary
test/test_suite.bats	Tests generated local rules; coverage should include enabled/disabled behavior and runtime updates.
test/pihole.toml	Adds the new test configuration entry.
src/config/dnsmasq_config.c	Generates local DNS rules; host mutations must regenerate or reload these rules.
src/config/config.h	Adds the configuration field.
src/config/config.c	Registers the new setting and default.
src/api/docs/content/specs/config.yaml	Documents the API property.

Suppressed comments (2)

src/config/dnsmasq_config.c:838

• When dns.expandHosts is enabled with a non-empty dns.domain.name, dnsmasq creates a second hosts entry such as foo.lan for a dotless foo (src/dnsmasq/cache.c:1513-1525). local=/foo/ does not match foo.lan, so queries such as AAAA or HTTPS for the expanded name can still be forwarded, leaving the override vulnerable on the exact path this setting is meant to close. Emit a local rule for each expanded name as well, taking the effective expansion suffix into account.

				fprintf(pihole_conf, "local=/%s/\n", name);

src/config/dnsmasq_config.c:838

• The dns.hosts validator permits a final label longer than 63 characters because it only checks label length when it encounters a dot, while dnsmasq's canonicalise() rejects labels over MAXLABEL (63). Thus an otherwise accepted entry such as 1.2.3.4 <64-character-label> now emits an invalid local= directive, causing generated-config validation or a later restart to fail. Validate/canonicalize the hostname before emitting it, or fix the host validation path.

				fprintf(pihole_conf, "local=/%s/\n", name);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.