Configure Stubby

It is recommended to use the default configuration file provided which will use 'Strict' privacy mode and spread the DNS queries among several of the current DNS Privacy test servers. Note that this file contains both IPv4 and IPv6 addresses.

Note also that this file only enables a small subset of the available servers by default. Users can choose to use additional servers by uncommenting the relevant sections in the file. See DNS Privacy Test Servers for details of the available servers.

Create Custom Configuration File

Alternatively the configuration file location can be specified on the command line using the -C flag. Changes to the configuration file require a restart of Stubby.

From release 0.1.3 of stubby (using the 1.2 release of getdns) the configuration file format is a YAML like format, which contains detailed comments of the options. See here for an example or keep reading for a short description. To be backwards compatible a file using the YAML format must have a .yml or .yaml extension.

Essentially the options available are the same as the options that can be set on a getdns context. 

The previously used JSON like format used internally in getdns is still supported but only when the configuration file is specified via the command line using the -C flag. This format is the same as the output returned by stubby -i. For example, this output can be used as a configuration file directly, but a less verbose form is also accepted.

To aid with creating a custom configuration file, an example is given below.

The config file below will configure Stubby in the following ways:

  • resolution_type: Work in stub mode only (not recursive mode) - required for Stubby operation.
  • dns_transport_list: Use TLS only as a transport (no fallback to UDP or TCP).
  • tls_authentication: Use Strict Privacy i.e. require a TLS connection and authentication of the upstream
    • If Opportunistic mode is desired,  remove the tls_authentication: GETDNS_AUTHENTICATION_REQUIRED field and add additional transports to the dns_transport_list (e.g. UDP, TCP) . In Opportunistic mode authentication of the nameserver is not required and fallback to clear text transports is permitted if they are in the dns_transport_list.
  • tls_query_padding_blocksize: Use the EDNS0 padding option to pad DNS queries to hide their size
  • edns_client_subnet_private: Use EDNS0 Client Subnet privacy so the client subnet is not sent to authoritative servers
  • listen_address: have the Stubbby daemon listen on IPv4 and IPv6 on port 53 on the loopback address
  • idle_timeout: Use an EDNS0 Keepalive idle timeout of 10s unless overridden by the server. This keeps idle TLS connections open to avoid the overhead of opening a new connection for every query.
  • round_robin_upstreams: Round robin queries across all the configured upstream servers. Without this option Stubby will use each upstream server sequentially until it becomes unavailable and then move on to use the next.
  • upstream_recursive_servers: Use the NLnet labs test DNS Privacy Server for outgoing queries. In Strict Privacy mode, at least one of the following is required for each nameserver:
    • tls_auth_name: This is the authentication domain name that will be verified against the presented certificate.
    • tls_pubkey_pinset: The sha256 SPKI pinset for the server. This is also verified against the presented certificate.

tls_query_padding_blocksize: 256
edns_client_subnet_private : 1
idle_timeout: 10000
  -  0::1
round_robin_upstreams: 1
  - address_data:
    tls_auth_name: ""
      digest: "sha256"
       value: foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9Q=

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.

A custom port can be specified by adding the tls_port: attribute to the upstream_recursive_server in the config file.

A custom listen address port can be configured by using the <IP_address>@<port> syntax


To enable DNSSEC validation when using Stubby add the following option to the configuration file

dnssec_return_status: GETDNS_EXTENSION_TRUE

A trust anchor is also required for DNSSEC validation. 

getdns version 1.2 and later include support for automatic trust anchor management - which will automatically fetch a trust anchor if none is present on the system. See 'Zero configuration DNSSEC'  (and below) for the specific details of key management for DNSSEC for this case. 

If using a version of getdns earlier than 1.2 then a trust anchor must be manually installed and managed on the system. We recommend using unbound-anchor.

Storage of Zero-config Trust anchor

When the system-level user does have a home directory, stubby will store the for Zero configuration DNSSEC dynamically acquired root trust anchor in a subdirectory called ".getdns" of that home directory. If the system-level user does not have a home directory or the home directory is not writeable or readable, stubby will fallback to the current working directory.

