STUBBY(1)

NAME
stubby - a local DNS Privacy stub resolver

SYNOPSIS
stubby [-C file] [-ghilV] [-v loglevel]

DESCRIPTION
stubby acts as a local DNS Privacy stub resolver, using DNS-over-TLS. Stubby encrypts DNS queries sent from the local machine to a DNS Privacy resolver, increasing end user privacy.

stubby is in the early stages of development but is suitable for technical/advanced users.

stubby provides DNS Privacy by running as a daemon that listens on the loopback address for DNS queries, and forwards those queries out over TLS. The default configuration provides Strict Privacy, and uses a subset of available DNS Privacy servers. See https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Test+Servers .

OPTIONS

-C file
    Read settings from the configuration file file. If this option is not given, stubby looks for a configuration file at ~/.stubby.yml. If this is not present, stubby falls back to the global configuration file @ETCDIR@/stubby.yml.

-g  Run stubby as a daemon.

-h  Print a usage message and exit.

-i  Read the configuration, validate the contents, pretty-print them to the standard output and exit.

-l  Enable all logging. Equivalent to -v 7.

-v loglevel
    Enable logging. All logging messages at or below loglevel are printed to standard error:

    0: EMERG
        The system is unusable

    1: ALERT
        Action must be taken immediately

    2: CRIT
        Critical conditions

    3: ERROR
        Error conditions

    4: WARN
        Warning conditions

    5: NOTICE
        Normal, but significant, conditions

    6: INFO
        Information messages

    7: DEBUG
        Debug-level messages

-V  Print the stubby version and exit.

CONFIGURATION
The configuration file is in YAML. An example config is:

    resolution_type: GETDNS_RESOLUTION_STUB
    dns_transport_list:
      - GETDNS_TRANSPORT_TLS
    tls_authentication: GETDNS_AUTHENTICATION_REQUIRED
    tls_query_padding_blocksize: 256
    edns_client_subnet_private : 1
    idle_timeout: 10000
    listen_addresses:
      - 127.0.0.1
      -  0::1
    round_robin_upstreams: 1
    upstream_recursive_servers:
      - address_data: 145.100.185.15
        tls_auth_name: "dnsovertls.sinodun.com"
        tls_pubkey_pinset:
          - digest: "sha256"
            value: 62lKu9HsDVbyiPenApnc4sfmSYTHOVfFgL3pyB+cBL4=
      - address_data: 145.100.185.16
        tls_auth_name: "dnsovertls1.sinodun.com"
        tls_pubkey_pinset:
          - digest: "sha256"
            value: cE2ecALeE5B+urJhDrJlVFmf38cJLAvqekONvjvpqUA=
      - address_data: 185.49.141.37
        tls_auth_name: "getdnsapi.net"
        tls_pubkey_pinset:
          - digest: "sha256"
            value: foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9Q=
      - address_data: 2001:610:1:40ba:145:100:185:15
        tls_auth_name: "dnsovertls.sinodun.com"
        tls_pubkey_pinset:
          - digest: "sha256"
            value: 62lKu9HsDVbyiPenApnc4sfmSYTHOVfFgL3pyB+cBL4=
      - address_data: 2001:610:1:40ba:145:100:185:16
        tls_auth_name: "dnsovertls1.sinodun.com"
        tls_pubkey_pinset:
          - digest: "sha256"
            value: cE2ecALeE5B+urJhDrJlVFmf38cJLAvqekONvjvpqUA=
      - address_data: 2a04:b900:0:100::38
        tls_auth_name: "getdnsapi.net"
        tls_pubkey_pinset:
          - digest: "sha256"
            value: foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9Q=

The configuration items are as follow. Some take constant values from the getdns library underlying stubby and further explanation of their values may be found in the getdns documentation or at http://www.getdnsapi.net .

resolution_type resolution.
    This must be set to GETDNS_RESOLUTION_STUB for historic reasons. stubby will exit with an error if any other setting is used.

dns_transport_list list
    Set the list of transport types to be used. For DNS Privacy this must be set to GETDNS_TRANSPORT_TLS. Clear text transports are GETDNS_TRANSPORT_TCP and GETDNS_TRANSPORT_UDP .

tls_authentication type
    Set the type of authentication required. For Strict Privacy, this should be set to GETDNS_AUTHENTICATION_REQUIRED. For Opportunistic mode, remove this setting or set to GETDNS_AUTHENTICATION_NONE. In Opportunistic mode authentication of the nameserver is not required and fallback to clear text transports is permitted if they are in dns_transport_list .

tls_query_padding_blocksize blocksize
    Use the EDNS0 padding option to pad DNS queries to hide their size.

edns_client_subnet_private 0 or 1
    If 1, use EDNS0 Client Subnet privacy so the client s ubnet is not sent to authoritative servers.

idle_timeout timeout
    Use an EDNS0 Keepalive idle timeout of timeout milliseconds 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 0 or 1
    If 1, 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 server list
    Specify the upstream servers that stubby is to use. Each item in the list contains the following items:

    address_data address
        IPv4 or IPv6 address of the server.

    tls_auth_name name
        This is the authentication domain name that will be verified against the presented certificate.

    tls_pubkey_pinset pinset
        The sha256 SPKI pinset for the server. This is also verified against the presented certificate. This contains two items:

        digest type
            The type of the key digest.

        value keyval
            The key value.

FILES
~/.stubby.yml
@ETCDIR@/stubby.yml

SEE ALSO
https://getdnsapi.net/
https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Daemon+-+Stubby