EagleSafe ZTB provides centralized DNS management to help your peers resolve domain names within your private network and control how DNS queries are routed across your tenant.
Key concepts
- Nameserver: a DNS server distributed to peers. Configured under DNS → Nameservers.
- Match Domains: specific domains resolved by a particular nameserver (e.g.
company.internal). Adding a domain automatically includes all its subdomains. - Primary Nameserver: the default nameserver that handles all queries not matched by specific rules. Configured by leaving match domains empty.
- Search Domains: suffixes automatically appended to short hostnames. If
company.internalis a search domain, typingserver1resolves asserver1.company.internal. - DNS Resolver: each peer runs a local DNS resolver that routes queries based on your nameserver configuration.
How DNS works
Each peer runs a local embedded DNS resolver. When an application makes a DNS query, the resolver:
- Checks whether the query matches a configured match domain — if yes, forwards to the specific nameserver for that domain.
- If no match, forwards to the primary nameserver.
- Returns the result to the application.
Example with a primary nameserver (1.1.1.1) and a match domain nameserver (company.internal → internal DNS 10.0.0.1):
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
Query: "server" (with search domain "company.internal")
→ Expanded to "server.company.internal"
→ Matches company.internal → Internal DNS → Returns private IPIf a peer belongs to multiple distribution groups, all nameserver configurations from those groups are merged. When multiple nameservers match a query, the most specific match domain wins.
Default behavior (no nameservers configured)
- Linux: ZTB always configures DNS so that peer domain names resolve automatically. Original nameservers are preserved as upstream.
- macOS / Windows / Mobile: without nameservers configured, ZTB does not modify DNS settings. Peer domain names will not resolve — you can still use ZTB IP addresses directly.
DNS setup per platform
- Linux: configures DNS via
/etc/resolv.conforresolvconf. Original nameservers preserved as upstream. - macOS: uses system APIs, does not modify
/etc/resolv.conf. - Windows: sets the network adapter's DNS server to the local ZTB resolver.
- Android: requires disabling Private DNS (Settings → Network & Internet → Private DNS → Off). When Private DNS is enabled, Android bypasses VPN DNS.
- iOS: uses VPN DNS configuration.
Match domain support: only macOS, Windows 10+, and Linux with systemd-resolved support nameservers with match domains. Always configure at least one primary nameserver (without match domains) assigned to all peers.
DNS forwarder on routing peers
When a Network resource uses a domain name, the routing peer runs a DNS forwarder that resolves the domain on behalf of clients. The forwarder listens on port 22054. If domain resources are not resolving, verify the port is open on the routing peer:
nslookup -port=22054 <domain> <routing-peer-ip>DNS management modes
- Managed mode (default): ZTB fully controls DNS settings on the peer. All queries go through the ZTB resolver.
- Unmanaged mode: ZTB does not modify DNS settings. The peer uses its existing DNS configuration.
DNS management can be disabled per peer group in DNS → Settings. This is required for Active Directory Domain Controllers — ZTB DNS management must be disabled on DC groups to avoid interfering with AD DNS services.
