diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index d7a7cb2a..a6715526 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -161,6 +161,7 @@ export const docsNavigation = [ title: 'DNS', isOpen: false, links: [ + { title: 'Quickstart', href: '/manage/dns/private-dns-behind-routing-peers' }, { title: 'Overview', href: '/manage/dns' }, { title: 'Configuring Nameservers', href: '/manage/dns/nameserver-groups' }, { title: 'DNS Settings', href: '/manage/dns/dns-settings' }, diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx index 09148be1..9ad7dbd5 100644 --- a/src/pages/manage/dns/index.mdx +++ b/src/pages/manage/dns/index.mdx @@ -274,6 +274,7 @@ When you assign a nameserver to distribution groups: Now that you understand how NetBird handles DNS: +- **[Private DNS Behind Routing Peers](/manage/dns/private-dns-behind-routing-peers)** - Quickstart for DNS servers on private networks - **[Configure Nameservers](/manage/dns/nameserver-groups)** - Step-by-step setup guide - **[DNS Settings](/manage/dns/dns-settings)** - Control DNS management per group - **[Troubleshooting](/manage/dns/troubleshooting)** - Solve common DNS issues diff --git a/src/pages/manage/dns/nameserver-groups.mdx b/src/pages/manage/dns/nameserver-groups.mdx index 62679f19..f77ac073 100644 --- a/src/pages/manage/dns/nameserver-groups.mdx +++ b/src/pages/manage/dns/nameserver-groups.mdx @@ -369,13 +369,7 @@ Result: Uses DNS2 (more specific) ### Disabling DNS Management for Specific Groups -Some peers may need to keep their local DNS configuration (e.g., VPN requirements, corporate policy). - -1. Go to **DNS Settings** (not Nameservers) -2. Add groups to **Disabled Management Groups** -3. Peers in these groups will ignore all NetBird DNS configuration - -See [DNS Settings](/manage/dns/dns-settings) for details. +Some peers may need to keep their local DNS configuration (e.g., VPN requirements, corporate policy). See [DNS Settings](/manage/dns/dns-settings) to disable DNS management for specific groups. --- @@ -488,53 +482,9 @@ See [Troubleshooting](/manage/dns/troubleshooting) for more diagnostic commands. --- -## Advanced: Private DNS Behind Routing Peers - -If your DNS server is on a private network accessible only through a routing peer, you need to set up network routes and access control in addition to the nameserver configuration. - -### Scenario - -You have: -- **DNS server**: `192.168.0.32:53` on a private network -- **Routing peer**: Can reach the `192.168.0.0/24` network -- **Client peers**: Need to query this DNS through the routing peer - -### Setup Requirements - -#### 1. Configure the Nameserver - -Create a nameserver pointing to your private DNS: -- IP: `192.168.0.32` -- Port: `53` -- Distribution groups: Your client peer groups (e.g., "Remote Developers") - -#### 2. Create a Network Route - -Set up a network route so clients can reach the DNS server: -- Network: `192.168.0.0/24` -- Routing peer: The peer that can access this network -- Distribution groups: Same as your nameserver (e.g., "Remote Developers") - -#### 3. Configure Access Control - -Create an access control rule allowing DNS traffic: -- Source: Client groups (e.g., "Remote Developers") -- Destination: Routing peer's group -- Protocol: UDP -- Port: 53 - -### DNS Forwarder Port - - -**Technical detail**: When using private DNS behind routing peers, NetBird uses a DNS forwarder on routing peers. Starting with v0.59.0, this forwarder uses port `22054` (changed from `5353`) to avoid collisions with mDNS. For backward compatibility, port `5353` is used if any peer in your account runs below v0.59.0. - - -This forwarder port is internal to NetBird's routing mechanism - you don't need to configure it, but may see it in logs or network traces. - ---- - ## Next Steps +- **[Private DNS Behind Routing Peers](/manage/dns/private-dns-behind-routing-peers)** - Quickstart for DNS servers on private networks - **[DNS Settings](/manage/dns/dns-settings)** - Disable DNS management for specific groups - **[Troubleshooting](/manage/dns/troubleshooting)** - Fix common DNS issues - **[API Reference](/ipa/resources/dns)** - Automate with the API diff --git a/src/pages/manage/dns/private-dns-behind-routing-peers.mdx b/src/pages/manage/dns/private-dns-behind-routing-peers.mdx new file mode 100644 index 00000000..108e1367 --- /dev/null +++ b/src/pages/manage/dns/private-dns-behind-routing-peers.mdx @@ -0,0 +1,72 @@ +export const description = 'Quickstart guide for configuring private DNS servers behind routing peers' +import {Note} from "@/components/mdx" + + +# Quickstart: Private DNS Behind Routing Peers + +If your DNS server is on a private network accessible only through a routing peer, you need to set up network routes and access control in addition to the nameserver configuration. + +## Scenario + +You have: +- **DNS server**: `192.168.0.32:53` on a private network +- **Routing peer**: Can reach the `192.168.0.0/24` network +- **User peers**: Need to query this DNS through the routing peer + +## Setup Steps + +### Step 1: Configure the Nameserver + +Create a nameserver pointing to your private DNS: +- DNS - Nameservers - Add nameserver - Custom DNS +- IP: `192.168.0.32` +- Port: `53` +- Distribution groups: Your user peer groups (e.g., "Remote Developers") + + +For detailed instructions on creating nameservers, see [Configuring Nameservers](/manage/dns/nameserver-groups). + + +### Step 2: Create a Network Route + +Set up a NetBird Network so clients can reach the DNS server: +- Networks - Add network +- Network: e.g. "Office Network" +- Add Resource: `192.168.0.32/32` +- Distribution groups: Internal DNS +- Routing peer: The always-on peer that can access this network + + +For detailed instructions on creating network routes, see [Routing Traffic to Private Networks](/manage/network-routes/routing-traffic-to-private-networks). + + +### Step 3: Configure Access Control + +Create an access control rule allowing DNS traffic: +- Source: User groups (e.g., "Remote Developers") +- Destination: Internal DNS (the resource group) +- Protocol: UDP +- Port: 53 + + +For detailed instructions on access control, see [Manage Network Access](/manage/access-control/manage-network-access). + + +## Technical Details + +### DNS Forwarder Port + + +**Technical detail**: When using private DNS behind routing peers, NetBird uses a DNS forwarder on routing peers. Starting with v0.59.0, this forwarder uses port `22054` (changed from `5353`) to avoid collisions with mDNS. For backward compatibility, port `5353` is used if any peer in your account runs below v0.59.0. + + +This forwarder port is internal to NetBird's routing mechanism - you don't need to configure it, but may see it in logs or network traces. + +--- + +## Next Steps + +- **[Configuring Nameservers](/manage/dns/nameserver-groups)** - Learn more about DNS configuration +- **[Network Routes](/manage/network-routes/routing-traffic-to-private-networks)** - Understand routing to private networks +- **[Access Control](/manage/access-control/manage-network-access)** - Configure network access policies +- **[DNS Troubleshooting](/manage/dns/troubleshooting)** - Fix common DNS issues