sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-16 07:26:35 +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

5
src/components/NavigationDocs.jsx
View File

@@ -159,7 +159,10 @@ export const docsNavigation = [
title: 'DNS',
isOpen: false,
links: [
{ title: 'Manage DNS in Your Network', href: '/manage/dns' },
{ title: 'Overview', href: '/manage/dns' },
{ title: 'Configuring Nameservers', href: '/manage/dns/nameserver-groups' },
{ title: 'DNS Settings', href: '/manage/dns/dns-settings' },
{ title: 'DNS Troubleshooting', href: '/manage/dns/troubleshooting' },
]
},
{

1878
src/pages/ipa/resources/dns.mdx
View File

File diff suppressed because it is too large Load Diff

381
src/pages/manage/dns/dns-settings.mdx Normal file
View File

@@ -0,0 +1,381 @@
export const description = 'Control DNS management behavior for peer groups'
# 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.
## Understanding 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.
### Unmanaged Mode
When a peer's group **is** in the disabled management list:
- ✅ 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**:
- Peer has conflicting VPN or DNS requirements
- Corporate policy requires specific DNS settings
- Testing or troubleshooting DNS issues
- Peer is in a restricted environment
### Client-Side DNS Control
You can also disable DNS management directly on a peer using the `--disable-dns` flag:
```bash
# Disable DNS management on this peer
netbird up --disable-dns
# Enable DNS management on this peer
netbird up --disable-dns=true
```
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
<Note>
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.
</Note>
## 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:
<img src="/docs-static/img/manage/dns/netbird-dns-settings.png" alt="DNS settings" className="imagewrapper-big"/>
### 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'.
<Note>
Changes take effect within 10-30 seconds. Peers in disabled groups will revert to their original DNS settings.
</Note>
### 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'.
The peer will start using configured nameserver groups again.
---
## 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
---
## 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
<Note>
Even in unmanaged mode, peers can still communicate over the NetBird network. DNS management only affects name resolution, not connectivity.
</Note>
---
## API Configuration
You can manage DNS settings programmatically:
### Get Current Settings
```bash
curl -X GET https://api.netbird.io/api/dns/settings \
-H "Authorization: Token <TOKEN>"
```
### Update Settings
```bash
curl -X PUT https://api.netbird.io/api/dns/settings \
-H "Authorization: Token <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"disabled_management_groups": [
"ch8i4ug6lnn4g9hqv7m0",
"ch8i4ug6lnn4g9hqv7m1"
]
}'
```
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
---
## 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
<Note>
Questions about DNS settings? Check the [troubleshooting guide](/manage/dns/troubleshooting) or ask in the [NetBird community](https://netbird.io/slack).
</Note>

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

549
src/pages/manage/dns/nameserver-groups.mdx Normal file
View File

@@ -0,0 +1,549 @@
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.
<Note>
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.
</Note>
## 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
<Note>
The Domains and Name & Description tabs remain disabled until you configure at least one nameserver IP and one distribution group in the Nameserver tab.
</Note>
### 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
<img src="/docs-static/img/manage/dns/netbird-nameserver-add-button.png" alt="Add nameserver IPs" className="imagewrapper-big"/>
<img src="/docs-static/img/manage/dns/netbird-nameserver-choose-type.png" alt="Choose nameserver provider" className="imagewrapper-big"/>
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.
<Note>
**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.
</Note>
#### Add Nameserver IPs
Add a nameserver IP (or multiple IPs for redundancy):
<img src="/docs-static/img/manage/dns/netbird-nameserver-custom.png" alt="Custom DNS provider" className="imagewrapper-big"/>
<Properties>
<Property name="IP" type="string" required>
IP address of the DNS server (e.g., `10.0.0.1` or `1.1.1.1`)
</Property>
<Property name="Port" type="integer" required>
DNS port, typically `53`
</Property>
</Properties>
Example configuration:
```json
{
"nameservers": [
{"ip": "1.1.1.1", "port": 53},
{"ip": "1.0.0.1", "port": 53}
]
}
```
<Note>
**Best practice**: Configure 2-3 nameservers for redundancy. If the first fails, peers automatically try the next one.
</Note>
#### Assign Distribution Groups
Select which peer groups will use this nameserver.
<Properties>
<Property name="Distribution Groups" type="string[]" required>
At least one peer group must be selected. All peers in these groups will receive this DNS configuration.
</Property>
</Properties>
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.
<img src="/docs-static/img/manage/dns/netbird-nameserver-add-domain.png" alt="Choose nameserver provider" className="imagewrapper-big"/>
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.
<Note>
**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
</Note>
#### 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**:
- Exact match: `company.internal`
- Wildcard subdomain: `*.company.internal` (matches `app.company.internal` but NOT `company.internal` itself)
- Multiple patterns per nameserver
**Example for internal DNS**:
```
company.internal
*.company.internal
internal.example.com
*.internal.example.com
```
<Note>
**Tip**: Include both `domain.internal` and `*.domain.internal` to match the apex domain and all subdomains.
</Note>
#### 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.
<img src="/docs-static/img/manage/dns/netbird-nameserver-name-and-desc.png" alt="Choose nameserver provider" className="imagewrapper-big"/>
<Properties>
<Property name="DNS Name" type="string" required>
A descriptive name for this nameserver (e.g., "Cloudflare DNS" or "Internal DNS")
</Property>
<Property name="Description" type="string" optional>
Optional notes about this nameserver's purpose (e.g., "Cloudflare DNS Servers" or "Berlin office resolver for remote developers")
</Property>
</Properties>
### 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`
**Configuration**:
<CodeGroup title="Nameservers">
```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", "*.company.internal"],
"search_domains_enabled": true,
"groups": ["All Peers"]
}
```
</CodeGroup>
**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**:
<CodeGroup title="Nameservers">
```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",
"*.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",
"*.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"]
}
```
</CodeGroup>
---
### 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"]
}
```
<Note>
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
</Note>
---
### 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).
1. Go to **DNS Settings** (not Nameservers)
2. Add groups to **Disabled Management Groups**
3. Peers in these groups will ignore all NetBird DNS configuration
See [DNS Settings](/manage/dns/dns-settings) for details.
---
## Updating Nameservers
### Editing an Existing Nameserver
1. Navigate to **DNS** → **Nameservers**
2. Click the group to edit
3. Modify settings
4. Click **Save**
<Note>
Changes propagate to peers within 10-30 seconds. No peer restart required.
</Note>
### 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
<Note>
**Before deleting a primary nameserver**: Create a new primary first, or peers will revert to their original DNS settings.
</Note>
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
*.corp.company.internal → Corporate services
*.ec2.internal → AWS VPC
*.compute.internal → GCP
```
### 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.
---
## Advanced: 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
- **Client peers**: Need to query this DNS through the routing peer
### Setup Requirements
#### 1. Configure the Nameserver
Create a nameserver pointing to your private DNS:
- IP: `192.168.0.32`
- Port: `53`
- Distribution groups: Your client peer groups (e.g., "Remote Developers")
#### 2. Create a Network Route
Set up a network route so clients can reach the DNS server:
- Network: `192.168.0.0/24`
- Routing peer: The peer that can access this network
- Distribution groups: Same as your nameserver (e.g., "Remote Developers")
#### 3. Configure Access Control
Create an access control rule allowing DNS traffic:
- Source: Client groups (e.g., "Remote Developers")
- Destination: Routing peer's group
- Protocol: UDP
- Port: 53
### DNS Forwarder Port
<Note>
**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.
</Note>
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
- **[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
<Note>
Need help? Check our [troubleshooting guide](/manage/dns/troubleshooting) or join the [NetBird Slack community](https://netbird.io/slack).
</Note>

455
src/pages/manage/dns/troubleshooting.mdx Normal file
View File

@@ -0,0 +1,455 @@
export const description = 'Diagnose and fix common DNS issues in NetBird'
# DNS Troubleshooting
This guide helps you diagnose and resolve common DNS issues in NetBird. Follow the structured approach below to identify and fix problems quickly.
## Quick Diagnostics Checklist
Before diving deep, run through this quick checklist:
```bash
# 1. Is NetBird connected?
netbird status
# 2. Is DNS the peer being passed the correct nameservers?
netbird status | grep Nameserver
# 3. Can you resolve public domains?
nslookup google.com
# 4. Can you resolve internal domains?
nslookup internal.company.internal
# 5. What DNS server is being used?
cat /etc/resolv.conf # Linux/macOS
# or
Get-DnsClientServerAddress # Windows
```
If any of these fail, continue to the relevant section below.
<Note>
**Quick isolation test**: To check if an issue is caused by NetBird DNS, temporarily disable DNS management on the peer:
```bash
netbird down
netbird up --disable-dns
```
If the problem goes away, the issue is in your NetBird DNS configuration. If it persists, it's unrelated to NetBird DNS.
</Note>
## Common Issues and Solutions
### Issue 1: Can't Resolve Internal Domains
**Symptoms**:
- `nslookup internal.company.internal` fails
- `ping server.company.internal` returns "unknown host"
- Public domains work fine
**Solutions**:
#### Solution A: System Not Using NetBird DNS
The OS isn't configured to use NetBird's resolver.
**Linux/macOS**:
```bash
# Check resolv.conf
cat /etc/resolv.conf
# Should contain:
# nameserver 100.x.255.254 (where x is from your NetBird /16 block)
# If not, restart NetBird
sudo systemctl restart netbird
# or
sudo netbird down && sudo netbird up
```
**Windows**:
```powershell
# Check DNS settings
Get-DnsClientServerAddress -InterfaceAlias "NetBird"
# Should show: 100.x.255.254 (where x is from your NetBird /16 block)
# If not, restart NetBird service
Restart-Service netbird
```
#### Solution B: Wrong Nameserver Configuration
NetBird is routing queries to the wrong DNS server.
1. **Go to Dashboard → DNS → Nameservers**
2. **Check match domains**:
- Does your domain pattern match?
- `company.internal` won't match `*.company.internal` (need both)
3. **Check nameserver IPs**:
- Are they correct?
- Are they reachable from peers?
4. **Check distribution groups**:
- Is the peer's group assigned to this nameserver?
**Common mistakes**:
```json
// ❌ Wrong: Wildcard only
{
"domains": ["*.company.internal"]
}
// Doesn't match "company.internal" (no subdomain)
// ✅ Correct: Both patterns
{
"domains": ["company.internal", "*.company.internal"]
}
```
#### Solution C: Nameserver Unreachable
The configured nameserver can't be reached.
**Test connectivity**:
```bash
# Can peer reach the nameserver?
ping 10.0.0.1 # Replace with your nameserver IP
# Test DNS query directly
dig @10.0.0.1 internal.company.internal
# If this times out:
# → Firewall or routing issue
# → Check NetBird routes
# → Check firewall rules on DNS server
```
### Issue 2: Public Domains Not Resolving
**Symptoms**:
- Can't resolve `google.com`, `github.com`, etc.
- Internal domains may work
- "DNS resolution failed" errors
**Diagnosis**:
```bash
# Test public DNS
nslookup google.com
nslookup google.com <NetBird local resolver IP>
nslookup google.com 8.8.8.8
# If direct to 8.8.8.8 works but others fail, it's likely a NetBird resolver issue
# If all fail, it's likely a Network connectivity issue
```
**Solutions**:
#### Solution A: No Primary Nameserver Configured
**Check**:
1. Go to **DNS → Nameservers**
2. Look for a nameserver with empty match domains (this is the primary)
3. Verify it's assigned to your peer's distribution groups
**Fix**: Create a primary nameserver:
```json
{
"name": "Public DNS",
"primary": true,
"domains": [], // don't configure any match domains!
"nameservers": [
{"ip": "1.1.1.1", "ns_type": "udp", "port": 53},
{"ip": "8.8.8.8", "ns_type": "udp", "port": 53}
],
"groups": ["All Peers"]
}
```
#### Solution B: Primary Nameserver Unreachable
Your primary DNS server is down or unreachable.
**Test**:
```bash
# Test primary nameserver directly
dig @1.1.1.1 google.com
# If timeout, it's likely Network issue or firewall block
```
**Fix**:
1. Add backup nameservers to the primary group
2. Or switch to a different primary DNS:
```json
{
"nameservers": [
{"ip": "1.1.1.1", "ns_type": "udp", "port": 53},
{"ip": "1.0.0.1", "ns_type": "udp", "port": 53},
{"ip": "8.8.8.8", "ns_type": "udp", "port": 53}
]
}
```
#### Solution C: DNS Management Disabled
The peer's group has DNS management disabled.
**Check**:
1. Go to **DNS → DNS Settings**
2. Look for peer's group in `disabled_management_groups`
**Fix**: Remove from disabled list or expected behavior.
### Issue 3: Intermittent DNS Failures
**Symptoms**:
- DNS works sometimes but not always
- Queries timeout randomly
- Slow DNS resolution
**Diagnosis**:
```bash
# Test multiple times
for i in {1..10}; do
echo "Test $i:"
time nslookup internal.company.internal
sleep 1
done
# Look for:
# - Timeouts
# - Slow responses (>1 second)
# - Inconsistent results
```
**Solutions**:
#### Solution A: Nameserver Performance Issues
**Test nameserver directly**:
```bash
# Time direct queries to each nameserver
time dig @10.0.0.1 internal.company.internal
time dig @10.0.0.2 internal.company.internal
# If slow or timeout:
# → Nameserver is overloaded or having issues
```
**Fix**:
1. Add more nameservers for load balancing
2. Check nameserver health
3. Consider caching DNS server closer to peers
#### Solution B: Network Instability
**Check NetBird connectivity**:
```bash
netbird status
# Should show: Status: Connected
# If shows disconnected/reconnecting:
# → Underlying network issues
```
**Fix**:
- Check physical network connection
- Verify firewall rules
- Review NetBird logs: `netbird up --log-level debug`
#### Solution C: DNS Cache Issues
**Clear DNS cache**:
**Linux**:
```bash
# systemd-resolved
sudo systemd-resolve --flush-caches
# nscd
sudo systemctl restart nscd
```
**macOS**:
```bash
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
```
**Windows**:
```powershell
ipconfig /flushdns
```
**NetBird**:
```bash
# Restart NetBird to clear its cache
netbird down && netbird up
```
### Issue 4: Search Domains Not Working
**Symptoms**:
- `ping server` doesn't work
- `ping server.company.internal` does work
- Short names aren't expanded
**Diagnosis**:
```bash
# Check search domains
cat /etc/resolv.conf
# Should contain:
# search company.internal
# Or on Windows:
Get-DnsClientGlobalSetting | Select-Object SuffixSearchList
```
**Solutions**:
#### Solution A: Search Domains Not Enabled
**Check configuration**:
1. Go to **DNS → Nameservers**
2. Find your internal domain nameserver
3. Check **Mark match domains as search domains** is enabled
**Fix**:
```json
{
"domains": ["company.internal", "*.company.internal"],
"search_domains_enabled": true // Must be true!
}
```
<Note>
Search domains only work for match domain groups, not primary groups.
</Note>
#### Solution B: Multiple Search Domains Conflict
If you have multiple nameservers with search domains enabled, they may conflict.
**Check**:
```bash
cat /etc/resolv.conf
# If you see many search entries:
# search domain1.internal domain2.internal domain3.internal domain4.internal
# → OS may truncate or ignore some
```
**Fix**: Limit to 3-4 most important search domains.
### Issue 5: DNS Works on NetBird Network, Fails Outside
**Symptoms**:
- DNS works when connected to NetBird
- DNS fails when NetBird disconnects
- Computer can't resolve anything after using NetBird
**Diagnosis**:
```bash
# Disconnect NetBird
netbird down
# Check DNS
cat /etc/resolv.conf
# If still shows 100.x.255.254, NetBird didn't restore original DNS
```
**Solutions**:
#### Solution A: Manual DNS Restoration
**Linux/macOS**:
```bash
# Remove NetBird DNS manually
sudo rm /etc/resolv.conf
sudo ln -s /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
# or create new resolv.conf:
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
```
**Windows**:
```powershell
# Reset to automatic DNS
Set-DnsClientServerAddress -InterfaceAlias "Ethernet" -ResetServerAddresses
```
#### Solution B: Clean Reinstall
If DNS keeps breaking:
```bash
# Completely remove NetBird
sudo netbird down
sudo systemctl stop netbird
sudo systemctl disable netbird
# Restore DNS manually (see above)
# Reinstall NetBird
curl -sSL https://pkgs.netbird.io/install.sh | sh
```
### Issue 6: DNS Rebinding Protection
**Symptoms**:
- Router blocks internal DNS queries
- "DNS rebinding attack detected" in router logs
- Inconsistent resolution
**Diagnosis**:
This happens when using NetBird DNS with routers that have DNS rebinding protection (pfSense, OpenWRT, etc.).
**Solutions**:
#### Solution A: Whitelist Domains
In your router's DNS settings, whitelist your internal domains:
**pfSense**:
1. Services → DNS Resolver
2. Add to "Domain Overrides" or whitelist
**OpenWRT**:
```bash
# Add to /etc/config/dhcp
config domain
option name 'company.internal'
option ip '10.0.0.1'
```
---
## Prevention Checklist
Avoid future DNS issues:
- ✅ Always configure at least one primary nameserver
- ✅ Use 2-3 nameservers for redundancy
- ✅ Test configuration on one peer before rolling out
- ✅ Document your DNS architecture
- ✅ Monitor DNS resolution performance
- ✅ Keep NetBird client updated
- ✅ Include both `domain.internal` and `*.domain.internal` patterns
- ✅ Verify nameservers are reachable before configuring
- ✅ Use fast, reliable public DNS for primary (Cloudflare, Google)
- ✅ Set `search_domains_enabled: true` for internal domains
---
## Related Documentation
- **[DNS Overview](/manage/dns)** - Understand DNS architecture
- **[Configuring Nameservers](/manage/dns/nameserver-groups)** - Configuration guide
- **[DNS Settings](/manage/dns/dns-settings)** - Management modes
- **[API Reference](/ipa/resources/dns)** - Automate DNS

4
src/styles/tailwind.css
View File

@@ -114,6 +114,10 @@
border: 0;
}
.spacer-sm {
height: 5px;
}
.Toastify__close-button {
color: var(--toastify-text-color-light) !important;
}