Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.



Stubby is the name given to a mode of using getdns which enables it to act as a local DNS-over-TLS stub resolver. The daemon can  It is recommended to use the latest release of the 1.1 version of getdns to have the most up to date version of Stubby.

In this mode  Stubby (getdns) does several things

  • Runs as a daemon
  • By default obtains its configuration information from the configuration file at /etc/stubby.conf
  • Can be configured to listen on the loopback address and send all outgoing DNS queries received on that address out over TLS to a DNS Privacy server


Building Stubby

> sudo src/tools/getdns_query -s @185

Create a config file

Stubby will use the config file at /etc/stubby.conf by default if it exists, or the config file location can be specified on the command line using the '-C' flag. Changes to the config file require a restart of Stubby.

The config file below is an example that will configure Stubby to:

  • listen on IPv4 and IPv6 on port 53 on the loopback address
  • use TLS over IPv4 to the NLnet labs test DNS Privacy Server for outgoing queries
  • enforce a 'Strict' Usage Profile based authentication of both a domain name and a SPKI pinset (If Opportunistic mode is desired, simply remove the 'tls_authentication: GETDNS_AUTHENTICATION_REQUIRED' field)
  • use an EDNS0 Keepalive timeout of 10s unless overridden by the server
Numbered Headings


In this mode, the only dependency is OpenSSL (version 1.0.2 or later is required for hostname authentication to be supported). If this is installed in a non-standard location on your system use the --with-ssl option to configure below to specify where it is. 


It may be necessary to install 1.0.2 from source for most Linux distros.


It is recommended to install OpenSSL using homebrew, in which case use the following in the configure line in step 1.3 below:

Code Block

Download the getdns source

Either clone the code:

Code Block
> git clone
> cd getdns
> git checkout release/1.1.0-alpha3

or grab a tarball from this page: Latest getdns releases

Build the code

Code Block
> git submodule update --init
> libtoolize -ci
> autoreconf -fi
> mkdir build
> cd build
> ../configure --prefix=<install_location> --without-libidn --enable-stub-only
> make
> sudo make install


  • --enable-debug-daemon If you just want to see very detailed debug information as messages are processed (including teh connection statistics ) then add use the --enable-debug-stubdaemon option instead to the configure line above.
  • --enable-debug-stub If you just want to see very detailed debug information as messages are processed (including connection statistics) then use add the --enable-debug-daemonstub option instead to the configure line above.

Run the daemon

The command below will run the daemon listening on port 53 of the loopback address and sending queries to the NLnet Labs test DNS Privacy server (at and 2a04:b900:0:100::38) over TLS. (More test servers are listed here).

It also specifies an example idle timeout on the TLS connection of 10s with the '-e 10000' option. (Note: the NLnet Labs test server does not support EDNS0 TCP Keepalive yet, so in that case this timeout will always be used.)


It is recommended to use more than one upstream for increased performance and reliability.


IPv4 only

Code Block
Code Block
{ resolution_type: GETDNS_RESOLUTION_STUB
, dns_transport_list: [ GETDNS_TRANSPORT_TLS ]
, upstream_recursive_servers:
  [ { address_data:
-l L -z -e 10000

IPv4 and IPv6

Code Block
> sudo src/tools/getdns_query -s @ @2a04:b900:0:100::38 -l L -z   , tls_auth_name: ""
    , tls_pubkey_pinset:
      [ { digest: "sha256"
        , value: 0x7e8c59467221f606695a797ecc488a6b4109dab7421aba0c5a6d3681ac5273d4
      } ]
   } ]
, listen_addresses: [ -z 1, 0::1@531 -e 10000

You can specify multiple upstreams just by repeating the @<address> element on the command line.

Exit the daemon at any time by hitting CTRL-C.

Strict vs Opportunistic

The above command will run the daemon without trying to authenticate the TLS connection (a form of Opportunistic Privacy).

If you have authentication information for the DNS Privacy server and you want to use Strict Privacy then you can specify this when starting the daemon in the following ways:

  • Domain name: append the domain name to the IP address with a tilde '~' e.g. and add the '-m' flag
  • SPKI pinset: specify the pinset using the '-K' flag e.g. -K 'pin-sha256="foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S="' and add the '-m' flag
Test the daemon
, idle_timeout: 10000

Additional privacy servers can be specified by adding more entries to the upstream_recursive_servers list above (note a separate entry must be made for the IPv4 and IPv6 addresses of a given server. More DNS Privacy test servers are listed here.


It is recommended to use more than one upstream for increased performance and reliability.


Run Stubby

Simply invoke Stubby on the command line. By default it runs in the foreground, the '-g' flag runs it in the background. The pid file is /var/run/

Code Block
> sudo stubby


Test Stubby

A quick test can be done by using dig (or your favourite DNS tool) on the loopback address

Code Block
> dig @

Modify your upstream resolvers

For getdns

Once this change is made your DNS queries will be re-directed to Stubby and sent over TLS! (You may need to restart some applications to have them pick up the network settings).

You can monitor the traffic using Wireshark watching on port 853.

For Stubby to re-send outgoing DNS queries over TLS the recursive resolvers configured on your machine must be changed to send all the local queries over to the loopback interface on which getdns Stubby is listening. This depends on the operating system being run. It is useful to note your existing default nameservers before making this change!

Linux/Unix systems

  • Edit the /etc/resolv.conf file
  • Comment out the existing nameserver entries
  • Add the following (only add the IPv4 address if you don't have IPv6)

    Code Block
    nameserver ::1


From the command line you can do the following to set the local DNS servers on, for example, your 'Wi-Fi' interface (first line clears all servers, second line adds localhost):

Code Block
sudo networksetup -setdnsservers Wi-Fi Empty
sudo networksetup -setdnsservers Wi-Fi ::1

If you want to reset, use something similar to the above to specify your default servers.


Or via the GUI:

  • Open System Preferences->Network->Advanced->DNS
  • Use the '-' button to remove the existing nameservers
  • Use the + button to add '' and '::1' (only add the IPv4 address if you don't have IPv6)
  • Hit 'OK' in the DNS pane and then 'Apply' on the Network pane

Once the change in step 1.6 is made your queries will be re-directed to the getdns daemon and sent over TLS! You can monitor the traffic using Wireshark watching on port 853.


  • You may need to restart some applications to have them pick up the network settings
  • If you are using a DNS Privacy server that does not support concurrent processing of TLS queries, you may experience some issues due to timeouts causing subsequent queries on the same connection to fail.
  • The daemon Stubby currently (indefinitely) backs-off for 1 hour from using servers that provide poor service - the next version will have a timed re-try in this case.make this time configurable. Or this can be reset by restarting Stubby.