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 with the internal domain name (e.g., fileserver.corp.local) and an access control policy 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.

A domain resource matches the exact name you enter: fileserver.corp.local covers that one host, not other names under corp.local. To reach many hostnames under a domain — several servers, or names you can't list in advance — use a wildcard resource such as *.corp.local, which matches every subdomain. A wildcard routes all of those names through the routing peer, so when you only need a handful of hosts, prefer listing them as specific resources.

Domain Resources and Routing Peer DNS

When you define a Network resource using a domain name (e.g., crm.corp.local), the routing peer resolves that domain using its own local DNS configuration. With Routing Peer DNS Resolution enabled (the default), the client sends its DNS queries for that domain to the routing peer, which looks up the domain and returns the result — so the client needs no nameserver of its own to resolve that name.

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 to the internal Nameserver's distribution groups — along with any client groups that resolve these names directly (Active Directory clients always do):

1. Go to DNS → Nameservers
2. Edit your internal DNS nameserver (or create one if it doesn't exist)
3. Under Domains, ensure your internal domains are listed (e.g., corp.local)
4. Add the routing peer's group — plus any client groups that resolve these names directly — to the Distribution Groups
5. Save

This ensures the routing peer receives the nameserver configuration and can resolve internal domains on behalf of clients.

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

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

5. Under Domains, add a Match Domain and enter your internal domains (e.g., corp.local, company.internal)

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.

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 Network Routing → 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.

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.

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.

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

Temporarily Disabling

Edit the nameserver and toggle Enable Nameserver to OFF. Peers stop using it but the configuration is preserved.

Deleting

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.

Reaching a Domain Controller through a routing peer

With Routing Peer DNS Resolution on (the default), a domain resource is enough for a plain file share — the routing peer resolves its name-to-IP (A/AAAA) lookup. Active Directory needs more:

• What it needs — a domain-joined client needs a nameserver (corp.example.com → the DC) for the SRV / DC-locator records that logon and DFS depend on. It only works once the DC itself is reachable through the peer.
• Why a domain resource isn't enough — the routing peer serves only A/AAAA, not SRV / DC-locator records. And once it's the client's resolver for the domain, the client stops asking anywhere else — it won't separately query the DC for the records it's missing. So a plain domain resource silently leaves out exactly the records AD login and DFS need.

This is the same on Windows and Linux clients.

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.

WireGuard Port Conflict on Domain Controllers

When NetBird is installed on a Windows Domain Controller, the Windows DNS Server service may already be using UDP port 51820 — WireGuard's default port. This causes NetBird to fail during startup.

Symptoms:

• NetBird fails with: Error: daemon up failed: call service up method: rpc error: code = DeadlineExceeded desc = context deadline exceeded
• The peer appears as disconnected in the NetBird management portal
• The WireGuard tunnel cannot establish a connection

Cause:

The Windows DNS Server service uses a dynamic socket pool that can bind to UDP port 51820 before WireGuard claims it. Since both services need exclusive use of the port, WireGuard fails to start.

Diagnosis:

1. Open an elevated Command Prompt or PowerShell on the Domain Controller and check what process is using port 51820:

netstat -ano | findstr 51820

2. Identify the process holding the port using the PID from the output:

tasklist /FI "PID eq <PID>"

If the process is dns.exe or svchost.exe (hosting the DNS Server service), this confirms the port conflict.

3. Optionally, capture a NetBird debug bundle for further investigation:

netbird debug for 1m -U

Fix:

Exclude port 51820 from the DNS Server's socket pool so it cannot claim the port:

dnscmd /config /SocketPoolExcludedPortRanges 51820-51820

Then restart the DNS Server service:

net stop dns && net start dns

Then restart the NetBird service:

netbird service restart