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

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.

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.

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.

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.