This can be overruled by supplying a "appdata_dir" in the stubby.yml configuration file. When a "appdata_dir" was specified, that directory will be used for storing data related to Zero configuration DNSSEC immediately, without the other paths being tried. It is recommended for systemd setups using the provided systemd.service file(s) to have a "appdata_dir" directive set to "/var/cache/stubby" in the stubby.yml configuration file.

Note that using DNSSEC can add a small performance overhead because it increases the number of queries required to resolve a DNS request.

Opportunistic DoT to your local resolver

Some users may want to have a configuration for Stubby that will always use the resolver from the system configuration (most likely but not always on the local network), but with encryption used where possible. This is an Opportunistic mode which does not authenticate the DoT server. To configure Stubby in this mode:

  1. Set the transport list and authentication parameter in the configuration to:

    tls_authentication: GETDNS_AUTHENTICATION_NONE
  2. Remove (or comment out) all the upstream_resolvers. This will cause Stubby to fallback to using the system resolvers only.

Note: a future version of Stubby will most likely support a mixed mode of system resolvers and configured resolvers. 

Runtime logging

In the 0.1.2 release of stubby there is runtime logging, which can be turned on by using the '-l' flag.

In the 0.1.3 release the logging level is be controlled by specifying a logging level via the '-v' flag. See stubby help ('stubby -h') for more details. 

  • No labels


  1. Anonymous

    Is there any way to change the local port stubby is listening on? I want to use another one instead of 53. Thanks.

  2. Anonymous


    You can edit the stubby.conf file (older releases of getdns) or the stubby.yml (>getdns

    1.2). To be found usually in /usr/local/etc/stubby/ directory.

    If you are not sure just enter in a terminal : sudo stubby -i

  3. Anonymous

    I looked into the code and it seems that port 53 is hard-coded (see server.c, function getdns_context_set_listen_addresses, line 809). So without patching, it is not possible to run stubby together with another resolver on the same host. That is a bit frustrating, especially as the addresses stubby is listening on can be configured. The typical use case would be using dnsmasq to handle DNS for the local domain and using stubby as DNS "upstream" resolver, such that dnsmasq routes all unhandled DNS requests through stubby.

  4. Anonymous

    Thank you, you are correct. I am sorry for my 'help'. I also tried to use portforwarding to an unprivileged 5353 in unbound but that failed also.

  5. Anonymous

    From: :

    See the comments in the default stubby.yml file for how to specify a port:

    getdns_context_listen_addresses accepts a list of address dicts, these can contain ports.
    That the yaml config shows only addresses and not a fully expanded address dictionary, is because it will be converted to an address dictionary by getdns_str2dict automatically: see

    But it is also possible to give the address and port explicitly with an address dictionary.
    For example in yaml:

      - address_data:
        port: 5353
      - address_data: 0::1
        port: 5353

    or in getdns style JSON:

    { listen_addresses:
      [ { address_data:
        , port: 5353 }
      , { address_data: 0::1
        , port: 5353 }
  6. Anonymous

    Hi, i have one question. With Dnscrypt you could use a blacklist to avoid resolving certain domains and ips. Is going to be this feature available anytime soon?

  7. We've had a similar request to be able to configure forward zones, see:

    Is your specific request to be able to configure domains that you always get NXDOMAIN for ?

    1. Anonymous

      Hi Sara, the specific situation i'm referring to concearns to the fact that in Windows some ips and domains used for gathering telemetry are hardcoded in dlls, avoiding the hosts file, so i used the blacklist in dnscrypt to prevent the dns resolution and the consecuent connections. This can be applied also to prevent malware/trojan/ransomware connections to certain ips/domains. I would like to have this same functionality on Stubby if possible, it would be awesome.

  8. Just a hint for Windows users, usind DNSSEC Zero Configuration:

    The text is a bis misleading, the default path on Windows is "%AppData%\getdns" and not "%Userprofile%\.getdns"