sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-20 09:26:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Restructure and improve DNS documentation (#504)

Browse Source 
* docs: Restructure and improve DNS documentation

Reorganizes DNS docs into overview, configuration, settings, and troubleshooting
guides with clearer explanations and UI-aligned terminology

* amendments from Vik's feedback

* clarified IP assignment range

* remove incorrect common mistake note

* - added diagrams
- renamed dns overview.mdx to index.mdx
- updated references/redirects
- created new spacer div class

---------

Co-authored-by: Ashley Mensah <ashley@netbird.io>
This commit is contained in:
shuuri-labs
2025-12-04 20:16:57 +01:00
committed by GitHub
parent c309000266
commit 4db6796ef9
14 changed files with 1660 additions and 2041 deletions
Download Patch File Download Diff File Expand all files Collapse all files

418
src/pages/manage/dns/index.mdx
View File

@@ -1,167 +1,277 @@
export const description = 'Understanding how DNS works in NetBird'
import {Note} from "@/components/mdx"
# Manage DNS in your network
<div className="videowrapper">
<iframe src="https://www.youtube.com/embed/xxQ_QeEMC0U" allow="fullscreen;"></iframe>
</div>
<br/><br/>
# DNS in NetBird
With NetBird, you don't need to worry about designing your private network or configuring [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol)
as it is automatically done in a single place - the NetBird Management service.
NetBird assigns and automatically distributes IP addresses to your peers.
Once your peers have their IP addresses, they can communicate with each other, establish direct encrypted WireGuard® tunnels,
and access services running on connected peers, such as SSH.
Even though we trust our memory capacity, there is a limit to what we can remember,
especially when it comes to IP addresses like this one, 100.128.185.34.
NetBird provides intelligent DNS management to help your peers resolve domain names within your private network and control how they access external domains.
Starting [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird automatically assigns a domain name
to each peer in a private `netbird.cloud` space that can be used to access the machines. E.g., `my-server.netbird.cloud`.
## DNS Fundamentals
Besides accessing machines by their domain names, you can configure NetBird to use your private nameservers,
control what nameservers a specific [peer group](/manage/access-control/manage-network-access#groups) should use, and set up split DNS.
Before diving into NetBird's DNS features, let's cover the basics you'll need to understand.
<Note>
Nameservers feature is available in NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later on both
cloud and self-hosted versions.
</Note>
### What is DNS?
## Core concepts
### Local resolver
To minimize system changes, NetBird runs a local embedded DNS resolver on each peer.
This resolver handles queries for domain names of registered peers in your network and forwards queries to upstream nameservers that you configure in the system.
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.
<Note>
DNS Forwarder port change: starting with NetBird v0.59.0, the local DNS forwarder used for routed DNS routes switches from port <code>5353</code> to <code>22054</code> to avoid collisions on client devices. For backward compatibility, the Management Service applies the new port only when <strong>all peers in the account</strong> run v0.59.0 or newer. If any peer is below v0.59.0, port <code>5353</code> will be used for all peers in that account.
</Note>
### DNS Resolution Flow
### Nameserver
A nameserver is an upstream DNS server responsible for name resolution. If a query is not related to a peer domain name,
it will be resolved by one of the upstream servers. You can assign private and public IPs, as well as custom ports for your nameservers.
Ensure that network routes for private addresses are set up to allow peers to connect to them, when configuring private nameservers.
Here's what happens when a device looks up a domain:
### Match domains
When creating nameserver groups without match domains, it implies that the nameservers will resolve all DNS queries.
For specific cases, you may want to deploy a split horizon configuration for private or specific domains.
Match domains allow you to route queries to specific nameservers, which is useful for internal DNS configurations
that only internal servers can resolve.
<Note>
Only macOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with match domains.
For a better experience, we recommend setting at least one nameserver group without match domains to be applied to the `All` group.
</Note>
#### Mark match domains as search domains
Marking a match domain as a search domain configures peers to use only hostnames to perform FQDN queries, e.g., `ping host-a` instead of `ping host-a.netbird.cloud`.
<Note>
Marking a match domains as a search domain feature is available in NetBird [v0.24.0](https://github.com/netbirdio/netbird/releases) or later.
</Note>
### Distribution groups
Distribution groups define which peers will receive the nameserver configuration.
They are particularly useful when using private nameservers to link routing peers and clients of the private servers.
<Note>
When using private nameservers, you may use these groups to link routing peers and clients of the private servers.
</Note>
## Managing nameserver groups
A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers in the distribution groups.
### Creating a nameserver group
Access the `DNS` tab, the `Nameservers` section and click `Add Nameserver`.
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-add-button.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
That will open a nameserver selection configuration screen where you can choose between using three predefined public
nameservers or using a custom setup.
### Selecting predefined nameservers
If you choose a predefined public nameserver option, you can select the following nameservers:
- [Google DNS servers](https://developers.google.com/speed/public-dns/docs/using)
- [Cloudflare DNS servers](https://one.one.one.one/dns/)
- [Quad9 DNS servers](https://www.quad9.net/)
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-selection-view-open.png" alt="high-level-dia" className="imagewrapper"/>
</p>
After selecting one of the three options, you need to assign a peer group for which this nameserver will be effective.
In the example below, we chose the `All` group:
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-all-group.png" alt="high-level-dia" className="imagewrapper"/>
</p>
### Creating custom nameservers
You can also configure a custom nameserver by clicking `Add custom`. Now you can enter the details of your custom nameserver.
In the example below, we are creating a nameserver with the following information:
- Name: `Office resolver`
- Description: `Berlin office resolver`
- Add at least one nameserver: `192.168.0.32` with port `53`
- Distribution group: `Remote developers`
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-custom.png" alt="high-level-dia" className="imagewrapper"/>
</p>
### Creating a nameserver for specific domains
Sometimes one may want to forward DNS queries to specific nameservers but only for particular domains that match a setting.
Taking the example of custom nameservers above, you could select a match mode for only domains listed there.
Below you can see the same nameserver setup but only for the `berlinoffice.com` domain:
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-remote-resolver.png" alt="high-level-dia" className="imagewrapper"/>
</p>
<Note>
Only macOS, Windows 10+, and Linux running `systemd-resolved` support nameservers with only match domains. For a better experience, we recommend setting at least a nameserver group without match domains to be applied to the `All` group.
</Note>
### Distributing DNS settings with groups
You can select as many distribution groups as you want for your nameserver setup.
Keep in mind to link them to peers and, if required, to add access control rules when using private nameservers.
### Adding remote private DNS servers
To add a private DNS server that is running behind routing peers, you need to create resources to ensure communication between your nameserver clients.
In the Berlin office example from previous steps, we have a peer from the `Office network` that can route traffic to the `192.168.0.32` IP,
so we need to ensure that a similar network route exists:
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-remote-route.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group allowing port `UDP 53`:
<p>
<img src="/docs-static/img/manage/dns/netbird-nameserver-remote-rule.png" alt="high-level-dia" className="imagewrapper-big"/>
</p>
## Testing configuration
### Querying records
DNS configuration has evolved in the past few years, and each operating system might expose its nameserver configuration differently.
Unfortunately, tools like `nslookup` or `dig` didn't get updated to match these OS configurations, and in many cases,
they won't use the same servers as your browser to query domain names.
For these cases, we listed some tools to support your checks:
#### macOS
You can use `dscacheutil`:
```shell
dscacheutil -q host -a name peer-a.netbird.cloud
```
#### Windows
You can use `Resolve-DnsName` on `Powershell`:
```shell
Resolve-DnsName -Name peer-a.netbird.cloud
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
```
#### Linux
In most cases, you will be fine with traditional tools because most DNS managers on Linux tend to update the /etc/resolv.conf.
```shell
dig peer-a.netbird.cloud
# or
nslookup peer-a.netbird.cloud
```
If your system is running systemd-resolved, you can also use ```resolvectl```:
```shell
resolvectl query peer-a.netbird.cloud
```
## Get started
<p float="center" >
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Use NetBird</Button>
</p>
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
- Follow us [on X](https://x.com/netbird)
- Join our [Slack Channel](/slack-url)
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
### 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`).
</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
- **Mobile**: Uses VPN DNS configuration
<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
### 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](/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