sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-10-19 03:59:05 +02: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
co-authored by Ashley Mensah
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
src/pages/manage/dns/index.mdx
+17 -12
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
src/pages/manage/dns/nameserver-groups.mdx
+14 -19
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
src/pages/manage/dns/troubleshooting.mdx
+9
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.