---
name: "stubby"
section: "1"
platform: "linux"
package: "stubby"
version: "0.4.3-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/stubby"
---

# stubby(1)

a local DNS Privacy stub resolver

## 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 */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 **-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
/etc/stubby/stubby.yml
```

## SEE ALSO

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