You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

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.

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.

The configuration file format is a JSON like format used internally in getdns and 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. Essentially the options available are the same as the options that can be set on a getdns context. 

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, simply remove the tls_authentication: GETDNS_AUTHENTICATION_REQUIRED field. 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.

{ resolution_type: GETDNS_RESOLUTION_STUB
, dns_transport_list: [ GETDNS_TRANSPORT_TLS ]
, tls_query_padding_blocksize: 256
, edns_client_subnet_private : 1
, listen_addresses: [, 0::1 ]
, idle_timeout: 10000
, round_robin_upstreams: 1
, upstream_recursive_servers:
  [ { address_data:
    , tls_auth_name: ""
    , tls_pubkey_pinset:
      [ { 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.

We plan to switch to using YAML for the configuration file in the near future as it is more user friendly!!


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

dnssec_return_status: GETDNS_EXTENSION_TRUE

If using a version of getdns earlier than 1.2 (due for release in September 2017) then DNSSEC support also requires that a trust anchor is manually installed and managed on the system. We recommend using unbound-anchor. getdns version 1.2 should include support for automatic trust anchor management. 

  • No labels