stubby - a local DNS Privacy stub resolver

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.netresolution_typeresolution.
              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_listlist
              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_UDPtls_authenticationtype
              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_listtls_query_padding_blocksizeblocksize
              Use the EDNS0 padding option to pad DNS queries to hide their size.

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

       idle_timeouttimeout
              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_upstreams0 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_serversserverlist
              Specify  the  upstream servers that stubby is to use. Each item in the list contains the following
              items:

              address_dataaddress
                     IPv4 or IPv6 address of the server.

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

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

                     digesttype
                            The type of the key digest.

                     valuekeyval
                            The key value.

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

Files

~/.stubby.yml/etc/stubby/stubby.yml

Name

       stubby - a local DNS Privacy stub resolver

Options

-Cfile
              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 /etc/stubby/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 -v7.

       -vloglevel
              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.