docs: explain macOS DNS resolver behavior for match-only vs primary nameservers - #912
docs: explain macOS DNS resolver behavior for match-only vs primary nameservers#912SunsetDrifter wants to merge 5 commits into
Conversation
…y vs primary nameserver split Lab-validated against client 0.76.3 (macOS 26, NetBird Cloud): - DNS troubleshooting: new Issue 5 'dig and host fail, but browsers and curl work (macOS)' with the scoped-resolver vs resolv.conf explanation, the language-runtime split table (pure-Go/dnspython/c-ares vs getaddrinfo), and the Windows nslookup-vs-NRPT analog; renumbered Issues 5-8 to 6-9; checklist step 6 now says why it prescribes dscacheutil/Resolve-DnsName - Internal DNS Servers: primary-vs-match now explains that match-only leaves resolv.conf untouched on macOS; new warning that emptying a match group's domains silently drops the search suffix (masked on domain-joined Windows); split-horizon example gains the route-everything-internal variant (the OpenVPN migration shape) - DNS overview: macOS line now distinguishes scoped resolvers from the primary case, where configd regenerates resolv.conf with NetBird's resolver
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
Next review available in: 36 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe DNS documentation now explains macOS scoped and primary resolvers, adds internal DNS configuration guidance, improves platform-specific troubleshooting, and updates issue references. ChangesDNS documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pages/manage/dns/internal-dns-servers.mdx`:
- Around line 126-137: Update src/pages/manage/dns/internal-dns-servers.mdx
lines 126-137 to state that every internal DNS server must recursively resolve
or forward public domains before configuring it as the primary nameserver. Add
the same prerequisite in src/pages/manage/dns/troubleshooting.mdx line 425
before recommending the primary group as the macOS workaround.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4164d3cd-4165-4ea9-942d-133e68783536
📒 Files selected for processing (4)
src/pages/help/troubleshooting-client/windows.mdxsrc/pages/manage/dns/index.mdxsrc/pages/manage/dns/internal-dns-servers.mdxsrc/pages/manage/dns/troubleshooting.mdx
| If you are migrating from a VPN that pushed your internal DNS servers for everything (a common OpenVPN setup), the equivalent is the same two groups pointing at the **same internal servers**: | ||
|
|
||
| **Primary (internal)**: Custom DNS with your internal DNS server IPs (e.g., 10.0.0.1, 10.0.0.2). Assign to your target group. Leave match domains empty. | ||
|
|
||
| **Match domain (internal)**: Same servers. Add match domain `company.internal`. Enable search domains. | ||
|
|
||
| Result: | ||
| - All queries, public and internal, go to your internal DNS | ||
| - `server` still expands to `server.company.internal` | ||
| - Tools that read `/etc/resolv.conf` directly and tools that use the system resolver query the same server | ||
|
|
||
| Two groups look redundant when they hold the same servers, but they do different jobs: the primary receives every query, while the match-domain group provides the search-domain expansion (and keeps working for scoped-resolver platforms). A VPN "pushing DNS servers" maps to the **primary** group, not to a match-domain group. |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
State the public-resolution prerequisite for an internal primary nameserver.
A primary nameserver resolves all unmatched domains. If the internal DNS servers are authoritative-only and do not recurse or forward public queries, these instructions stop public DNS resolution after users apply them. (docs.netbird.io)
src/pages/manage/dns/internal-dns-servers.mdx#L126-L137: State that each internal DNS server must recursively resolve or forward public domains before it is configured as primary.src/pages/manage/dns/troubleshooting.mdx#L425-L425: Add the same prerequisite before recommending the primary group as the macOS workaround.
📍 Affects 2 files
src/pages/manage/dns/internal-dns-servers.mdx#L126-L137(this comment)src/pages/manage/dns/troubleshooting.mdx#L425-L425
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/manage/dns/internal-dns-servers.mdx` around lines 126 - 137, Update
src/pages/manage/dns/internal-dns-servers.mdx lines 126-137 to state that every
internal DNS server must recursively resolve or forward public domains before
configuring it as the primary nameserver. Add the same prerequisite in
src/pages/manage/dns/troubleshooting.mdx line 425 before recommending the
primary group as the macOS workaround.
1 participant
Documents a macOS DNS behavior that surfaced in a support case: with a match-domain nameserver group and no primary, browsers and curl resolve internal names while dig and host return NXDOMAIN, because macOS keeps the two resolver paths separate.
Changes
DNS Troubleshooting
Internal DNS Servers
DNS overview
Summary by CodeRabbit