DHCP: allow configuring a secondary DNS server (option 6) via the UI for degraded-mode resilience

[NinjDS]

Prerequisites

• I have checked the Wiki and Discussions and found no answer

• I have searched other issues and found no duplicates

• I want to request a feature or enhancement and not ask a question

The problem

(I already posted "#7954" but this is more structured and goes with an incoming PR)

The problem

AdGuard Home’s built-in DHCP server currently advertises only itself as DNS server (DHCP option 6).

This works well in normal conditions, but it creates a single point of failure for the local network:

• if AdGuard Home is temporarily unavailable (update, restart, crash, host issue),
• DHCP clients lose all DNS resolution,
• even though a fallback DNS resolver may exist on the LAN.

This is especially problematic in locked-down deployments (e.g. Home Assistant OS add-on), where:

• users have no access to AdGuardHome.yaml,
• the web UI is the only configuration surface.

Advanced DHCP options (including option 6 overrides) are currently only configurable via YAML, which makes this use case impossible in such environments.

Willingness to contribute

I’m willing to submit a PR implementing this behavior (UI + backend), following maintainers’ guidance on naming and API structure.

Proposed solution

Goal (very limited scope)

Provide a simple, safe and explicit way to configure one or more additional DNS servers advertised by DHCP via the UI, in order to:

• allow a degraded but functional LAN if AdGuard Home is down,
• without exposing generic or unsafe DHCP option editing,
• without breaking existing configurations.

This is not a request to expose full DHCP options editing.

---

Proposed behavior

UI

• Add a new optional field in DHCP settings:

  “Additional DNS servers for DHCP clients”

• Accepts a list of IPv4 / IPv6 addresses.

• Empty by default → current behavior unchanged.

• Display a clear warning (with translations), for example:

  “Secondary DNS servers may bypass AdGuard Home filtering.
  It is recommended to keep AdGuard Home as the first DNS server.”

Backend

• Internally maps this field to DHCP option 6 (ips format).
• Always keeps AdGuard Home’s own IP as the first DNS server.
• Does not expose or modify any other DHCP options.
• Existing YAML configurations with custom dhcp.options must continue to work unchanged.

---

Why this approach is safe

• No raw DHCP option editing.
• No UI access to arbitrary option numbers.
• Only affects option 6, which AdGuard Home already supports.
• Fully backward-compatible.
• Opt-in only.

---

Example use case

Home Assistant OS + AdGuard Home add-on:

• AdGuard Home = primary DNS + DHCP.
• Secondary local resolver (or upstream DNS) configured as fallback.
• If Home Assistant restarts, the LAN keeps basic DNS functionality instead of fully breaking.

---

Implementation notes (high-level)

• Extend DHCP config API to expose a dedicated field (e.g. additional_dns_servers).
• Convert this field to option 6 internally when applying DHCP config.
• UI: simple multi-IP input, reuse existing IP validation components.
• Add warning text with translations.

Alternatives considered and additional information

Alternatives considered

• Editing dhcp.options via UI → rejected (too dangerous / too broad).
• Relying on YAML only → not viable in HAOS and similar environments.

[NinjDS]

To clarify my approach and show where I’m heading, here is how I currently see the implementation.

Identified entry points (backend)

From what I understand of the code, the change would mainly touch:

• the DHCP config API handlers (get/set DHCP configuration),
• the Go structures representing DHCP configuration (I still need to investigate that part)
• the part where DHCP options are generated and applied.

The idea would be to introduce a dedicated, explicit field in the DHCP config (e.g. additional_dns_servers) rather than exposing raw DHCP options.

Proposed API evolution

• Add an optional field like additional_dns_servers: []string to the DHCP config API.
• Empty or unset → current behavior unchanged.
• Internally, this field would be mapped to DHCP option 6 (ips format).
• AdGuardHome’s own IP would always remain the first advertised DNS server.

This avoids exposing generic DHCP option editing while covering the resilience use case.

Safety / compatibility considerations

• No access to arbitrary DHCP options from the UI.
• Only affects option 6, which is already supported internally.
• Fully backward-compatible with existing YAML-based configurations.
• Opt-in only.

If this direction sounds acceptable, I can prepare a first PR focusing on the backend/API side, with unit tests, and follow up with a small UI change once the API contract is validated. I'm not sure whether I'll be able to fully test run my code, however, having nothing set up here.