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.

DNS Fundamentals

Before diving into NetBird's DNS features, let's cover the basics you'll need to understand.

What is DNS?

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

NetBird Automatic Domain Names

Starting with v0.11.0, 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.

How NetBird Handles DNS

NetBird gives you centralized control over DNS resolution for all peers in your network, solving common challenges with split-horizon DNS, private networks, and secure name resolution.

Architecture Overview

NetBird's DHCP Role

The NetBird management service acts as a DHCP server only for the NetBird network, not your LAN:

• NetBird IPs: Management assigns each peer a unique IP from one of 64 possible /16 blocks within the 100.64.0.0/10 CGNAT range (e.g., 100.64.0.0/16 through 100.127.0.0/16). The block is randomly selected per account and can be customized.
• 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.

Client-Side: How Peers Resolve DNS

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
• Mobile: Uses VPN DNS configuration

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:

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

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:

Query: "google.com"
→ No match → Primary (1.1.1.1) → Returns public IP

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 supports two modes per peer group:

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:

Linux (always sets up DNS):

• NetBird always configures DNS so peer domain names (like my-server.netbird.cloud) work
• Your original nameservers are preserved as upstream
• Both NetBird peer domains and regular DNS continue to work

macOS/Windows/Mobile (only when nameservers configured):

• Without nameservers configured, NetBird doesn't modify DNS
• Peer domain names like my-server.netbird.cloud won't resolve
• You can still use NetBird IPs directly (e.g., 100.121.5.10)

When you add custom nameservers:

• The local DNS resolver routes queries based on your match domain rules
• Custom nameservers can handle specific domains (split-horizon DNS)
• Primary nameservers handle all non-matched queries

Management-Side: How Configuration Works

Nameservers

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

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.

Configuration Rules

Distribution Logic

When you assign a nameserver to distribution groups:

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

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

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)

What's Next?

Now that you understand how NetBird handles DNS:

• Configure Nameservers - Step-by-step setup guide
• DNS Settings - Control DNS management per group
• Troubleshooting - Solve common DNS issues
• API Reference - Automate DNS configuration