From f147dddeed3404052e74ca32b7406636f322573c Mon Sep 17 00:00:00 2001 From: Maciek Date: Thu, 24 Sep 2026 16:34:58 +0200 Subject: [PATCH 1/3] docs(app): Add FAQ entries for AdGuard Home and Pi-hole with modDNS Signed-off-by: Maciek --- app/src/pages/legal/FAQ.tsx | 34 +++++++++++++++++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/app/src/pages/legal/FAQ.tsx b/app/src/pages/legal/FAQ.tsx index cbb70163..1d5e7d34 100644 --- a/app/src/pages/legal/FAQ.tsx +++ b/app/src/pages/legal/FAQ.tsx @@ -111,7 +111,7 @@ function FAQSection({ title, children, globalToggleSignal, globalToggleState }: ); } -const FAQ_LAST_UPDATED = 'September 9, 2026'; +const FAQ_LAST_UPDATED = 'September 24, 2026'; const CODE_CLASS = "text-[var(--shadcn-ui-app-foreground)] px-2 py-0.5 rounded text-sm font-mono border border-[var(--shadcn-ui-app-border)]"; const TABLE_CELL_CLASS = "border border-[var(--shadcn-ui-app-border)] px-3 py-2 text-left align-top"; @@ -522,6 +522,30 @@ export default function FAQ(): JSX.Element { ); + const localResolversWithModDNS = ( +
+

Yes, both. Put the local resolver in front of modDNS and let it forward every query it does not answer itself.

+
    +
  • AdGuard Home speaks DoH, DoT and DoQ natively. Add https://dns.moddns.net/dns-query/<profile id>, tls://<profile id>.dns.moddns.net or quic://<profile id>.dns.moddns.net:853 as an upstream, or paste one of your DNS Stamps. Click Test upstreams to confirm.
    • +
  • Pi-hole forwards plain DNS only, so it needs dnscrypt-proxy next to it. Configure dnscrypt-proxy with your DoH stamp (the ready-made dnscrypt-proxy.toml snippet is on the DNS Stamps tab under Setup) and set Pi-hole's upstream to 127.0.0.1#5353. Pi-hole's guide covers the installation: docs.pi-hole.net/guides/dns/dnscrypt-proxy.
    • +
+

Your profile id is shown on the Setup page. To see the resolver as a named device in your query logs, generate the stamp with a device label (see "Can I generate a per-device DNS Stamp?").

+

Filter in one place only: a domain blocked by AdGuard Home or Pi-hole never reaches modDNS and is missing from your modDNS logs and statistics, so turn off the local blocklists and manage blocking in your modDNS profile.

+
+ ); + + const adGuardHomeCannotResolveUpstream = ( +
+

AdGuard Home looks up the modDNS hostname through its own Bootstrap DNS servers setting, not through your system resolver. By default it asks Quad9. If your network only allows DNS to one resolver, that lookup never gets an answer and Test upstreams reports "couldn't communicate with upstream" with "resolving hostname" in the message, even though the modDNS server is reachable.

+

The most common case is a VPN client with a firewall or kill switch, such as the IVPN app, which only allows DNS to IVPN's own resolver. Two fixes, either one is enough:

+
    +
  • Use a DNS Stamp as the upstream. A stamp carries the modDNS address, so no bootstrap lookup is needed. It keeps working whether the VPN is on or off.
    • +
  • Set the bootstrap to the resolver your network allows. With the IVPN app that is the IVPN DNS server; the address depends on your AntiTracker setting, see What is the IP address of your DNS servers?. This only works while the VPN is connected.
    • +
+

AdGuard Home caches the result of the bootstrap lookup. If a setup that worked stops working after you turn a VPN on, restart AdGuard Home after changing the bootstrap, or switch to a stamp.

+
+ ); + const renderFAQContent = () => (
@@ -784,6 +808,10 @@ export default function FAQ(): JSX.Element { question="Which clients can I use a DNS Stamp with?" answer={dnsStampsCompatibleClients} /> + + Date: Fri, 25 Sep 2026 10:39:46 +0200 Subject: [PATCH 2/3] docs(app): State in the FAQ that modDNS serves no plain DNS on port 53 Signed-off-by: Maciek --- app/src/pages/legal/FAQ.tsx | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/app/src/pages/legal/FAQ.tsx b/app/src/pages/legal/FAQ.tsx index 1d5e7d34..cafc5c00 100644 --- a/app/src/pages/legal/FAQ.tsx +++ b/app/src/pages/legal/FAQ.tsx @@ -111,7 +111,7 @@ function FAQSection({ title, children, globalToggleSignal, globalToggleState }: ); } -const FAQ_LAST_UPDATED = 'September 24, 2026'; +const FAQ_LAST_UPDATED = 'September 25, 2026'; const CODE_CLASS = "text-[var(--shadcn-ui-app-foreground)] px-2 py-0.5 rounded text-sm font-mono border border-[var(--shadcn-ui-app-border)]"; const TABLE_CELL_CLASS = "border border-[var(--shadcn-ui-app-border)] px-3 py-2 text-left align-top"; @@ -176,11 +176,14 @@ export default function FAQ(): JSX.Element { }; const supportedProtocols = ( -
    -
  • DNS-over-HTTPS (DoH) - Port 443
    • -
  • DNS-over-TLS (DoT) - Port 853
    • -
  • DNS-over-QUIC (DoQ) - Port 853
    • -
+
+
    +
  • DNS-over-HTTPS (DoH) - Port 443
    • +
  • DNS-over-TLS (DoT) - Port 853
    • +
  • DNS-over-QUIC (DoQ) - Port 853
    • +
+

We do not offer unencrypted DNS on port 53. The modDNS address answers encrypted queries only, so it cannot serve as a bootstrap or fallback resolver in AdGuard Home, routers or similar clients; use any plain resolver for that role.

+
); const howToCreateProfile = ( From 7e1662a787f2baae57cf694bfd554f24a925abef Mon Sep 17 00:00:00 2001 From: Maciek Date: Fri, 25 Sep 2026 12:42:33 +0200 Subject: [PATCH 3/3] docs(app): Match the Pi-hole upstream example to dnscrypt-proxy's listen address Signed-off-by: Maciek --- app/src/pages/legal/FAQ.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/src/pages/legal/FAQ.tsx b/app/src/pages/legal/FAQ.tsx index cafc5c00..a0814f41 100644 --- a/app/src/pages/legal/FAQ.tsx +++ b/app/src/pages/legal/FAQ.tsx @@ -530,7 +530,7 @@ export default function FAQ(): JSX.Element {

Yes, both. Put the local resolver in front of modDNS and let it forward every query it does not answer itself.

  • AdGuard Home speaks DoH, DoT and DoQ natively. Add https://dns.moddns.net/dns-query/<profile id>, tls://<profile id>.dns.moddns.net or quic://<profile id>.dns.moddns.net:853 as an upstream, or paste one of your DNS Stamps. Click Test upstreams to confirm.
    • -
  • Pi-hole forwards plain DNS only, so it needs dnscrypt-proxy next to it. Configure dnscrypt-proxy with your DoH stamp (the ready-made dnscrypt-proxy.toml snippet is on the DNS Stamps tab under Setup) and set Pi-hole's upstream to 127.0.0.1#5353. Pi-hole's guide covers the installation: docs.pi-hole.net/guides/dns/dnscrypt-proxy.
    • +
  • Pi-hole forwards plain DNS only, so it needs dnscrypt-proxy next to it. Configure dnscrypt-proxy with your DoH stamp (the ready-made dnscrypt-proxy.toml snippet is on the DNS Stamps tab under Setup) and set Pi-hole's upstream to the address dnscrypt-proxy listens on, for example 127.0.0.1#5053 when listen_addresses in dnscrypt-proxy.toml is 127.0.0.1:5053; the two must match. Pi-hole's guide covers the installation: docs.pi-hole.net/guides/dns/dnscrypt-proxy.

Your profile id is shown on the Setup page. To see the resolver as a named device in your query logs, generate the stamp with a device label (see "Can I generate a per-device DNS Stamp?").

Filter in one place only: a domain blocked by AdGuard Home or Pi-hole never reaches modDNS and is missing from your modDNS logs and statistics, so turn off the local blocklists and manage blocking in your modDNS profile.