1dnsviz-probe(1)             General Commands Manual            dnsviz-probe(1)
2
3
4

NAME

6       dnsviz-probe - issue diagnostic DNS queries
7

SYNOPSIS

9       dnsviz probe [ options ] [ domain_name... ]
10

DESCRIPTION

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
18       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
23       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
28       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
34

OPTIONS

36       -f, --names-file filename
37              Read names from a file (one name per line), instead of from com‐
38              mand line.
39
40              If this option is used, then names may not be specified  on  the
41              command line.
42
43       -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
47       -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
51       -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
56       -4, --ipv4
57              Use IPv4 only.
58
59       -6, --ipv6
60              Use IPv6 only.
61
62       -b, --source-ip address
63              Use  the  specified  source  IPv4  or  IPv6 address for queries,
64              rather than detecting it.
65
66              This option can be used more than once to supply  both  an  IPv4
67              and an IPv6 address.
68
69              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
73       -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
78                     Examples:
79
80                            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
84                            Same, but use HTTP Basic authentication:
85                            http://username:password@www.example.com/cgi-
86                            bin/dnsviz-lg.cgi
87
88                            Issue  DNS  queries from host.example.com on which
89                            DNSViz is also installed.
90                            ssh://username@host.example.com
91
92              Note that a looking glass that uses https is only supported when
93              using python version 2.7.9 or greater.
94
95
96       -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
100       -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
106       -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
114       -s, --recursive-servers server[,server...]
115              Query the specified recursive  resolver(s),  rather  than  using
116              those specified in /etc/resolv.conf.
117
118              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
128              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
132              The following are example server values:
133
134
135                     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
142              This option cannot be used in conjunction with -A.
143
144
145       -A, --authoritative-analysis
146              Query authoritative servers, rather than (the default) recursive
147              servers.
148
149       -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
157              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
163                     dnsviz  probe  -A  -x  example.com:ns1.example.com  exam‐
164                     ple.com
165
166              the com servers will be queried for DS records for  example.com.
167              However, if the following is used:
168
169                     dnsviz  probe  -A  -x  example.com+:ns1.example.com exam‐
170                     ple.com
171
172              no queries are performed at com servers or above,  including  DS
173              records for example.com.
174
175              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
185                     dnsviz  probe  -A  -x  example.com:example.com.zone exam‐
186                     ple.com
187
188              This option may be used multiple times on the command line.
189
190              This option can only be used in conjunction with -A.
191
192       -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
198              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
206              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
210       -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
215              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
219
220                     31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE
221                     31589                         8                         2
222                     CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
223                     E576343C
224
225              would be specified by passing this value to -D:
226
227                     "31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE,
228                        31589                        8                       2
229                     CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
230                     E576343C"
231
232              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
236                     dnsviz probe -D example.com:dsset-example.com.
237
238              This option must be used in conjunction with the -N option.
239
240       -n, --nsid
241              Use the NSID EDNS option with every DNS query issued.
242
243       -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
249       -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
256              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
260       -E, --edns
261              Issue queries to check EDNS compatibility of servers.
262
263              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
268       -o, --output-file filename
269              Write  the  output  to the specified file instead of to standard
270              output, which is the default.
271
272       -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
277       -h     Display the usage and exit.
278
279

EXIT CODES

281       The exit codes are:
282
283       0      Program terminated normally.
284
285       1      Incorrect usage.
286
287       2      The network was unavailable for diagnostic queries.
288
289       3      There was an error processing the input or saving the output.
290
291       4      Program execution was interrupted, or an unknown error occurred.
292

SEE ALSO

294       dnsviz(1), dnsviz-grok(1),  dnsviz-graph(1),  dnsviz-print(1),  dnsviz-
295       query(1)
296
297
298
2990.9.4                             27 Sep 2021                  dnsviz-probe(1)
Impressum