When your network has on-premise DNS infrastructure — Active Directory, BIND, Unbound, or other internal DNS servers — you may need to configure EagleSafe ZTB to use them. This page covers when a nameserver configuration is needed and when it isn’t.
When you don’t need a nameserver
If you only need access to a few internal resources by domain name, you don’t need to configure a nameserver. Create a Network resource with the internal domain name (e.g. fileserver.corp.local) and an access control policy allowing peers to reach it. The routing peer resolves the DNS and routes traffic to the resource, as long as it can itself resolve the domain.
Wildcard domains are also supported as resources (e.g. *.corp.local), but they route all matching traffic through the routing peer. For granular access, prefer single domain names.
Domain resources and routing peer DNS
When a Network resource is defined using a domain name (e.g. crm.corp.local), the routing peer resolves that domain using its own local DNS configuration. If the routing peer cannot resolve the domain — for example, a Linux peer not configured to use your internal DNS — domain resource lookups will fail.
To fix this, add the routing peer’s group to the distribution groups of your internal nameserver:
- Go to DNS → Nameservers and edit your internal DNS nameserver (or create one).
- Add the routing peer’s group to Distribution Groups.
- Under Domains, ensure your internal domains are listed (e.g.
corp.local). - Save.
Configure a nameserver for internal domains
- Go to DNS → Nameservers → Add Nameserver and choose Custom DNS.
- Enter the IP addresses of your internal DNS servers (e.g.
192.168.0.32). Configure 2–3 IPs for redundancy. - Select the Distribution Groups — the peer groups that should use this nameserver.
- Under Domains, add a Match Domain with your internal domains (e.g.
corp.local,company.internal). - Save.
Peers in the distribution groups will use your internal DNS for the specified domains. All other domains continue to resolve normally.
Private DNS behind routing peers
If your internal DNS server is on a private network not directly reachable by peers, you need to route DNS traffic through a routing peer in addition to the nameserver configuration above.
- Go to Networks → Add Network and add a resource with the DNS server’s IP (e.g.
192.168.0.32/32). Assign it to a group (e.g. “Internal DNS”). Add the routing peer that can access the private network. - Create an access control policy: Source = your user groups, Destination = “Internal DNS” group, Protocol = UDP, Port = 53.
Primary vs match domain nameservers
- Match domain: handles queries for specific domains (e.g.
corp.local). Adding a domain automatically includes all subdomains. - Primary: handles all queries not matched by other nameservers. Created by leaving Match Domains empty.
Each peer should have exactly one primary nameserver. Without a primary, peers use their original DNS for non-matched queries.
Search domains
Enable Mark match domains as search domains to allow short name queries. When enabled, typing server expands to server.company.internal.
Example: split-horizon DNS
Primary nameserver (internet):
Provider: Cloudflare (1.1.1.1, 1.0.0.1)
Distribution: All Peers
Match domains: (none — primary)
Match domain nameserver (internal):
Provider: Custom (10.0.0.1, 10.0.0.2)
Distribution: All Peers
Match domain: company.internal
Search domain: enabled
Result:
google.com → Cloudflare
app.company.internal → Internal DNS (10.0.0.1)
server → Expanded to server.company.internal → Internal DNSDNS failover and overlapping domains
Configure multiple IPs within a single nameserver entry for automatic failover — the client tries servers in order. When multiple nameservers match a query, the most specific match domain wins.
Managing nameservers
- Edit: go to DNS → Nameservers, click the nameserver, modify settings and save. Changes propagate to peers within 10–30 seconds with no restart required.
- Disable temporarily: edit the nameserver and toggle Enable Nameserver to OFF. The configuration is preserved.
- Delete: before deleting a primary nameserver, create a new primary first — otherwise peers revert to their original DNS settings.
Active Directory and Domain Controllers
Domain Controllers as routing peers
Using Domain Controllers (DCs) as routing peers is not recommended. If unavoidable, you must disable ZTB DNS management for the DC’s group — otherwise ZTB will interfere with the AD DNS services the DC depends on.
- Create a dedicated group for your Domain Controllers (e.g. “Domain Controllers”).
- Go to DNS → DNS Settings.
- Add the Domain Controllers group to Disable DNS management for these groups.
- Save.
The DC continues using its own DNS for Active Directory services while still acting as a routing peer.
WireGuard port conflict on Domain Controllers
When the ZTB agent is installed on a Windows Domain Controller, the Windows DNS Server service may already be using UDP port 51820 (WireGuard’s default), causing the agent to fail at startup.
Symptoms: agent fails with context deadline exceeded, peer appears disconnected.
Diagnosis:
netstat -ano | findstr 51820
tasklist /FI "PID eq <PID>"If the process is dns.exe, the conflict is confirmed.
Fix: exclude port 51820 from the DNS Server’s socket pool, then restart both services:
dnscmd /config /SocketPoolExcludedPortRanges 51820-51820
net stop dns && net start dns
netbird service restartSchedule this change during a maintenance window — restarting the DNS Server service temporarily interrupts DNS resolution for all clients on that DC. This exclusion persists across reboots.
