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

Remove wildcard syntax (*.domain.com) from match domain examples as (#524)

Browse Source 
the UI does not support wildcards - adding a domain automatically
  matches all subdomains
- Add note about disabling Android Private DNS for custom DNS resolution
- Re-add DNS API documentation

Co-authored-by: Ashley Mensah <ashley@netbird.io>
This commit is contained in:
shuuri-labs
2025-12-19 10:20:58 +01:00
committed by GitHub
parent a9dfece4db
commit fe2f159f74
4 changed files with 420 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
src/pages/ipa/resources/dns.mdx Normal file
View File

@@ -0,0 +1,380 @@
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>

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

@@ -42,7 +42,7 @@ Here's what happens when a device looks up a domain:
</Property>
<Property name="Match Domains">
Specific domains that should be resolved by a particular nameserver (e.g., `*.company.internal`).
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">
@@ -93,7 +93,12 @@ 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
- **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.
@@ -119,8 +124,8 @@ NetBird does **not** cache most DNS queries. Caching only occurs in specific cas
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)
- **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:
@@ -129,14 +134,14 @@ 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
→ 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
→ 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
→ Matches company.internal → Internal DNS → Returns private IP
```
#### 4. **DNS Management Modes**
@@ -239,11 +244,11 @@ When you assign a nameserver to distribution groups:
### 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.
**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
- **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
@@ -251,9 +256,9 @@ When you assign a nameserver to distribution groups:
**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
- **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

33
src/pages/manage/dns/nameserver-groups.mdx
View File

@@ -125,20 +125,17 @@ 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
- Domain match: `company.internal` (automatically matches the domain and all its subdomains like `app.company.internal`)
- Multiple domains 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.
Adding a domain like `company.internal` automatically matches both the domain itself and all subdomains (e.g., `app.company.internal`, `server.company.internal`). Wildcard syntax (`*.domain.com`) is not supported in the UI.
</Note>
#### Search Domains
@@ -179,7 +176,7 @@ Once nameserver IPs and distribution groups are configured, navigate to the **Na
### Scenario 1: Simple Internal DNS
**Goal**: Use Cloudflare for internet, internal DNS for `*.company.internal`
**Goal**: Use Cloudflare for internet, internal DNS for `company.internal` and all its subdomains
**Configuration**:
@@ -210,7 +207,7 @@ Once nameserver IPs and distribution groups are configured, navigate to the **Na
],
"enabled": true,
"primary": false,
"domains": ["company.internal", "*.company.internal"],
"domains": ["company.internal"],
"search_domains_enabled": true,
"groups": ["All Peers"]
}
@@ -249,7 +246,6 @@ Once nameserver IPs and distribution groups are configured, navigate to the **Na
"primary": false,
"domains": [
"ec2.internal",
"*.ec2.internal",
"compute.internal"
],
"nameservers": [
@@ -264,7 +260,7 @@ Once nameserver IPs and distribution groups are configured, navigate to the **Na
"name": "GCP Internal DNS",
"primary": false,
"domains": [
"*.internal.gcp.company.com"
"internal.gcp.company.com"
],
"nameservers": [
{"ip": "169.254.169.254", "ns_type": "udp", "port": 53}
@@ -278,8 +274,7 @@ Once nameserver IPs and distribution groups are configured, navigate to the **Na
"name": "Corporate DNS",
"primary": false,
"domains": [
"corp.company.com",
"*.corp.company.com"
"corp.company.com"
],
"nameservers": [
{"ip": "10.1.0.1", "ns_type": "udp", "port": 53},
@@ -330,7 +325,7 @@ You can use services like:
1. **For Developers**:
- Primary: Public DNS (all domains)
- Match: Internal DNS (*.company.internal)
- Match: Internal DNS (company.internal)
- Assigned to: "Developers" group
2. **For Guests**:
@@ -366,8 +361,8 @@ 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
1. company.internal → DNS1
2. us-east.company.internal → DNS2
Result: Uses DNS2 (more specific)
```
@@ -450,10 +445,10 @@ Every peer should receive at least one primary nameserver, or they'll use unmana
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
company.internal → On-premise Active Directory (includes all subdomains)
corp.company.internal → Corporate services (includes all subdomains)
ec2.internal → AWS VPC (includes all subdomains)
compute.internal → GCP (includes all subdomains)
```
### 6. Monitor and Maintain

9
src/pages/manage/dns/troubleshooting.mdx
View File

@@ -88,6 +88,15 @@ sudo netbird down && sudo netbird up
Restart-Service netbird
```
**Android**:
If DNS resolution isn't working on Android, check your **Private DNS** setting:
1. Go to **Settings → Network & Internet → Private DNS**
2. 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, preventing NetBird's custom DNS resolution from working.
#### Solution B: Wrong Nameserver Configuration
NetBird is routing queries to the wrong DNS server.