1STUBBY(1) General Commands Manual STUBBY(1)
2
6 stubby - a local DNS Privacy stub resolver
7
10 stubby [-C file] [-ghilV] [-v loglevel]
11
14 stubby acts as a local DNS Privacy stub resolver, using DNS-over-TLS.
15 Stubby encrypts DNS queries sent from the local machine to a DNS Pri‐
16 vacy resolver, increasing end user privacy.
17 stubby is in the early stages of development but is suitable for tech‐
19 nical/advanced users.
20 stubby provides DNS Privacy by running as a daemon that listens on the
22 loopback address for DNS queries, and forwards those queries out over
23 TLS. The default configuration provides Strict Privacy, and uses a
24 subset of available DNS Privacy servers. See https://dnspri‐
25 vacy.org/wiki/display/DP/DNS+Privacy+Test+Servers
26
29 -C file
30 Read settings from the configuration file file. If this option
31 is not given, stubby looks for a configuration file at
32 ~/.stubby.yml. If this is not present, stubby falls back to the
33 global configuration file /etc/stubby/stubby.yml.
34 -g Run stubby as a daemon.
36 -h Print a usage message and exit.
38 -i Read the configuration, validate the contents, pretty-print them
40 to the standard output and exit.
41 -l Enable all logging. Equivalent to -v 7.
43 -v loglevel
45 Enable logging. All logging messages at or below loglevel are
46 printed to standard error:
47 0: EMERG
49 The system is unusable
50 1: ALERT
52 Action must be taken immediately
53 2: CRIT
55 Critical conditions
56 3: ERROR
58 Error conditions
59 4: WARN
61 Warning conditions
62 5: NOTICE
64 Normal, but significant, conditions
65 6: INFO
67 Information messages
68 7: DEBUG
70 Debug-level messages
71 -V Print the stubby version and exit.
73
76 The configuration file is in YAML. An example config is:
77 resolution_type: GETDNS_RESOLUTION_STUB
79 dns_transport_list:
80 - GETDNS_TRANSPORT_TLS
81 tls_authentication: GETDNS_AUTHENTICATION_REQUIRED
82 tls_query_padding_blocksize: 256
83 edns_client_subnet_private : 1
84 idle_timeout: 10000
85 listen_addresses:
86 - 127.0.0.1
87 - 0::1
88 round_robin_upstreams: 1
89 upstream_recursive_servers:
90 - address_data: 145.100.185.15
91 tls_auth_name: "dnsovertls.sinodun.com"
92 tls_pubkey_pinset:
93 - digest: "sha256"
94 value: 62lKu9HsDVbyiPenApnc4sfmSYTHOVfFgL3pyB+cBL4=
95 - address_data: 145.100.185.16
96 tls_auth_name: "dnsovertls1.sinodun.com"
97 tls_pubkey_pinset:
98 - digest: "sha256"
99 value: cE2ecALeE5B+urJhDrJlVFmf38cJLAvqekONvjvpqUA=
100 - address_data: 185.49.141.37
101 tls_auth_name: "getdnsapi.net"
102 tls_pubkey_pinset:
103 - digest: "sha256"
104 value: foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9Q=
105 - address_data: 2001:610:1:40ba:145:100:185:15
106 tls_auth_name: "dnsovertls.sinodun.com"
107 tls_pubkey_pinset:
108 - digest: "sha256"
109 value: 62lKu9HsDVbyiPenApnc4sfmSYTHOVfFgL3pyB+cBL4=
110 - address_data: 2001:610:1:40ba:145:100:185:16
111 tls_auth_name: "dnsovertls1.sinodun.com"
112 tls_pubkey_pinset:
113 - digest: "sha256"
114 value: cE2ecALeE5B+urJhDrJlVFmf38cJLAvqekONvjvpqUA=
115 - address_data: 2a04:b900:0:100::38
116 tls_auth_name: "getdnsapi.net"
117 tls_pubkey_pinset:
118 - digest: "sha256"
119 value: foxZRnIh9gZpWnl+zEiKa0EJ2rdCGroMWm02gaxSc9Q=
120 The configuration items are as follow. Some take constant values from
122 the getdns library underlying stubby and further explanation of their
123 values may be found in the getdns documentation or at
124 http://www.getdnsapi.net
125 resolution_type resolution.
127 This must be set to GETDNS_RESOLUTION_STUB for historic reasons.
128 stubby will exit with an error if any other setting is used.
129 dns_transport_list list
131 Set the list of transport types to be used. For DNS Privacy this
132 must be set to GETDNS_TRANSPORT_TLS. Clear text transports are
133 GETDNS_TRANSPORT_TCP and GETDNS_TRANSPORT_UDP
134 tls_authentication type
136 Set the type of authentication required. For Strict Privacy,
137 this should be set to GETDNS_AUTHENTICATION_REQUIRED. For Oppor‐
138 tunistic mode, remove this setting or set to GETDNS_AUTHENTICA‐
139 TION_NONE. In Opportunistic mode authentication of the name‐
140 server is not required and fallback to clear text transports is
141 permitted if they are in dns_transport_list
142 tls_query_padding_blocksize blocksize
144 Use the EDNS0 padding option to pad DNS queries to hide their
145 size.
146 edns_client_subnet_private 0 or 1
148 If 1, use EDNS0 Client Subnet privacy so the client s ubnet is
149 not sent to authoritative servers.
150 idle_timeout timeout
152 Use an EDNS0 Keepalive idle timeout of timeout milliseconds
153 unless overridden by the server. This keeps idle TLS connections
154 open to avoid the overhead of opening a new connection for every
155 query.
156 round_robin_upstreams 0 or 1
158 If 1, round robin queries across all the configured upstream
159 servers. Without this option stubby will use each upstream
160 server sequentially until it becomes unavailable and then move
161 on to use the next.
162 upstream_recursive_servers server list
164 Specify the upstream servers that stubby is to use. Each item in
165 the list contains the following items:
166 address_data address
168 IPv4 or IPv6 address of the server.
169 tls_auth_name name
171 This is the authentication domain name that will be veri‐
172 fied against the presented certificate.
173 tls_pubkey_pinset pinset
175 The sha256 SPKI pinset for the server. This is also veri‐
176 fied against the presented certificate. This contains two
177 items:
178 digest type
180 The type of the key digest.
181 value keyval
183 The key value.
184
187 ~/.stubby.yml
188 /etc/stubby/stubby.yml
189
192 https://getdnsapi.net/
193 https://dnsprivacy.org/wiki/display/DP/DNS+Privacy+Daemon+-+Stubby
194 STUBBY(1)