From fe2f159f74184f605879ae9b62828e30b91feda6 Mon Sep 17 00:00:00 2001
From: shuuri-labs <61762328+shuuri-labs@users.noreply.github.com>
Date: Fri, 19 Dec 2025 10:20:58 +0100
Subject: [PATCH]  Remove wildcard syntax (*.domain.com) from match domain
 examples as (#524)

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>
---
 src/pages/ipa/resources/dns.mdx            | 380 +++++++++++++++++++++
 src/pages/manage/dns/index.mdx             |  29 +-
 src/pages/manage/dns/nameserver-groups.mdx |  33 +-
 src/pages/manage/dns/troubleshooting.mdx   |   9 +
 4 files changed, 420 insertions(+), 31 deletions(-)
 create mode 100644 src/pages/ipa/resources/dns.mdx

diff --git a/src/pages/ipa/resources/dns.mdx b/src/pages/ipa/resources/dns.mdx
new file mode 100644
index 00000000..e2548a37
--- /dev/null
+++ b/src/pages/ipa/resources/dns.mdx
@@ -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>
\ No newline at end of file
diff --git a/src/pages/manage/dns/index.mdx b/src/pages/manage/dns/index.mdx
index 3b8710c5..09148be1 100644
--- a/src/pages/manage/dns/index.mdx
+++ b/src/pages/manage/dns/index.mdx
@@ -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
 
diff --git a/src/pages/manage/dns/nameserver-groups.mdx b/src/pages/manage/dns/nameserver-groups.mdx
index 73ac7f1e..62679f19 100644
--- a/src/pages/manage/dns/nameserver-groups.mdx
+++ b/src/pages/manage/dns/nameserver-groups.mdx
@@ -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
diff --git a/src/pages/manage/dns/troubleshooting.mdx b/src/pages/manage/dns/troubleshooting.mdx
index 465d860a..168a47e3 100644
--- a/src/pages/manage/dns/troubleshooting.mdx
+++ b/src/pages/manage/dns/troubleshooting.mdx
@@ -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.