From 204c2793f3431a5e4acd34afdd19207aa5d21562 Mon Sep 17 00:00:00 2001 From: Jack Carter <128555021+SunsetDrifter@users.noreply.github.com> Date: Tue, 11 Aug 2026 17:24:23 +0200 Subject: [PATCH] docs: unmanaged DNS mode also ignores Custom Zone records (#916) * docs: unmanaged DNS mode also ignores Custom Zone records A peer whose group is under DNS Settings -> Disable DNS Management (or started with --disable-dns) never gets NetBird's resolver wired into the OS, so Custom Zone records silently stop resolving along with nameservers. The unmanaged-mode description, the Custom Zones limitations list, and the DNS troubleshooting flow now say so, and the troubleshooting page gains a confirm-managed-mode first check (the existing --disable-dns isolation test reproduces this exact cause and misreads as 'not NetBird DNS'). Also fixes the API Reference links to the canonical /api path (/ipa redirects). * docs: fix DNS API Reference link on the DNS landing page --- src/pages/manage/dns/custom-zones.mdx | 1 + src/pages/manage/dns/dns-settings.mdx | 6 +++--- src/pages/manage/dns/index.mdx | 2 +- src/pages/manage/dns/troubleshooting.mdx | 14 +++++++++++++- 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/src/pages/manage/dns/custom-zones.mdx b/src/pages/manage/dns/custom-zones.mdx index 18bcb074..6534e3a8 100644 --- a/src/pages/manage/dns/custom-zones.mdx +++ b/src/pages/manage/dns/custom-zones.mdx @@ -108,6 +108,7 @@ Custom DNS Zones have the following limitations: - **Cannot use peer DNS domain**: Zone domain must not conflict with your NetBird peer DNS domain (e.g., `netbird.cloud`, `netbird.selfhosted`, or a custom domain configured via the `--dns-domain` flag or in **Settings** > **Network** > **DNS Domain**) - **CNAME exclusivity**: CNAME records cannot coexist with A or AAAA records for the same hostname - **Empty zones not distributed**: Zones without any DNS records are not distributed to peers +- **Requires managed DNS**: Peers in groups listed under **DNS** > **DNS Settings** (Disable DNS Management), or started with `netbird up --disable-dns`, run in [unmanaged mode](/manage/dns/dns-settings#unmanaged-mode) and will not resolve zone records, even when the zone's distribution groups include them ## Use Cases diff --git a/src/pages/manage/dns/dns-settings.mdx b/src/pages/manage/dns/dns-settings.mdx index eebea303..ee26de09 100644 --- a/src/pages/manage/dns/dns-settings.mdx +++ b/src/pages/manage/dns/dns-settings.mdx @@ -15,7 +15,7 @@ NetBird configures the system's DNS settings. All DNS queries route through NetB ### Unmanaged Mode -NetBird does not modify system DNS settings. The peer uses its pre-existing DNS configuration and all configured nameservers are ignored. +NetBird does not modify system DNS settings. The peer uses its pre-existing DNS configuration, and all configured nameservers and [Custom Zone](/manage/dns/custom-zones) records are ignored, including zones distributed to a group this peer belongs to. Use unmanaged mode when a peer has conflicting VPN or DNS requirements, corporate policy requires specific DNS settings, or you're troubleshooting DNS issues. @@ -36,7 +36,7 @@ netbird up --disable-dns=false ``` -The `--disable-dns` flag takes precedence over server-side DNS settings. Even if the management server configures nameservers for this peer's group, the peer will ignore them when this flag is set. +The `--disable-dns` flag takes precedence over server-side DNS settings. Even if the management server configures nameservers or Custom Zone records for this peer's group, the peer will ignore them when this flag is set. The flag persists across reconnects: a later plain `netbird up` keeps DNS management disabled until you run `netbird up --disable-dns=false`. ## Configuring DNS Settings @@ -86,7 +86,7 @@ curl -X PUT https://api.netbird.io/api/dns/settings \ }' ``` -See the full [API Reference](/ipa/resources/dns) for more details. +See the full [API Reference](/api/resources/dns) for more details. --- diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx index 16bf79f9..f822d5a9 100644 --- a/src/pages/manage/dns/index.mdx +++ b/src/pages/manage/dns/index.mdx @@ -142,4 +142,4 @@ You can disable DNS management for specific groups in [DNS Settings](/manage/dns - **[Custom Zones](/manage/dns/custom-zones)** - Create private DNS records distributed to peers - **[Extra DNS Labels](/manage/dns/extra-dns-labels)** - Assign additional DNS names to peers for service discovery and load balancing - **[Troubleshooting](/manage/dns/troubleshooting)** - Diagnose DNS issues -- **[API Reference](/ipa/resources/dns)** - Automate DNS configuration +- **[API Reference](/api/resources/dns)** - Automate DNS configuration diff --git a/src/pages/manage/dns/troubleshooting.mdx b/src/pages/manage/dns/troubleshooting.mdx index 58a63657..cfc22002 100644 --- a/src/pages/manage/dns/troubleshooting.mdx +++ b/src/pages/manage/dns/troubleshooting.mdx @@ -57,6 +57,18 @@ nslookup google.com If any of these fail, continue to the relevant section below. +### First: Confirm the Peer Is in Managed Mode + +Before anything else, confirm NetBird is managing DNS on this peer at all. If any group the peer belongs to is listed under **DNS** > **DNS Settings** (Disable DNS Management), the peer runs in [unmanaged mode](/manage/dns/dns-settings#unmanaged-mode): NetBird never wires its resolver into the operating system, so nameservers and [Custom Zone](/manage/dns/custom-zones) records are silently ignored, even when their distribution groups include the peer. This is easy to miss: nothing on the Nameservers or Zones screens indicates that a peer is unmanaged, and the result is exactly the symptoms this page covers. + +1. In the dashboard, open **DNS** > **DNS Settings** and check whether any of the peer's groups is listed. Remove it (or move the peer out of that group) if DNS should be managed. +2. On the peer, run `netbird status -d`. If the **Nameservers** section is empty even though nameservers are configured for the peer's groups, the peer is in unmanaged mode. +3. Also check the peer wasn't started with `netbird up --disable-dns`. In that case `netbird status -d` still lists the nameservers as Available, but the system's active DNS configuration (step 3 of the checklist above) won't show NetBird's resolver. The flag persists across reconnects; clear it with `netbird up --disable-dns=false`. + + +A peer in unmanaged mode also makes the isolation test below misleading: disabling DNS management on a peer where it was never applied changes nothing, so "problem persists" would wrongly suggest the issue is unrelated to NetBird DNS. + + **Quick isolation test**: To check if an issue is caused by NetBird DNS, temporarily disable DNS management on the peer: ```bash @@ -988,4 +1000,4 @@ Avoid future DNS issues: - **[DNS Overview](/manage/dns)** - Understand DNS architecture - **[Internal DNS Servers](/manage/dns/internal-dns-servers)** - Nameserver configuration and internal DNS - **[DNS Settings](/manage/dns/dns-settings)** - Management modes -- **[API Reference](/ipa/resources/dns)** - Automate DNS +- **[API Reference](/api/resources/dns)** - Automate DNS