Versions Compared

Key

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

...

Section


Column
width50%


Info

'Stubby' is part of the getdns project - this is just a reference

page on how to get up and running with Stubby!

Bugs or feature requests can be directed to either

Column
width30%

Image Removed 

Table of Contents

Stubby

...

name given to a mode of

...

using getdns

...

Numbered Headings

Dependencies

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. 

Linux

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

OS X

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
--with-ssl=/usr/local/opt/openssl/

Download the getdns source

Either clone the code:

Code Block
> git clone https://github.com/getdnsapi/getdns.git
> cd getdns
> git checkout develop

or grab a tarball from this page: Latest getdns releases

Build the code

Info

Note that on Mac OS X you will need the developer tools from Xcode to compile the code. And you may need to use brew to install libtool (and then use glibtoolize below), autoconf and automake.

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

Logging/debugging

  • --enable-debug-daemon If you don't want to see the connection statistics then remove the --enable-debug-daemon option in the configure line above.
  • --enable-debug-stub If you do want to see very detailed debug information as messages are processed (including connection statistics) then add the --enable-debug-stub option to the configure line above.

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. [Note: With no config file stubby will use opportunistic mode to the default nameservers for queries).

Info

It is recommended to use more than one upstream for increased performance and reliability. A config files that uses Strict Privacy to several of the current test servers that support this over both IPv4 and IPv6 is provided in the stubby source. To use it simply execute

Code Block
sudo cp ../src/tools/stubby.conf /etc/stubby.conf

To hand-craft a config file, read the instructions below. 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 (Note the hex representation of the SPKI pin is required here, not the base64 encoded form)
  • (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
  • use EDNS0 Client subnet privacy and enable Padding of DNS requests to hide the message size
Code Block
{ resolution_type: GETDNS_RESOLUTION_STUB
, dns_transport_list: [ GETDNS_TRANSPORT_TLS ]
, upstream_recursive_servers:
  [ { address_data: 185.49.141.38
    , tls_auth_name: "getdnsapi.net"
    , tls_pubkey_pinset:
      [ { digest: "sha256"
        , value: foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9S=
      } ]
   } ]
, tls_authentication: GETDNS_AUTHENTICATION_REQUIRED
, tls_query_padding_blocksize: 256
, edns_client_subnet_private : 1
, listen_addresses: [ 127.0.0.1, 0::1 ]
, 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.

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

Run Stubby

Simply invoke Stubby on the command line. By default it runs in the foreground, the '-g' flag runs it in the background.

Code Block
> sudo stubby
The logging is currently crude and simply writes to stderr.(We are working on making this better!) If don't want to see any logging for some reason then include the following on the command line: 2>/dev/null
  • If you build with both stub and daemon logging and want to see only the daemon logging use: 2>&1 >/dev/null |  grep 'DAEMON' 
  • The pid file is /var/run/stubby.pid
  • Test Stubby

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

    Code Block
    > dig @127.0.0.1 www.example.com

    Modify your upstream resolvers

    Note

    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 to the loopback interface on which 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 127.0.0.1
      nameserver ::1

    OS X

    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 127.0.0.1 ::1

    If you want to reset, just use:

    Code Block
    sudo networksetup -setdnsservers Wi-Fi Empty

    which should pick up the default DHCP nameservers. Or use something similar to the first set of instructions if you want to specify particular namerservers.

    Or via the GUI:

    • Open System Preferences->Network->Advanced->DNS
    • Use the '-' button to remove the existing nameservers
    • Use the + button to add '127.0.0.1' 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

    Notes:

  • 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.
  • Stubby currently backs-off for 1 hour from using servers that provide poor service - the next version will make this time configurable. Or this can be reset by restarting Stubby.

     which enables it to act as a local DNS Privacy stub resolver (using DNS-over-TLS). Stubby encrypts DNS queries sent from a client machine (desktop or laptop) to a DNS Privacy resolver increasing end user privacy.

    Stubby is in the early stages of development but is suitable for technical/advanced users. A more generally user-friendly version is on the way!

    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
    • Can be configured with authentication information for DNS Privacy servers and instructed to use either a 'Strict' or an 'Opportunistic' Profile as described in Authentication and (D)TLS Profile for DNS-over-(D)TLS

    Building Stubby

    Since Stubby is part of the getdns project - the reference page for how to get up and running with Stubby has moved to the getdns website:

    Stubby Reference Guide

    As always, bugs or feature requests can be directed to either



    Column
    width30%

    Image Added 



    Other options

    Other ways to run a privacy daemon are: 

    • Run Unbound as a local forwarder using the ssl_upstream option to encrypt outgoing queries. This is provides a local caching resolver but at the moment Unbound doesn't fully support RFC7766 as a client and so you may not see the same performance as from Stubby (which pipelines queries). 
    • Work is in progress to enable knot resolver to work in this mode too