diff --git a/next.config.mjs b/next.config.mjs index 6b13aee9..80f7706d 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -48,7 +48,7 @@ const nextConfig = { }, { source: '/docs/how-to-guides/nameservers', - destination: '/manage/dns/nameserver-groups', + destination: '/manage/dns/internal-dns-servers', permanent: true, }, { diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 811ee589..b0ca31ae 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -293,14 +293,10 @@ 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: 'Internal DNS Servers', + href: '/manage/dns/internal-dns-servers', }, { title: 'DNS Settings', href: '/manage/dns/dns-settings' }, { title: 'Custom Zones', href: '/manage/dns/custom-zones' }, @@ -530,9 +526,8 @@ export const docsNavigation = [ }, { title: 'Management Geolocation Database', - href: '/selfhosted/geo-support' + href: '/selfhosted/geo-support', }, - ], }, { @@ -619,8 +614,9 @@ export const docsNavigation = [ title: 'Coturn to Embedded STUN', href: '/selfhosted/migration/coturn-to-stun-migration', }, - { title: 'Combined Container Setup', - href: '/selfhosted/migration/combined-container' + { + title: 'Combined Container Setup', + href: '/selfhosted/migration/combined-container', }, { title: 'Enable Reverse Proxy', @@ -876,4 +872,4 @@ function NavigationGroup({ group, className, hasChildren }) { ) -} \ No newline at end of file +} diff --git a/src/pages/manage/dns/dns-settings.mdx b/src/pages/manage/dns/dns-settings.mdx index 48312c80..eebea303 100644 --- a/src/pages/manage/dns/dns-settings.mdx +++ b/src/pages/manage/dns/dns-settings.mdx @@ -1,38 +1,27 @@ export const description = 'Control DNS management behavior for peer groups' +import {Note} from "@/components/mdx" # DNS Settings -DNS Settings allow you to control whether NetBird manages DNS configuration for specific peer groups. This is useful when certain peers need to maintain their existing DNS setup. +DNS Settings control whether NetBird manages DNS configuration for specific peer groups. This is useful when certain peers need to maintain their existing DNS setup. -## Understanding DNS Management Modes +## DNS Management Modes NetBird supports two DNS management modes per peer: ### Managed Mode (Default) -When a peer's group is **not** in the disabled management list: - -- ✅ NetBird configures the system's DNS settings -- ✅ All DNS queries route through NetBird's local resolver -- ✅ Configured nameservers apply to this peer -- ✅ Centralized DNS control from the dashboard - -**Use managed mode when**: You want full control over DNS resolution for the peer. +NetBird configures the system's DNS settings. All DNS queries route through NetBird's local resolver, and configured nameservers apply to this peer. ### Unmanaged Mode -When a peer's group **is** in the disabled management list: +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 -- ✅ Peer uses its pre-existing DNS configuration -- ✅ All configured nameservers are ignored for this peer -- ✅ Peer maintains complete DNS independence +Use unmanaged mode when a peer has conflicting VPN or DNS requirements, corporate policy requires specific DNS settings, or you're troubleshooting DNS issues. -**Use unmanaged mode when**: -- Peer has conflicting VPN or DNS requirements -- Corporate policy requires specific DNS settings -- Testing or troubleshooting DNS issues -- Peer is in a restricted environment + +Even in unmanaged mode, peers can still communicate over the NetBird network. DNS management only affects name resolution, not connectivity. + ### Client-Side DNS Control @@ -46,34 +35,19 @@ netbird up --disable-dns netbird up --disable-dns=false ``` -This is useful when: -- You need to disable DNS on a single peer without changing server-side settings -- Testing DNS behavior locally -- The peer has special DNS requirements not covered by group settings - 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. ## Configuring DNS Settings -### View Current Settings - -1. Log in to NetBird dashboard -2. Navigate to **DNS** in the sidebar -3. Click **DNS Settings** tab - -You'll see: -DNS settings - - ### Disable DNS Management for a Group -To prevent NetBird from managing DNS for specific groups: - 1. Go to **DNS** → **DNS Settings** -2. Click the groups selection box and select groups existing groups, or type a new group name and press enter. This will create a new group inline and disable DNS management for said new group. -3. Click 'Save Changes'. +2. Click the groups selection box and select existing groups, or type a new group name and press enter to create one inline +3. Click **Save Changes** + +DNS settings Changes take effect within 10-30 seconds. Peers in disabled groups will revert to their original DNS settings. @@ -81,159 +55,13 @@ Changes take effect within 10-30 seconds. Peers in disabled groups will revert t ### Re-enable DNS Management -To restore NetBird DNS management: - 1. Go to **DNS** → **DNS Settings** -2. Remove the group from **Disabled Management Groups** -3. Click 'Save Changes'. +2. Remove the group from the disabled list +3. Click **Save Changes** -The peer will start using configured nameserver groups again. +### Domain Controllers ---- - -## Common Use Cases - -### Use Case 1: VPN Conflict - -**Problem**: Peers using another VPN conflict with NetBird's DNS management. - -**Solution**: -1. Create a distribution group for VPN users (e.g., "External VPN Users") -2. Add this group to disabled management groups -3. These peers keep their VPN's DNS settings - -### Use Case 2: Corporate DNS Policy - -**Problem**: Company policy requires specific DNS servers on certain devices. - -**Solution**: -1. Group affected peers (e.g., "Compliance Devices") -2. Disable DNS management for this group -3. Manually configure DNS on these devices per policy - -### Use Case 3: Gradual Rollout - -**Problem**: Want to test DNS changes on a subset of peers first. - -**Solution**: -1. Create "DNS Beta" and "DNS Production" groups -2. Initially disable management for "DNS Production" -3. Test with "DNS Beta" group -4. Once validated, enable management for "DNS Production" - -### Use Case 4: Troubleshooting - -**Problem**: Suspect NetBird DNS is causing connectivity issues. - -**Solution**: -1. Temporarily add peer's group to disabled management -2. Test if issue persists with original DNS -3. If fixed, investigate nameserver configuration -4. If not fixed, issue is unrelated to NetBird DNS - -### Use Case 5: Domain Controllers - -**Problem**: Running NetBird on a Windows Domain Controller used as a routing peer can cause DNS conflicts, since Domain Controllers rely on their own DNS configuration for Active Directory services. - -**Solution**: -1. Create a dedicated group for your Domain Controllers (e.g., "Domain Controllers") -2. Go to **DNS** → **DNS Settings** -3. Add the Domain Controller group to **Disable DNS management for these groups** -4. Save Changes - ---- - -## How Peers Behave in Each Mode - -### Managed Mode Behavior - -``` -Peer Startup: -1. NetBird client starts -2. Receives nameserver configuration from management -3. Configures local DNS resolver (127.0.0.1:53) -4. Updates OS DNS settings to point to 127.0.0.1 -5. Routes queries based on configured nameservers - -During Operation: -- All DNS queries go through NetBird resolver -- Configuration updates apply automatically -``` - -### Unmanaged Mode Behavior - -``` -Peer Startup: -1. NetBird client starts -2. Sees group is in disabled management list -3. Does NOT modify DNS settings -4. Does NOT start local DNS resolver for management -5. Uses existing system DNS configuration - -During Operation: -- DNS queries use system's configured servers -- NetBird nameservers have no effect -- NetBird provides connectivity only -``` - ---- - -## Checking Peer DNS Mode - -### Linux/macOS - -```bash -# Check if NetBird resolver is active -cat /etc/resolv.conf -# Should show: -# nameserver <100.X.X.X> (NetBird IP - managed) -# or other IPs (unmanaged) -``` - -### Windows - -```powershell -# Check DNS servers for NetBird adapter -Get-DnsClientServerAddress -InterfaceAlias "NetBird" - -# Managed: Shows <100.X.X.X> (NetBird IP) -# Unmanaged: Shows other servers or nothing -``` - -#### Using the NetBird CLI - -```bash -# Check NetBird status -netbird status -d -``` - -Example Output: -``` -... -Nameservers: - [1.1.1.1:53] for [.] is Available -... -``` ---- - -## Mixing Managed and Unmanaged Peers - -You can have both modes in the same network: - -**Example Configuration**: -- **All Peers** group: Mixed management - - Most peers: Managed (use configured nameservers) - - VPN users: Unmanaged (keep VPN DNS) - - Guest devices: Unmanaged (no internal DNS) - -**Result**: -- Managed peers can resolve internal domains -- Unmanaged peers only see public DNS -- Both can communicate over NetBird network - - -Even in unmanaged mode, peers can still communicate over the NetBird network. DNS management only affects name resolution, not connectivity. - +For guidance on running NetBird alongside Domain Controllers, including disabling DNS management for DC groups, see [Internal DNS Servers](/manage/dns/internal-dns-servers#active-directory--domain-controllers). --- @@ -241,16 +69,12 @@ Even in unmanaged mode, peers can still communicate over the NetBird network. DN You can manage DNS settings programmatically: -### Get Current Settings - ```bash +# Get current settings curl -X GET https://api.netbird.io/api/dns/settings \ -H "Authorization: Token " -``` -### Update Settings - -```bash +# Update settings curl -X PUT https://api.netbird.io/api/dns/settings \ -H "Authorization: Token " \ -H "Content-Type: application/json" \ @@ -262,130 +86,12 @@ curl -X PUT https://api.netbird.io/api/dns/settings \ }' ``` -See full [API Reference](/ipa/resources/dns) for more details. - ---- - -## Best Practices - -### 1. Default to Managed Mode - -Unless there's a specific reason, keep DNS managed for centralized control and consistency. - -### 2. Use Groups Strategically - -Create distribution groups that align with DNS management needs: -- ✅ Good: "External VPN Users", "Compliance Devices", "Guest Devices" -- ❌ Bad: Disabling management for individual peers repeatedly - -### 3. Document Exceptions - -Keep a record of why certain groups are unmanaged: - -``` -Disabled Management Groups: -- "External VPN Users" → Conflict with corporate VPN -- "Legacy Systems" → Cannot modify DNS (embedded systems) -- "DNS Beta" → Temporary during testing -``` - -### 4. Review Periodically - -Regularly audit disabled groups: -- Are they still needed? -- Can peers be migrated to managed mode? -- Are there security implications? - -### 5. Consider Security - -Unmanaged peers: -- May bypass corporate DNS filtering -- Could be vulnerable to DNS hijacking -- Might not respect DNS-based access controls - -Only use unmanaged mode when necessary. - ---- - -## Troubleshooting - -### Peer Not Respecting Nameservers - -**Symptom**: Configured nameservers don't apply to a peer. - -**Check**: -```bash -# On the dashboard -1. Go to DNS → DNS Settings -2. Check if peer's group is in disabled_management_groups - -# If yes → Remove from list or expected behavior -# If no → Check peer logs for errors -``` - -### Peer Reverting to Old DNS - -**Symptom**: Peer keeps using previous DNS settings after configuration change. - -**Possible causes**: -1. Group added to disabled management -2. Peer not receiving updates (connectivity issue) -3. Peer not restarted after significant change - -**Solution**: -```bash -# Restart NetBird client -netbird down -netbird up - -# Or full restart -systemctl restart netbird # Linux -# Windows: Restart NetBird service -``` - -### Cannot Disable Management for Group - -**Symptom**: Changes to DNS settings don't save or revert. - -**Check**: -- Permissions: Do you have admin rights? -- API errors: Check browser console for error messages -- Group exists: Verify the group ID is correct - ---- - -## Migration Scenarios - -### Moving from Unmanaged to Managed - -When enabling DNS management for a previously unmanaged group: - -1. **Communicate**: Warn users about DNS changes -2. **Prepare**: Create and test nameservers -3. **Schedule**: Choose low-impact time -4. **Enable**: Remove group from disabled list -5. **Verify**: Check peers are using NetBird DNS -6. **Monitor**: Watch for issues in first 24 hours - -### Moving from Managed to Unmanaged - -When disabling DNS management: - -1. **Document**: Note reason for change -2. **Disable**: Add group to disabled management -3. **Verify**: Confirm peers revert to system DNS -4. **Configure**: Manually set DNS if needed -5. **Test**: Ensure connectivity still works +See the full [API Reference](/ipa/resources/dns) for more details. --- ## Next Steps -- **[Configuring Nameservers](/manage/dns/nameserver-groups)** - Configure DNS servers and domains -- **[Troubleshooting](/manage/dns/troubleshooting)** - Diagnose DNS issues -- **[API Reference](/ipa/resources/dns)** - Automate DNS settings - - -Questions about DNS settings? Check the [troubleshooting guide](/manage/dns/troubleshooting) or ask in the [NetBird community](https://netbird.io/slack). - - +- **[Internal DNS Servers](/manage/dns/internal-dns-servers)** — Configure nameservers and internal DNS +- **[Internal DNS Servers](/manage/dns/internal-dns-servers)** — Work with AD, BIND, and other internal DNS +- **[Troubleshooting](/manage/dns/troubleshooting)** — Diagnose DNS issues diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx index 9ad7dbd5..74ef7e50 100644 --- a/src/pages/manage/dns/index.mdx +++ b/src/pages/manage/dns/index.mdx @@ -4,62 +4,22 @@ import {Note} from "@/components/mdx" # DNS in NetBird -NetBird provides intelligent DNS management to help your peers resolve domain names within your private network and control how they access external domains. +NetBird provides centralized DNS management to help your peers resolve domain names within your private network and control how they access external domains. -## DNS Fundamentals +## Key Concepts -Before diving into NetBird's DNS features, let's cover the basics you'll need to understand. +- **Nameserver**: A DNS server that NetBird distributes to peers. You configure these in the dashboard under **DNS → Nameservers**. +- **Match Domains**: Specific domains that should be resolved by a particular nameserver (e.g., `company.internal`). Adding a domain automatically matches all its subdomains. +- **Primary Nameserver**: The default nameserver that handles all domains not matched by specific rules. Configured by leaving match domains empty. +- **Search Domains**: Domain suffixes automatically appended to short hostnames. If you configure `company.internal` as a search domain, typing `server1` will try `server1.company.internal`. Available in v0.24.0+. +- **DNS Resolver**: NetBird runs a local DNS resolver on each peer that routes queries based on your nameserver configuration. -### What is DNS? +### Automatic Peer Domain Names -DNS (Domain Name System) is like a phone book for the internet. When you type `example.com`, DNS translates that human-readable name into an IP address like `93.184.216.34` that computers use to communicate. - -### DNS Resolution Flow - -Here's what happens when a device looks up a domain: - -``` -1. Application requests "internal-app.company.com" - ↓ -2. Operating System checks local DNS cache - ↓ -3. If not cached, queries configured DNS server - ↓ -4. DNS server returns IP address (or forwards query) - ↓ -5. Application connects to the IP address -``` - -### Key DNS Concepts for NetBird - - - - A server that answers DNS queries. NetBird lets you configure which nameservers your peers use. - - - - The component that performs DNS lookups. NetBird runs a local DNS resolver on each peer. - - - - Specific domains that should be resolved by a particular nameserver (e.g., `company.internal`). Adding a domain automatically matches all its subdomains. - - - - The default nameserver that handles all domains not matched by specific rules. In the UI, this is configured by leaving the match domains empty. - - - - Domain suffixes automatically appended to short hostnames. If you configure `company.internal` as a search domain, typing `server1` will try `server1.company.internal`. Available in NetBird v0.24.0 or later. - - - -### NetBird Automatic Domain Names - -Starting with [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name to each peer in a private `netbird.cloud` space. This means you can access your machines using friendly names like `my-server.netbird.cloud` instead of remembering IP addresses like `100.128.185.34`. +Starting with [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name to each peer in a private `netbird.cloud` space. You can access machines using names like `my-server.netbird.cloud` instead of IP addresses. -This feature is available on both NetBird Cloud and self-hosted versions running v0.11.0 or later. +Available on both NetBird Cloud and self-hosted versions running v0.11.0 or later. ## How NetBird Handles DNS @@ -80,54 +40,19 @@ The NetBird management service acts as a DHCP server **only for the NetBird netw - **LAN IPs remain unchanged**: Your local network DHCP continues to work normally - **Two networks, two IPs**: Each peer has both a LAN IP (e.g., `192.168.1.100`) and a NetBird IP (e.g., `100.121.5.10`) -NetBird creates a **parallel overlay network** on top of your existing network infrastructure. Your LAN DHCP server is unaffected. +NetBird creates a **parallel overlay network** on top of your existing network infrastructure. -### Client-Side: How Peers Resolve DNS +### Query Routing -NetBird configures DNS on each peer to enable resolution of NetBird peer domain names (like `my-server.netbird.cloud`) and any custom nameservers you configure. - -#### 1. **Local DNS Resolver Setup** - -NetBird configures the operating system to use its DNS resolver: - -- **Linux**: NetBird always sets up DNS (via `/etc/resolv.conf` directly or `resolvconf` if `systemd-resolved` isn't available). Your original nameservers are preserved as upstream servers, so both NetBird peer domains and regular DNS work. -- **macOS**: NetBird uses system APIs to configure DNS (it does **not** modify `/etc/resolv.conf` directly) -- **Windows**: NetBird sets the network adapter's DNS server to the local NetBird resolver's IP -- **Android**: Uses VPN DNS configuration -- **iOS**: Uses VPN DNS configuration - - -**Android**: For custom DNS resolution to work, you must disable Android's **Private DNS** setting. Go to **Settings → Network & Internet → Private DNS** and set it to **Off**. When Private DNS is enabled, Android bypasses the VPN's DNS configuration and sends DNS queries directly to the configured Private DNS provider. - - - -**Linux behavior**: Even without custom nameservers configured in the dashboard, NetBird sets up DNS. Your original upstream nameservers are preserved. - - -The local resolver runs on `100.x.255.254:53` (in userspace mode) and acts as a "smart proxy" for DNS queries. The `x` corresponds to the second octet of your NetBird /16 block. - -#### 2. **Query Routing** - -When an application makes a DNS query, NetBird's resolver: +When an application makes a DNS query, NetBird's local resolver: 1. **Checks match domains**: Does this query match a specific nameserver? - If yes → Forward to that nameserver - If no → Forward to primary nameserver -2. **Performs the query**: Sends request to the appropriate upstream nameserver -3. **Returns to application**: Sends IP address back +2. **Performs the query**: Sends the request to the appropriate upstream nameserver +3. **Returns the result**: Sends the IP address back to the application - -NetBird does **not** cache most DNS queries. Caching only occurs in specific cases: DNS forwarder on routing peers during upstream failures, and for NetBird infrastructure addresses (management, relay, STUN). - - -#### 3. **Example Flow** - -Let's say you have this configuration: -- **Primary nameserver**: Cloudflare (1.1.1.1) for general internet -- **Match domains**: `company.internal` → Internal DNS (10.0.0.1) -- **Match domains**: `ec2.internal` → AWS DNS (VPC resolver) - -Here's what happens with different queries: +**Example** with a primary nameserver (Cloudflare 1.1.1.1) and a match domain nameserver (`company.internal` → Internal DNS 10.0.0.1): ``` Query: "google.com" @@ -136,39 +61,20 @@ Query: "google.com" Query: "web.company.internal" → Matches company.internal → Internal DNS (10.0.0.1) → Returns private IP -Query: "ip-10-0-1-50.ec2.internal" -→ Matches ec2.internal → AWS DNS → Returns VPC IP - Query: "server" (with search domain "company.internal") → Expanded to "server.company.internal" → Matches company.internal → Internal DNS → Returns private IP ``` -#### 4. **DNS Management Modes** + +NetBird does **not** cache most DNS queries. Caching only occurs for DNS forwarder on routing peers during upstream failures, and for NetBird infrastructure addresses (management, relay, STUN). + -NetBird supports two modes per peer group: +Each peer can have one primary nameserver and multiple match domain nameservers. If a peer belongs to multiple distribution groups, all nameserver configurations from those groups are merged. When multiple nameservers match a query, the most specific match domain wins. - - - NetBird fully controls DNS settings. All queries go through NetBird's resolver. - - **Use when**: You want centralized DNS control - - - - NetBird doesn't modify DNS settings. The peer uses its existing DNS configuration. - - **Use when**: The peer has custom DNS requirements or conflicts with existing DNS setup - - +### Default Behavior (No Nameservers Configured) -You can disable DNS management for specific groups in **DNS Settings** (covered in the configuration guide). - -#### 5. **Default Behavior (No Nameservers Configured)** - -If you don't configure any nameservers in NetBird: - -The default behavior varies by platform: +If you don't configure any nameservers in NetBird, the behavior varies by platform: **Linux** (always sets up DNS): - NetBird always configures DNS so peer domain names (like `my-server.netbird.cloud`) work @@ -189,95 +95,50 @@ You don't need to configure custom nameservers to use NetBird. On Linux, peer do - Custom nameservers can handle specific domains (split-horizon DNS) - Primary nameservers handle all non-matched queries -### Management-Side: How Configuration Works +### DNS Setup Per Platform -#### Nameservers +NetBird configures the operating system to use its DNS resolver: -In the NetBird dashboard under **DNS → Nameservers**, you configure DNS servers for your network. Each nameserver entry defines: - -- **One or more nameserver IPs**: IP addresses of DNS servers (UDP port 53) -- **Match domains** (optional): Specific domains this nameserver should handle -- **Distribution groups**: Which peer groups use this nameserver -- **Primary mode**: Whether this handles all non-matched domains -- **Search domains**: Whether match domains are also search domains +- **Linux**: Always sets up DNS via `/etc/resolv.conf` or `resolvconf`. Original nameservers preserved as upstream. +- **macOS**: Uses system APIs (does **not** modify `/etc/resolv.conf` directly) +- **Windows**: Sets the network adapter's DNS server to the local NetBird resolver +- **Android/iOS**: Uses VPN DNS configuration -The API refers to these as "nameserver groups" because each configuration can contain multiple DNS server IPs for redundancy. The UI simply calls them "Nameservers" for clarity. +**Android**: Custom DNS resolution requires disabling **Private DNS**. Go to **Settings → Network & Internet → Private DNS** and set it to **Off**. When enabled, Android bypasses VPN DNS. -**Starting state**: When you first set up NetBird, the nameservers list is empty. Peers will use their existing system DNS until you create and assign nameservers to their distribution groups. +The local resolver runs on `100.x.255.254:53` (in userspace mode), where `x` corresponds to the second octet of your NetBird /16 block. -#### Configuration Rules +### DNS Forwarder on Routing Peers - - - - Leave match domains **empty** in the UI - - Acts as default/fallback for all queries - - Only one primary per peer - - Handles everything not matched by other nameservers - - - - - Specify one or more match domains - - Only handles queries matching those domains - - You can have multiple match domain nameservers - - More specific patterns take precedence - - +When a [Network resource](/manage/networks) uses a domain name, the routing peer runs a DNS forwarder that resolves domains on behalf of clients. The client's local resolver sends queries to this forwarder, which uses the routing peer's local DNS to resolve the domain and return the result. + +The DNS forwarder listens on port `22054` (changed from `5353` in v0.59.0 to avoid collisions with mDNS). For backward compatibility, port `5353` is used if any peer in your account runs below v0.59.0. -**Platform Support for Match Domains**: Only macOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with match domains. For best compatibility, we recommend configuring at least one primary nameserver (without match domains) assigned to all peers. +NetBird attempts to automatically open the forwarder port on routing peer firewalls, but this may fail on some systems. If domain resources aren't resolving, verify the port is open: `nslookup -port=22054 `. -#### Distribution Logic +### DNS Management Modes -When you assign a nameserver to distribution groups: +NetBird supports two modes per peer group: -1. Any peer in those groups receives the configuration -2. Peers can have multiple nameservers (one primary + multiple match domain nameservers) -3. If a peer matches multiple groups, all their nameservers are merged -4. The most specific match domain wins in case of conflicts +- **Managed Mode** (default): NetBird fully controls DNS settings. All queries go through NetBird's resolver. +- **Unmanaged Mode**: NetBird doesn't modify DNS settings. The peer uses its existing DNS configuration. ---- +You can disable DNS management for specific groups in [DNS Settings](/manage/dns/dns-settings). -## Common Use Cases - -### Use Case 1: Split-Horizon DNS - -**Scenario**: You have internal services at `company.internal` and want peers to use your internal DNS, but use public DNS for everything else. - -**Configuration**: -- **Nameserver 1** (Primary): Cloudflare 1.1.1.1 for general internet -- **Nameserver 2** (Match `company.internal`): Internal DNS 10.0.0.1 (automatically matches all subdomains like `app.company.internal`) - -### Use Case 2: Multi-Cloud Setup - -**Scenario**: Resources in AWS, GCP, and on-premise, each with their own DNS. - -**Configuration**: -- **Nameserver 1** (Primary): Public DNS -- **Nameserver 2** (Match `ec2.internal, compute.internal`): AWS VPC DNS -- **Nameserver 3** (Match `internal.gcp`): GCP Internal DNS -- **Nameserver 4** (Match `company.internal`): On-premise DNS - -### Use Case 3: Content Filtering - -**Scenario**: Block malware/ads for all mobile devices. - -**Configuration**: -- Create a distribution group for mobile peers -- Set primary nameserver to filtering DNS (e.g., NextDNS, Quad9) + +**Match Domain Platform Support**: Only macOS, Windows 10+, and Linux with `systemd-resolved` support nameservers with match domains. We recommend configuring at least one primary nameserver (without match domains) assigned to all peers. + --- ## What's Next? -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 +- **[Internal DNS Servers](/manage/dns/internal-dns-servers)** - Configure nameservers and work with AD, BIND, and other internal DNS - **[DNS Settings](/manage/dns/dns-settings)** - Control DNS management per group -- **[Troubleshooting](/manage/dns/troubleshooting)** - Solve common DNS issues +- **[Custom Zones](/manage/dns/custom-zones)** - Create private DNS records distributed to peers +- **[Troubleshooting](/manage/dns/troubleshooting)** - Diagnose DNS issues - **[API Reference](/ipa/resources/dns)** - Automate DNS configuration - - diff --git a/src/pages/manage/dns/internal-dns-servers.mdx b/src/pages/manage/dns/internal-dns-servers.mdx new file mode 100644 index 00000000..28623cb0 --- /dev/null +++ b/src/pages/manage/dns/internal-dns-servers.mdx @@ -0,0 +1,169 @@ +export const description = 'Configure NetBird to work with internal DNS servers like Active Directory, BIND, and Unbound' +import {Note} from "@/components/mdx" + +# Internal DNS Servers + +When your network has on-premise DNS infrastructure — Active Directory, BIND, Unbound, or other internal DNS servers — you may need to configure NetBird to use them. This page covers when a nameserver configuration is needed and when it isn't. + +## When You Don't Need a Nameserver + +If you just need access to a few internal resources by domain name, you don't need to configure a nameserver. Create a [Network resource](/manage/networks) with the internal domain name (e.g., `fileserver.corp.local`) and an [access control policy](/manage/access-control/manage-network-access) allowing your peers to reach it. The routing peer will resolve the DNS and route traffic to that resource. This works as long as the routing peer itself can resolve the domain. + +You can also use wildcard domains as resources (e.g., `*.corp.local`), but this will route all traffic to those domains through the routing peer. For more granular access to resources, we recommend using single domain names. + +## Domain Resources and Routing Peer DNS + +When you define a [Network resource](/manage/networks) using a domain name (e.g., `crm.corp.local`), the **routing peer** resolves that domain using its own local DNS configuration. The client sends DNS queries to the routing peer, which looks up the domain and returns the result. + +This means the routing peer must be able to resolve the domain. If it can't — for example, a Linux routing peer that isn't configured to use your Active Directory DNS — domain resource lookups will fail. + +To fix this, add the **routing peer's group** as a distribution group on the internal Nameserver: + +1. Go to **DNS** → **Nameservers** +2. Edit your internal DNS nameserver (or create one if it doesn't exist) +3. Add the **routing peer's group** to the **Distribution Groups** +4. Under **Domains**, ensure your internal domains are listed (e.g., `corp.local`) +5. Save + +This ensures the routing peer receives the nameserver configuration and can resolve internal domains on behalf of clients. + + +This applies to all domain-based resources, not just Active Directory domains. Any routing peer that needs to resolve internal domain names must have the corresponding nameserver distributed to its group. + + +## Configuring Nameservers for Internal Domains + +To resolve internal domains through NetBird, create a **match domain** Nameserver pointing to your internal DNS server: + +1. Go to **DNS** → **Nameservers** → **Add Nameserver** +2. Choose **Custom DNS** + +Add nameserver + +3. Add the IP addresses of your internal DNS servers (e.g., `192.168.0.32`) +4. Select the **Distribution Groups** — the peer groups that should use this nameserver + +Custom DNS provider + +5. Under **Domains**, add a **Match Domain** and enter your internal domains (e.g., `corp.local`, `company.internal`) + +Add match domain + +6. Save the nameserver + +Peers in the distribution groups will use your internal DNS server for the specified domains, while all other domains continue to resolve normally. + + +Configure 2-3 nameserver IPs for redundancy. If the first fails, peers automatically try the next one. + + +### Private DNS Behind Routing Peers + +If your internal DNS server is on a private network (not directly reachable by peers), you need to set up routing in addition to the nameserver configuration above. This is common when your DNS server is on an office LAN or cloud VPC that only the routing peer can access. + +**Create a Network Resource** so peers can reach the DNS server through the routing peer: + +1. Go to **Networks** → **Add Network** +2. Add a resource with the DNS server's IP (e.g., `192.168.0.32/32`) +3. Assign the resource to a group (e.g., "Internal DNS") +4. Add the routing peer that can access the private network + +For details, see [Networks](/manage/networks). + +**Create an Access Control Policy** allowing DNS traffic from your peers to the DNS server: + +1. **Source**: Your user groups (e.g., "Remote Developers") +2. **Destination**: The DNS resource group (e.g., "Internal DNS") +3. **Protocol**: UDP, **Port**: 53 + +For details, see [Manage Network Access](/manage/access-control/manage-network-access). + +### Primary vs Match Domain Nameservers + +- **Match domain**: Handles queries for specific domains (e.g., `corp.local`). Adding a domain automatically matches all its subdomains. +- **Primary**: Handles all queries not matched by other nameservers. To create a primary nameserver, leave the Match Domains section empty. + + +Each peer should have exactly **one** primary nameserver. If you don't configure a primary, peers use their original DNS settings for non-matched queries. + + +### Search Domains + +Toggle **Mark match domains as search domains** to enable domain suffix searching. When enabled, typing `server` expands to `server.company.internal`. Only applies to match domain nameservers. + +### Example: Split-Horizon DNS + +A common setup with two nameservers: + +**Primary (internet)**: Select a predefined provider like Cloudflare (1.1.1.1, 1.0.0.1). Assign to "All Peers". Leave match domains empty. + +**Match domain (internal)**: Choose Custom DNS with your internal DNS server IPs (e.g., 10.0.0.1, 10.0.0.2). Assign to "All Peers". Add match domain `company.internal`. Enable search domains. + +Result: +- `google.com` → Cloudflare +- `app.company.internal` → Internal DNS (10.0.0.1) +- `server` → Expanded to `server.company.internal` → Internal DNS + +### DNS Failover and Overlapping Domains + +Configure multiple nameserver IPs within a single nameserver entry for automatic failover. The client tries servers in order. + +If multiple nameservers match a query, the **most specific match wins**: + +``` +Query: app.us-east.company.internal + +Nameservers: +1. company.internal → DNS1 +2. us-east.company.internal → DNS2 + +Result: Uses DNS2 (more specific) +``` + +--- + +## Managing Nameservers + +### Editing + +1. Navigate to **DNS** → **Nameservers** +2. Click the nameserver to edit +3. Modify settings and click **Save** + + +Changes propagate to peers within 10-30 seconds. No peer restart required. + + +### Temporarily Disabling + +Edit the nameserver and toggle **Enable Nameserver** to OFF. Peers stop using it but the configuration is preserved. + +### Deleting + + +Before deleting a primary nameserver, create a new primary first, or peers will revert to their original DNS settings. + + +1. Click the nameserver +2. Click **Delete** and confirm + +--- + +## Active Directory & Domain Controllers + +Active Directory (AD) environments have specific DNS requirements because Domain Controllers (DCs) run their own DNS services and rely on DNS for core AD functionality like domain joins, authentication, and service discovery. + +### Domain Controllers as Routing Peers + +We do not recommend using Domain Controllers as routing peers. If you must, you need to **disable DNS management** for the DC's group. If NetBird manages DNS on a Domain Controller, it can interfere with the AD DNS services that the DC depends on. + +To configure this: + +1. Create a dedicated group for your Domain Controllers (e.g., "Domain Controllers") +2. Go to **DNS** → **DNS Settings** +3. Add the Domain Controller group to **Disable DNS management for these groups** +4. Save Changes + +This prevents NetBird from modifying the DC's DNS configuration while still allowing the DC to act as a routing peer. The DC continues using its own DNS for Active Directory services. + +For more details on DNS management modes, see [DNS Settings](/manage/dns/dns-settings). diff --git a/src/pages/manage/dns/nameserver-groups.mdx b/src/pages/manage/dns/nameserver-groups.mdx index f77ac073..d867a95d 100644 --- a/src/pages/manage/dns/nameserver-groups.mdx +++ b/src/pages/manage/dns/nameserver-groups.mdx @@ -1,494 +1,6 @@ export const description = 'Configure DNS nameservers for your NetBird network' import {Note} from "@/components/mdx" - # Configuring Nameservers -Nameservers let you control which DNS servers your peers use and which domains they handle. This guide walks you through common configuration scenarios. - - -In the NetBird UI, these are called **Nameservers**. In the API documentation, they're referred to as "nameserver groups" because each configuration can contain multiple DNS server IPs for redundancy. - - -## Before You Start - -Make sure you understand: -- [DNS basics and how NetBird handles DNS](/manage/dns) -- Which domains you want to resolve privately vs. publicly -- The IP addresses of your DNS servers - -## Creating Your First Nameserver - -The nameserver configuration follows a **step-by-step UI flow** with three tabs: -1. **Nameserver** (required first) - Add DNS server IPs and distribution groups -2. **Domains** (unlocks after step 1) - Configure primary or match domain mode -3. **Name & Description** (unlocks after step 1) - Add descriptive information - - -The Domains and Name & Description tabs remain disabled until you configure at least one nameserver IP and one distribution group in the Nameserver tab. - - -### Step 1: Choose a DNS Provider - -1. Log in to the NetBird dashboard -2. Navigate to **DNS** > **Nameservers** in the left sidebar -3. Click **Add Nameserver** -4. Select from predefined providers or choose **Custom DNS** to use your own - -Add nameserver IPs - -Choose nameserver provider - -If you choose a predefined provider, the addresses are pre-filled for you. - -### Step 2: Configure Nameserver IPs and Distribution Groups (Nameserver Tab) - -After selecting a provider, you'll be on the **Nameserver** tab. This is the first required step. - - -**Must complete this tab first**: You must configure at least one nameserver IP and at least one distribution group before you can access the Domains and Name & Description tabs. - - - -#### Add Nameserver IPs - -Add a nameserver IP (or multiple IPs for redundancy): - -Custom DNS provider - - - - - IP address of the DNS server (e.g., `10.0.0.1` or `1.1.1.1`) - - - - DNS port, typically `53` - - - -Example configuration: -```json -{ - "nameservers": [ - {"ip": "1.1.1.1", "port": 53}, - {"ip": "1.0.0.1", "port": 53} - ] -} -``` - - -**Best practice**: Configure 2-3 nameservers for redundancy. If the first fails, peers automatically try the next one. - - -#### Assign Distribution Groups - -Select which peer groups will use this nameserver. - - - - At least one peer group must be selected. All peers in these groups will receive this DNS configuration. - - - -Click **+ Add Distribution Group** and select one or more groups from the dropdown. - -#### Enable/Disable Nameserver - -Use the **Enable Nameserver** toggle to activate or deactivate this configuration without deleting it. - -### Step 3: Configure Domains (Domains Tab - Optional) - -Once nameserver IPs and distribution groups are set, click **Continue** or navigate to the **Domains** tab. - -Choose nameserver provider - - -Here you choose whether this is a primary nameserver (handles all domains) or a match domain nameserver (handles specific domains only). - -#### Option A: Primary Nameserver (Leave Domains Empty) - -Leave the **Match Domains** section empty for a primary nameserver that handles all DNS queries not matched by other nameservers. - - -**Important**: -- Each peer should have exactly **ONE** primary nameserver -- Primary nameserver = empty match domains list -- Handles all queries not matched by other nameservers -- If you don't configure a primary, peers use their original DNS settings - - -#### Option B: Match Domain Nameserver (Add Specific Domains) - -Add specific domains that this nameserver should handle: - -Click **+ Add Domain** and enter domain patterns: - -**Supported patterns**: -- Domain match: `company.internal` (automatically matches the domain and all its subdomains like `app.company.internal`) -- Multiple domains per nameserver - -**Example for internal DNS**: -``` -company.internal -internal.example.com -``` - - -Adding a domain like `company.internal` automatically matches both the domain itself and all subdomains (e.g., `app.company.internal`, `server.company.internal`). Wildcard syntax (`*.domain.com`) is not supported in the UI. - - -#### Search Domains - -Toggle **Mark match domains as search domains** to enable domain suffix searching. - -When enabled: -- Typing `server` expands to `server.company.internal` -- Short names automatically try configured domains -- Only applies to match domain nameservers (not primary) - -### Step 4: Set Name and Description (Name & Description Tab) - -Once nameserver IPs and distribution groups are configured, navigate to the **Name & Description** tab. - -Choose nameserver provider - - - - A descriptive name for this nameserver (e.g., "Cloudflare DNS" or "Internal DNS") - - - - Optional notes about this nameserver's purpose (e.g., "Cloudflare DNS Servers" or "Berlin office resolver for remote developers") - - - -### Step 5: Save and Verify - -1. Click **Continue** to move through the tabs, or **Add Nameserver** when you're done configuring -2. The nameserver will be created and distributed to the selected peer groups -3. Wait 10-30 seconds for peers to receive the update -4. Test DNS resolution (see [Troubleshooting](/manage/dns/troubleshooting)) - ---- - -## Common Configuration Scenarios - -### Scenario 1: Simple Internal DNS - -**Goal**: Use Cloudflare for internet, internal DNS for `company.internal` and all its subdomains - -**Configuration**: - - -```json {{ title: 'Primary - Internet' }} -{ - "name": "Cloudflare DNS", - "description": "Public internet DNS", - "nameservers": [ - {"ip": "1.1.1.1", "ns_type": "udp", "port": 53}, - {"ip": "1.0.0.1", "ns_type": "udp", "port": 53} - ], - "enabled": true, - "primary": true, - "domains": [], - "search_domains_enabled": false, - "groups": ["All Peers"] -} -``` - -```json {{ title: 'Match - Internal' }} -{ - "name": "Internal DNS", - "description": "Company internal domains", - "nameservers": [ - {"ip": "10.0.0.1", "ns_type": "udp", "port": 53}, - {"ip": "10.0.0.2", "ns_type": "udp", "port": 53} - ], - "enabled": true, - "primary": false, - "domains": ["company.internal"], - "search_domains_enabled": true, - "groups": ["All Peers"] -} -``` - - -**Result**: -- `google.com` → Cloudflare (1.1.1.1) -- `app.company.internal` → Internal DNS (10.0.0.1) -- `server` → Expanded to `server.company.internal` → Internal DNS - ---- - -### Scenario 2: Multi-Cloud Environment - -**Goal**: Different DNS for AWS, GCP, Azure, and on-premise - -**Configuration**: - - -```json {{ title: 'Primary' }} -{ - "name": "Google Public DNS", - "primary": true, - "domains": [], - "nameservers": [ - {"ip": "8.8.8.8", "ns_type": "udp", "port": 53} - ], - "groups": ["All Peers"] -} -``` - -```json {{ title: 'AWS' }} -{ - "name": "AWS VPC DNS", - "primary": false, - "domains": [ - "ec2.internal", - "compute.internal" - ], - "nameservers": [ - {"ip": "169.254.169.253", "ns_type": "udp", "port": 53} - ], - "groups": ["Engineers", "DevOps"] -} -``` - -```json {{ title: 'GCP' }} -{ - "name": "GCP Internal DNS", - "primary": false, - "domains": [ - "internal.gcp.company.com" - ], - "nameservers": [ - {"ip": "169.254.169.254", "ns_type": "udp", "port": 53} - ], - "groups": ["Engineers", "DevOps"] -} -``` - -```json {{ title: 'On-Premise' }} -{ - "name": "Corporate DNS", - "primary": false, - "domains": [ - "corp.company.com" - ], - "nameservers": [ - {"ip": "10.1.0.1", "ns_type": "udp", "port": 53}, - {"ip": "10.1.0.2", "ns_type": "udp", "port": 53} - ], - "search_domains_enabled": true, - "groups": ["All Peers"] -} -``` - - ---- - -### Scenario 3: Content Filtering for Mobile Devices - -**Goal**: Block ads/malware on company phones and tablets - -**Configuration**: - -```json -{ - "name": "NextDNS Filtering", - "description": "Content filtering for mobile", - "nameservers": [ - {"ip": "45.90.28.0", "ns_type": "udp", "port": 53} - ], - "primary": true, - "domains": [], - "groups": ["Mobile Devices"] -} -``` - - -You can use services like: -- **NextDNS**: Custom filtering policies -- **Quad9**: Malware blocking (9.9.9.9) -- **CleanBrowsing**: Family-safe filtering -- **Pi-hole**: Self-hosted ad blocking - - ---- - -### Scenario 4: Different DNS for Different Teams - -**Goal**: Developers get internal DNS, guests only get public DNS - -**Configuration**: - -1. **For Developers**: - - Primary: Public DNS (all domains) - - Match: Internal DNS (company.internal) - - Assigned to: "Developers" group - -2. **For Guests**: - - Primary: Public DNS only - - No internal DNS access - - Assigned to: "Guests" group - ---- - -## Advanced Configuration - -### DNS Failover and Redundancy - -Always configure multiple nameservers: - -```json -{ - "nameservers": [ - {"ip": "10.0.0.1", "ns_type": "udp", "port": 53}, // Primary - {"ip": "10.0.0.2", "ns_type": "udp", "port": 53}, // Secondary - {"ip": "8.8.8.8", "ns_type": "udp", "port": 53} // Fallback to public - ] -} -``` - -The client will try servers in order with automatic failover. - -### Overlapping Domain Patterns - -If multiple nameservers match a query, the **most specific match wins**: - -``` -Query: app.us-east.company.internal - -Nameservers: -1. company.internal → DNS1 -2. us-east.company.internal → DNS2 - -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). See [DNS Settings](/manage/dns/dns-settings) to disable DNS management for specific groups. - ---- - -## Updating Nameservers - -### Editing an Existing Nameserver - -1. Navigate to **DNS** → **Nameservers** -2. Click the group to edit -3. Modify settings -4. Click **Save** - - -Changes propagate to peers within 10-30 seconds. No peer restart required. - - -### Temporarily Disabling a Nameserver - -Instead of deleting, you can disable: - -1. Edit the nameserver -2. Toggle **Enable Nameserver** to OFF -3. Save - -Peers will stop using this nameserver but the configuration is preserved. - -### Deleting a Nameserver - - -**Before deleting a primary nameserver**: Create a new primary first, or peers will revert to their original DNS settings. - - -1. Click the nameserver -2. Click **Delete** -3. Confirm deletion - ---- - -## Best Practices - -### 1. Start Simple - -Begin with just two nameservers: -- One primary (public DNS) -- One match domain (internal) - -Add complexity only as needed. - -### 2. Use Descriptive Names - -Bad: "DNS1", "Group A" -Good: "Internal Corporate DNS", "AWS VPC Resolver" - -### 3. Always Have a Primary - -Every peer should receive at least one primary nameserver, or they'll use unmanaged DNS. - -### 4. Test in Stages - -1. Create nameserver -2. Assign to a test distribution group first -3. Verify DNS works on test peers -4. Roll out to all peers - -### 5. Document Your Domains - -Keep a list of which domains belong to which systems: - -``` -company.internal → On-premise Active Directory (includes all subdomains) -corp.company.internal → Corporate services (includes all subdomains) -ec2.internal → AWS VPC (includes all subdomains) -compute.internal → GCP (includes all subdomains) -``` - -### 6. Monitor and Maintain - -- Check that all nameserver IPs are reachable -- Update IP addresses if infrastructure changes -- Remove unused nameservers to keep configuration clean - ---- - -## Verifying Configuration - -After creating nameservers, verify they're working: - -### Check Peer Status - -1. Go to **Peers** in dashboard -2. Find a peer in your distribution group -3. Check DNS status indicator - -### Test from Peer - -On the peer device: - -```bash -# Check NetBird DNS is active -nslookup example.com 127.0.0.1 - -# Test internal domain resolution -nslookup internal.company.internal - -# Check search domains -ping server # Should expand to server.company.internal -``` - -See [Troubleshooting](/manage/dns/troubleshooting) for more diagnostic commands. - ---- - -## 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 - - -Need help? Check our [troubleshooting guide](/manage/dns/troubleshooting) or join the [NetBird Slack community](https://netbird.io/slack). - \ No newline at end of file +This content has been moved to the [Internal DNS Servers](/manage/dns/internal-dns-servers#configuring-nameservers-for-internal-domains) page, which covers nameserver creation, management, and working with internal DNS infrastructure. diff --git a/src/pages/manage/dns/private-dns-behind-routing-peers.mdx b/src/pages/manage/dns/private-dns-behind-routing-peers.mdx index a710daf6..9d490dba 100644 --- a/src/pages/manage/dns/private-dns-behind-routing-peers.mdx +++ b/src/pages/manage/dns/private-dns-behind-routing-peers.mdx @@ -1,72 +1,6 @@ -export const description = 'Quickstart guide for configuring private DNS servers behind routing peers' +export const description = 'Configure private DNS servers behind routing peers' import {Note} from "@/components/mdx" +# Private DNS Behind Routing Peers -# 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). - - -### 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)** - 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 +This content has been moved to the [Internal DNS Servers](/manage/dns/internal-dns-servers#configuring-nameservers-for-internal-domains) page, which provides comprehensive guidance on configuring NetBird with internal DNS infrastructure. diff --git a/src/pages/manage/dns/troubleshooting.mdx b/src/pages/manage/dns/troubleshooting.mdx index 56f339fc..aecce51a 100644 --- a/src/pages/manage/dns/troubleshooting.mdx +++ b/src/pages/manage/dns/troubleshooting.mdx @@ -835,6 +835,6 @@ Avoid future DNS issues: ## Related Documentation - **[DNS Overview](/manage/dns)** - Understand DNS architecture -- **[Configuring Nameservers](/manage/dns/nameserver-groups)** - Configuration guide +- **[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 diff --git a/src/pages/manage/networks/index.mdx b/src/pages/manage/networks/index.mdx index 43a64f41..816a1503 100644 --- a/src/pages/manage/networks/index.mdx +++ b/src/pages/manage/networks/index.mdx @@ -87,6 +87,10 @@ For troubleshooting, see [Debugging access to Domain Resources](/help/troublesho Firewall blocking DNS requests is the most common cause of domain resource issues. + + When a routing peer cannot resolve a domain resource (e.g., an internal domain like `fileserver.corp.local`), you may need to configure a [Nameserver](/manage/dns/internal-dns-servers#configuring-nameservers-for-internal-domains) for your internal DNS and add the routing peer's group as a distribution group. See [Internal DNS Servers](/manage/dns/internal-dns-servers#domain-resources-and-routing-peer-dns) for details. + + ## Manage Access to Resources To control access to resources, assign them to groups and create [access control policies](/manage/access-control/manage-network-access#creating-policies). A peer can only see a resource when a policy grants access from one of the peer's groups (source) to one of the resource's groups (destination). diff --git a/src/pages/use-cases/security/implement-zero-trust.mdx b/src/pages/use-cases/security/implement-zero-trust.mdx index 82be209e..0d7222d0 100644 --- a/src/pages/use-cases/security/implement-zero-trust.mdx +++ b/src/pages/use-cases/security/implement-zero-trust.mdx @@ -539,7 +539,7 @@ General rules: - Create a Network that includes: - IP ranges (for example `10.10.0.0/16` - the `/16` means the first 16 bits are the network portion, allowing 65,536 IP addresses) - DNS resources (for example `db.internal.example.com` for a specific hostname, or `*.corp.internal` for all subdomains) where appropriate -- Add a DNS server in NetBird with the right match domain (for example `corp.internal`) under [DNS → Nameservers](/manage/dns/nameserver-groups). +- Add a DNS server in NetBird with the right match domain (for example `corp.internal`) under [DNS → Nameservers](/manage/dns/internal-dns-servers#configuring-nameservers-for-internal-domains). - Add explicit policies allowing peers to reach the DNS servers themselves (UDP and TCP 53 to the resolver IPs).