Configure DNS
Firezone includes a sophisticated DNS routing system available on all plans that provides Split DNS and fallback resolver configuration for each Firezone Client. Read more below to understand how it works and how to configure it.
How DNS works in Firezone
Each Firezone Client embeds a lightweight DNS resolver used to route queries to an appropriate Gateway for resolution.
When a user signs in, the Client configures the host operating system to use this resolver as the default resolver for all queries on the system.
This is why you'll commonly see 100.100.111.1 or
fd00:2021:1111:8000::100:100:111:0 as the DNS server responding to DNS queries
when the Firezone Client is signed in.
How queries are resolved
DNS resolution is explained in detail in the Firezone architecture docs.
When the resolver sees a DNS query for a Resource, it generates a mapped, dummy IP and responds with that IP. The mapped IP is used to route traffic corresponding to the Resource in question to a healthy Gateway. While this is happening, the Gateway receives the query via the control plane and resolves it using its system resolver, storing the result in a lookup table.
When the Gateway sees traffic coming from the Client for the mapped IP, it translates the mapped IP back to the actual IP address of the Resource and forwards the traffic to the Resource.
This happens in a fraction of a second and is completely transparent to the end user. The Client host's system resolver is never used for resolving DNS queries for Firezone Resources, and never sees the actual IP addresses of DNS Resources in your account, ensuring your DNS data remains private and secure.
For example, if github.com was added as a Resource, an nslookup might return
100.96.0.1 as its IPv4 address:
> nslookup github.com
Server: 100.100.111.1
Address: 100.100.111.1#53
Non-authoritative answer:
Name: github.com
Address: 100.96.0.1
If the query doesn't match a Resource, the resolver forwards the query to one of the upstream resolvers if configured in your account. Otherwise, it forwards the query to the default system resolver on the Client host.
Queries forwarded to upstream resolvers are never routed through Firezone unless (1) you've defined custom upstream resolver(s) below, and (2) those resolvers are defined as Resources in your account. This ensures that queries for Firezone infrastructure and services on the Client's local LAN continue to be resolvable even if the Client's DHCP-provided DNS server collides with an IP or CIDR Resource in your account.
Firezone only intercepts queries for the A, AAAA, and PTR record types for
your DNS Resources. All other record types are forwarded to the upstream
resolver(s).
Configuring Client DNS upstream resolvers
Upstream DNS in all Clients can be configured with the servers of your choosing so that all queries on Client devices will be forwarded to the servers you specify for all non-Firezone resources.
Go to Settings -> DNS and enter IPv4 and/or IPv6 servers to use as fallback
resolvers. Firezone Clients will use these servers in the order they are defined
for any query that doesn't match a Resource the user has access to.
When setting custom upstream resolvers, it is highly recommended to configure both an IPv4 and IPv6 option. Otherwise, a Client that has only IPv4 or IPv6 connectivity may not be able to resolve DNS queries.
Firezone Clients support only DNS over UDP/53 at this time. DNS-over-TLS and DNS-over-HTTPS upstream servers are not yet supported.
If no custom resolvers are configured, Firezone Clients will fall back to the default system resolvers, typically set by the DHCP server of their local network.
Custom resolvers such as Cloudflare or NextDNS can be used to block malware, ads, adult material and other content for all users in your Firezone account.
Configuring Gateway resolvers
Firezone makes no assumptions about the DNS environment in which the Gateway
runs. It uses the default system resolver you've configured on the Gateway host,
typically defined in /etc/resolv.conf.
This resolver is used for DNS Resources defined in your Firezone account so it's important that your Gateway host has DNS configured properly for Clients to resolve names successfully.
Need additional help?
See all support options or try asking on one of our community-powered support channels:
- Discussion forums: Ask questions, report bugs, and suggest features.
- Discord server: Join discussions, meet other users, and chat with the Firezone team
- Email us: We read every message.