Stubby DNS — Privacy-First DNS-over-TLS Resolver

Stubby is a DNS stub resolver that encrypts your DNS queries using DNS over TLS (DoT). It acts as a privacy guard between your device and the internet, ensuring that every DNS query is encrypted and authenticated before it leaves your network.

Stubby is built on the getdns library, which implements the DNS-over-TLS standard. It is designed to be lightweight, secure, and easy to configure. You can use Stubby on its own or combine it with a local DNS cache like Dnsmasq or Unbound for better performance.

How Stubby Works

Stubby runs as a local service on your device. It listens for DNS queries on 127.0.0.1:53. When an application makes a DNS query, Stubby intercepts it and forwards it over an encrypted TLS connection to a DoT-capable upstream resolver. The upstream resolver is typically a public DNS provider like Cloudflare, Quad9, or Google.

The TLS encryption ensures that no one between your device and the DNS resolver can see or modify your DNS queries. Your ISP, the Wi-Fi hotspot provider, and anyone else on your network are blocked from seeing which domains you are visiting. Only the DNS resolver sees the actual queries.

Stubby also authenticates the DNS resolver. It checks the resolver's TLS certificate to confirm it is connecting to the legitimate server, not an imposter. This prevents man-in-the-middle attacks where an attacker redirects your DNS traffic to a fake resolver.

Installing and Configuring Stubby

On Linux, install Stubby from your distribution's package manager. On Debian and Ubuntu: sudo apt install stubby. On Fedora: sudo dnf install stubby. The configuration file is at /etc/stubby/stubby.yml on most systems.

On Windows, download the getdns/stubby installer from the official GitHub releases. The installer sets up Stubby as a Windows service. After installation, edit the configuration file at C:\Program Files\stubby\stubby.yml.

The default configuration already includes several DoT resolvers. You can customize which resolvers Stubby uses by editing the upstream_recursive_servers section. Cloudflare: 1.1.1.1 and 1.0.0.1 on port 853. Quad9: 9.9.9.9 and 149.112.112.112 on port 853.

After configuring Stubby, set your system DNS to 127.0.0.1. On Linux, this usually means editing /etc/resolv.conf. On Windows, change the DNS server in your network adapter settings to 127.0.0.1. Restart Stubby after the configuration change.

Stubby with Pi-hole

A common setup is using Stubby alongside Pi-hole. Pi-hole handles ad blocking and caching. Stubby handles DNS encryption. Pi-hole forwards queries to Stubby, which encrypts them and sends them to the upstream DoT resolver. This gives you ad blocking, caching, and encrypted DNS in one pipeline.

To set this up, configure Pi-hole to use 127.0.0.1#53 as its upstream DNS server. Configure Stubby to use your preferred DoT resolvers. Restart both services. Pi-hole sends queries to Stubby, which encrypts them and sends them upstream. The responses come back through Stubby to Pi-hole and then to the requesting device.

This setup gives you full control over your DNS resolution. Pi-hole provides the user interface and statistics. Stubby provides the encryption. You are not reliant on any single DNS provider for either blocking or privacy.

Troubleshooting Stubby

If Stubby is not working, check the system log for error messages. On Linux: journalctl -u stubby or check /var/log/syslog. Common issues include network connectivity problems, TLS certificate validation failures, and configuration syntax errors.

Test that Stubby is resolving queries correctly: dig @127.0.0.1 example.com. If the query succeeds, Stubby is working. If it fails, check that Stubby is running and listening on the correct address and port.

TLS connection failures indicate that the upstream DoT resolver is unreachable or that the TLS handshake failed. Check your internet connection and verify that the resolver addresses are correct. Some networks block port 853 used by DoT.

For more on encrypted DNS protocols and their differences, see our DNSCrypt guide and DNS over HTTPS guide.