netbird-docs/src/pages/manage/dns/index.mdx

export const description = 'Understanding how DNS works in NetBird'
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.

## 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

<Properties>
  <Property name="Nameserver">
    A server that answers DNS queries. NetBird lets you configure which nameservers your peers use.
  </Property>
  
  <Property name="DNS Resolver">
    The component that performs DNS lookups. NetBird runs a local DNS resolver on each peer.
  </Property>
  
  <Property name="Match Domains">
    Specific domains that should be resolved by a particular nameserver (e.g., `company.internal`). Adding a domain automatically matches all its subdomains.
  </Property>
  
  <Property name="Primary Nameserver">
    The default nameserver that handles all domains not matched by specific rules. In the UI, this is configured by leaving the match domains empty.
  </Property>
  
  <Property name="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 NetBird v0.24.0 or later.
  </Property>
</Properties>

### 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`.

<Note>
This feature is available on both NetBird Cloud and self-hosted versions running v0.11.0 or later.
</Note>

## 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

<div className="spacer-sm" />

<img src="/docs-static/img/manage/dns/netbird-dns-diagram.png" alt="NetBird DNS Diagram" className="imagewrapper-big"/>

#### 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
- **Android**: Uses VPN DNS configuration
- **iOS**: Uses VPN DNS configuration

<Note>
**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.
</Note>

<Note>
**Linux behavior**: Even without custom nameservers configured in the dashboard, NetBird sets up DNS. Your original upstream nameservers are preserved.
</Note>

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

<Note>
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).
</Note>

#### 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:

<Properties>
  <Property name="Managed Mode (Default)">
    NetBird fully controls DNS settings. All queries go through NetBird's resolver.
    
    **Use when**: You want centralized DNS control
  </Property>
  
  <Property name="Unmanaged Mode">
    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
  </Property>
</Properties>

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`)

<Note>
You don't need to configure custom nameservers to use NetBird. On Linux, peer domains work automatically. On other platforms, you can use NetBird IPs directly or configure nameservers for domain resolution.
</Note>

**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

<Note>
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.
</Note>

**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

<Properties>
  <Property name="Primary Nameserver">
    - 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
  </Property>
  
  <Property name="Match Domain Nameserver">
    - Specify one or more match domains
    - Only handles queries matching those domains
    - You can have multiple match domain nameservers
    - More specific patterns take precedence
  </Property>
</Properties>

<Note>
**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.
</Note>

#### 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 (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)

---

## 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
- **[DNS Settings](/manage/dns/dns-settings)** - Control DNS management per group
- **[Troubleshooting](/manage/dns/troubleshooting)** - Solve common DNS issues
- **[API Reference](/ipa/resources/dns)** - Automate DNS configuration