1dnsviz-probe(1) General Commands Manual dnsviz-probe(1)
2
6 dnsviz-probe - issue diagnostic DNS queries
7
9 dnsviz probe [ options ] [ domain_name... ]
10
12 Perform a series of diagnostic queries of specified names to either re‐
13 cursive (default) or authoritative DNS servers, the results of which
14 are serialized into JSON format. Its output is used to assess the
15 health of DNS deployments, using, e.g., dnsviz-grok(1) and dnsviz-
16 graph(1).
17 Domain names to be processed may be passed either as command-line argu‐
19 ments or in a file (using the -f option). When the -r option is used,
20 then the domain names can simply be implied using the diagnostic query
21 input.
22 Domain names are extracted from the diagnostic query input in conjunc‐
24 tion with -r only when -f is not used and no domain names are supplied
25 on the command line. If the -f option is used, then names may not be
26 specified on the command line.
27 The domain names passed as input are fully-qualified domain names, such
29 as example.com, www.example.com, _443._tcp.example.com, 1.2.0.192.in-
30 addr.arpa, or 8.b.d.0.1.0.0.2.ip6.arpa. Because it is implied that
31 specified domain names are fully qualified, no trailing dot is neces‐
32 sary.
33
36 -f, --names-file filename
37 Read names from a file (one name per line), instead of from com‐
38 mand line.
39 If this option is used, then names may not be specified on the
41 command line.
42 -d, --debug level
44 Set debug level to a value from 0 to 3, with increasing ver‐
45 bosity. The default is "2" (informational-level output).
46 -r, --input-file filename
48 Read diagnostic query input from the specified file, instead of
49 querying servers. Specify "-" to read from standard input.
50 -t, --threads threads
52 Issue diagnostic queries for different names in parallel using
53 the specified number of threads. The default is to execute di‐
54 agnostic queries of names serially.
55 -4, --ipv4
57 Use IPv4 only.
58 -6, --ipv6
60 Use IPv6 only.
61 -b, --source-ip address
63 Use the specified source IPv4 or IPv6 address for queries,
64 rather than detecting it.
65 This option can be used more than once to supply both an IPv4
67 and an IPv6 address.
68 The use of this option is sometimes necessary when using a dual-
70 homed machine, and it is desirable to use the non-default inter‐
71 face for queries.
72 -u, --looking-glass-url url
74 Issue queries through the DNS looking glass at the specified URL
75 (HTTP(S) or SSH). The queries will appear to come from the
76 looking glass rather than from the local machine.
77 Examples:
79 Issue DNS queries from www.example.com using the
81 cgi script dnsviz-lg.cgi:
82 http://www.example.com/cgi-bin/dnsviz-lg.cgi
83 Same, but use HTTP Basic authentication:
85 http://username:password@www.example.com/cgi-
86 bin/dnsviz-lg.cgi
87 Issue DNS queries from host.example.com on which
89 DNSViz is also installed.
90 ssh://username@host.example.com
91 Note that a looking glass that uses https is only supported when
93 using python version 2.7.9 or greater.
94 -k, --insecure
97 Do not verify the server-side TLS certificate for a HTTPS-based
98 DNS looking glass that was specified using -u.
99 -a, --ancestor ancestor
101 Issue diagnostic queries of each domain name through the speci‐
102 fied ancestor. The default for recursive mode is "." (i.e., is‐
103 sue queries all the way to the root). The default for authori‐
104 tative mode (i.e., with -A) is the domain name itself.
105 -R, --rr-types type[,type...]
107 Issue diagnostic queries for only the specified type(s) (e.g.,
108 A, AAAA). The default is to pick query types based on the na‐
109 ture of the name (e.g., the number of labels, whether it is a
110 subdomain of .arpa, labels indicating association to TLSA or SRV
111 records, etc.) and whether there are NS records detected (i.e.,
112 it is a zone).
113 -s, --recursive-servers server[,server...]
115 Query the specified recursive resolver(s), rather than using
116 those specified in /etc/resolv.conf.
117 Each server specified may either be an address (IPv4 or IPv6), a
119 domain name (which will be resolved to an address using the
120 standard resolution process), or both, using the syntax name=ad‐
121 dress. Note that when both a name and an address are specified
122 (name=address), the name is only used for identification pur‐
123 poses, and it doesn't matter whether the name resolves to the
124 corresponding address (or at all, for that matter). IPv6 ad‐
125 dresses must be wrapped in square brackets, e.g.,
126 "[2001:db8::1]".
127 Each server value may optionally be suffixed with a numeric port
129 on which the server should be contacted. If not specified, the
130 standard DNS port, 53, is used.
131 The following are example server values:
133 ns1.example.com
136 ns1.example.com:5333
137 ns1.example.com=192.0.2.1
138 ns1.example.com=[2001:db8::1]
139 ns1.example.com=[2001:db8::1]:5333
140 192.0.2.1
141 This option cannot be used in conjunction with -A.
143 -A, --authoritative-analysis
146 Query authoritative servers, rather than (the default) recursive
147 servers.
148 -x, --authoritative-servers domain[+]:server[,server...]
150 Treat the specified servers as authoritative for a domain,
151 rather than learning authoritative servers by following delega‐
152 tions. This option dictates which servers will be queried for a
153 domain, but the servers specified will not be used to check NS
154 or glue record consistency with the child; for that behavior,
155 see -N.
156 The default behavior is to identify and query servers authorita‐
158 tive for ancestors of the specified domain, if other options so
159 dictate. However, if the domain ends in "+", then queries
160 aren't issued for servers authoritative for ancestor domains of
161 the domain. For example, with the following command:
162 dnsviz probe -A -x example.com:ns1.example.com exam‐
164 ple.com
165 the com servers will be queried for DS records for example.com.
167 However, if the following is used:
168 dnsviz probe -A -x example.com+:ns1.example.com exam‐
170 ple.com
171 no queries are performed at com servers or above, including DS
173 records for example.com.
174 See -s for the syntax used for designating servers. However,
176 unlike the -s option, a zone file may be specified in lieu of a
177 server name and/or address, in which case an instance of
178 named(8) is started, the zone is served from that instance, and
179 queries for the domain are directed to the local instance of
180 named(8) serving that zone. For example, if example.com.zone is
181 a file containing the contents of the example.com zone, the fol‐
182 lowing command could be used to specify that the zone file
183 should be used:
184 dnsviz probe -A -x example.com:example.com.zone exam‐
186 ple.com
187 This option may be used multiple times on the command line.
189 This option can only be used in conjunction with -A.
191 -N, --delegation-information domain:server[,server...]
193 Use the specified delegation information for a domain, i.e., the
194 NS and glue records for the domain, which would be served by the
195 domain's parent. This is used for testing new delegations or
196 testing a potential change to a delegation.
197 This option has similar usage to that of the -x option. The ma‐
199 jor difference is that the server names supplied comprise the NS
200 record set, and the addresses supplied represent glue records.
201 Thus if there are discrepancies between the authoritative re‐
202 sponses for the NS RRset and glue and what is supplied on the
203 command line, an error will be reported when the output is sub‐
204 sequently assessed, e.g., using dnsviz-grok(1).
205 In lieu of specifying the record data itself on the command
207 line, a file may be specified, which contains the delegation NS
208 and glue records for the domain.
209 -D, --ds domain:ds[,ds...]
211 Use the specified delegation signer (DS) records for a domain.
212 This is used in conjunction with the -N option for testing the
213 introduction or change of DS records.
214 The DS records themselves are specified using the the textual
216 representation of their record data. For example the following
217 DS records for example.com:
218 31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE
221 31589 8 2
222 CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
223 E576343C
224 would be specified by passing this value to -D:
226 "31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE,
228 31589 8 2
229 CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
230 E576343C"
231 In lieu of specifying the record data itself on the command
233 line, a file may be specified, which contains the DS records.
234 For example:
235 dnsviz probe -D example.com:dsset-example.com.
237 This option must be used in conjunction with the -N option.
239 -n, --nsid
241 Use the NSID EDNS option with every DNS query issued.
242 -e, --client-subnet subnet[:prefix_len]
244 Use the EDNS Client Subnet option with every DNS query issued,
245 using the specified subnet and prefix_len as values. If prefix
246 is not specified, the prefix is the length of the entire ad‐
247 dress.
248 -c, --cookie cookie
250 Send the specified DNS client cookie with every DNS query is‐
251 sued. The value specified is for a client cookie only and thus
252 should be exactly 64 bits long. The value for the cookie is
253 specified using hexadecimal representation, e.g., dead‐
254 beef1580f00d.
255 If the -c option is not used, the default behavior is for a DNS
257 client cookie to be generated randomly to be sent with queries.
258 If an empty string is specified, then DNS cookies are disabled.
259 -E, --edns
261 Issue queries to check EDNS compatibility of servers.
262 If this option is used, each server probed will be queried with
264 "future" EDNS settings, the respective responses can later be
265 assessed for proper behavior. These settings include future
266 EDNS versions (i.e., > 0), unknown options, and unknown flags.
267 -o, --output-file filename
269 Write the output to the specified file instead of to standard
270 output, which is the default.
271 -p, --pretty-output
273 Output "pretty" instead of minimal JSON output, i.e., using in‐
274 dentation and newlines. Note that this is the default when the
275 output is a TTY.
276 -h Display the usage and exit.
278
281 The exit codes are:
282 0 Program terminated normally.
284 1 Incorrect usage.
286 2 The network was unavailable for diagnostic queries.
288 3 There was an error processing the input or saving the output.
290 4 Program execution was interrupted, or an unknown error occurred.
292
294 dnsviz(1), dnsviz-grok(1), dnsviz-graph(1), dnsviz-print(1), dnsviz-
295 query(1)
2960.9.3 11 Mar 2021 dnsviz-probe(1)