dnsviz-probe(1) User Commands dnsviz-probe(1)
dnsviz-probe - issue diagnostic DNS queries
dnsviz probe [ options ] [ domain_name... ]
Perform a series of diagnostic queries of specified names to either
recursive (default) or authoritative DNS servers, the results of
which are serialized into JSON format. Its output is used to assess
the health of DNS deployments, using, e.g., dnsviz-grok(1) and
dnsviz-graph(1).
Domain names to be processed may be passed either as command-line
arguments or in a file (using the -f option). When the -r option is
used, then the domain names can simply be implied using the
diagnostic query input.
Domain names are extracted from the diagnostic query input in
conjunction with -r only when -f is not used and no domain names are
supplied on the command line. If the -f option is used, then names
may not be specified on the command line.
The domain names passed as input are fully-qualified domain names,
such as example.com, www.example.com, _443._tcp.example.com,
1.2.0.192.in-addr.arpa, or 8.b.d.0.1.0.0.2.ip6.arpa. Because it is
implied that specified domain names are fully qualified, no trailing
dot is necessary.
-f, --names-file filename
Read names from a file (one name per line), instead of from
command line.
If this option is used, then names may not be specified on the
command line.
-d, --debug level
Set debug level to a value from 0 to 3, with increasing
verbosity. The default is "2" (informational-level output).
-r, --input-file filename
Read diagnostic query input from the specified file, instead
of querying servers. Specify "-" to read from standard input.
-t, --threads threads
Issue diagnostic queries for different names in parallel using
the specified number of threads. The default is to execute
diagnostic queries of names serially.
-4, --ipv4
Use IPv4 only.
-6, --ipv6
Use IPv6 only.
-b, --source-ip address
Use the specified source IPv4 or IPv6 address for queries,
rather than detecting it.
This option can be used more than once to supply both an IPv4
and an IPv6 address.
The use of this option is sometimes necessary when using a
dual-homed machine, and it is desirable to use the non-default
interface for queries.
-u, --looking-glass-url url
Issue queries through the DNS looking glass at the specified
URL (HTTP(S) or SSH). The queries will appear to come from
the looking glass rather than from the local machine.
Examples:
Issue DNS queries from www.example.com using the
cgi script dnsviz-lg.cgi:
http://www.example.com/cgi-bin/dnsviz-lg.cgi
Same, but use HTTP Basic authentication:
http://username:password@www.example.com/cgi-
bin/dnsviz-lg.cgi
Issue DNS queries from host.example.com on which
DNSViz is also installed.
ssh://username@host.example.com
Note that a looking glass that uses https is only supported
when using python version 2.7.9 or greater.
-k, --insecure
Do not verify the server-side TLS certificate for a HTTPS-
based DNS looking glass that was specified using -u.
-a, --ancestor ancestor
Issue diagnostic queries of each domain name through the
specified ancestor. The default for recursive mode is "."
(i.e., issue queries all the way to the root). The default
for authoritative mode (i.e., with -A) is the domain name
itself.
-R, --rr-types type[,type...]
Issue diagnostic queries for only the specified type(s) (e.g.,
A, AAAA). The default is to pick query types based on the
nature of the name (e.g., the number of labels, whether it is
a subdomain of .arpa, labels indicating association to TLSA or
SRV records, etc.) and whether there are NS records detected
(i.e., it is a zone).
-s, --recursive-servers server[,server...]
Query the specified recursive resolver(s), rather than using
those specified in /etc/resolv.conf.
Each server specified may either be an address (IPv4 or IPv6),
a domain name (which will be resolved to an address using the
standard resolution process), or both, using the syntax
name=address. Note that when both a name and an address are
specified (name=address), the name is only used for
identification purposes, and it doesn't matter whether the
name resolves to the corresponding address (or at all, for
that matter). IPv6 addresses must be wrapped in square
brackets, e.g., "[2001:db8::1]".
Each server value may optionally be suffixed with a numeric
port on which the server should be contacted. If not
specified, the standard DNS port, 53, is used.
The following are example server values:
ns1.example.com
ns1.example.com:5333
ns1.example.com=192.0.2.1
ns1.example.com=[2001:db8::1]
ns1.example.com=[2001:db8::1]:5333
192.0.2.1
This option cannot be used in conjunction with -A.
-A, --authoritative-analysis
Query authoritative servers, rather than (the default)
recursive servers.
-x, --authoritative-servers domain[+]:server[,server...]
Treat the specified servers as authoritative for a domain,
rather than learning authoritative servers by following
delegations. This option dictates which servers will be
queried for a domain, but the servers specified will not be
used to check NS or glue record consistency with the child;
for that behavior, see -N.
The default behavior is to identify and query servers
authoritative for ancestors of the specified domain, if other
options so dictate. However, if the domain ends in "+", then
queries aren't issued for servers authoritative for ancestor
domains of the domain. For example, with the following
command:
dnsviz probe -A -x example.com:ns1.example.com
example.com
the com servers will be queried for DS records for
example.com. However, if the following is used:
dnsviz probe -A -x example.com+:ns1.example.com
example.com
no queries are performed at com servers or above, including DS
records for example.com.
See -s for the syntax used for designating servers. However,
unlike the -s option, a zone file may be specified in lieu of
a server name and/or address, in which case an instance of
named(8) is started, the zone is served from that instance,
and queries for the domain are directed to the local instance
of named(8) serving that zone. For example, if
example.com.zone is a file containing the contents of the
example.com zone, the following command could be used to
specify that the zone file should be used:
dnsviz probe -A -x example.com:example.com.zone
example.com
This option may be used multiple times on the command line.
This option can only be used in conjunction with -A.
-N, --delegation-information domain:server[,server...]
Use the specified delegation information for a domain, i.e.,
the NS and glue records for the domain, which would be served
by the domain's parent. This is used for testing new
delegations or testing a potential change to a delegation.
This option has similar usage to that of the -x option. The
major difference is that the server names supplied comprise
the NS record set, and the addresses supplied represent glue
records. Thus if there are discrepancies between the
authoritative responses for the NS RRset and glue and what is
supplied on the command line, an error will be reported when
the output is subsequently assessed, e.g., using dnsviz-
grok(1).
In lieu of specifying the record data itself on the command
line, a file may be specified, which contains the delegation
NS and glue records for the domain.
-D, --ds domain:ds[,ds...]
Use the specified delegation signer (DS) records for a domain.
This is used in conjunction with the -N option for testing the
introduction or change of DS records.
The DS records themselves are specified using the textual
representation of their record data. For example the
following DS records for example.com:
31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE
31589 8 2
CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
E576343C
would be specified by passing this value to -D:
"31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE,
31589 8 2
CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
E576343C"
In lieu of specifying the record data itself on the command
line, a file may be specified, which contains the DS records.
For example:
dnsviz probe -D example.com:dsset-example.com.
This option must be used in conjunction with the -N option.
-n, --nsid
Use the NSID EDNS option with every DNS query issued.
-e, --client-subnet subnet[:prefix_len]
Use the EDNS Client Subnet option with every DNS query issued,
using the specified subnet and prefix_len as values. If
prefix is not specified, the prefix is the length of the
entire address.
-c, --cookie cookie
Send the specified DNS client cookie with every DNS query
issued. The value specified is for a client cookie only and
thus should be exactly 64 bits long. The value for the cookie
is specified using hexadecimal representation, e.g.,
deadbeef1580f00d.
If the -c option is not used, the default behavior is for a
DNS client cookie to be generated randomly to be sent with
queries. If an empty string is specified, then DNS cookies
are disabled.
-E, --edns
Issue queries to check EDNS compatibility of servers.
If this option is used, each server probed will be queried
with "future" EDNS settings, the respective responses can
later be assessed for proper behavior. These settings include
future EDNS versions (i.e., > 0), unknown options, and unknown
flags.
-o, --output-file filename
Write the output to the specified file instead of to standard
output, which is the default.
-p, --pretty-output
Output "pretty" instead of minimal JSON output, i.e., using
indentation and newlines. Note that this is the default when
the output is a TTY.
-h Display the usage and exit.
The exit codes are:
0 Program terminated normally.
1 Incorrect usage.
2 The network was unavailable for diagnostic queries.
3 There was an error processing the input or saving the output.
4 Program execution was interrupted, or an unknown error
occurred.
5 No recursive resolvers found in resolv.conf nor given on
command line.
dnsviz(1), dnsviz-grok(1), dnsviz-graph(1), dnsviz-print(1),
dnsviz-query(1)
0.11.1 21 April 2025 dnsviz-probe(1)
NAME
dnsviz-probe - issue diagnostic DNS queries
SYNOPSIS
dnsviz probe [ options ] [ domain_name... ]
DESCRIPTION
Perform a series of diagnostic queries of specified names to either
recursive (default) or authoritative DNS servers, the results of
which are serialized into JSON format. Its output is used to assess
the health of DNS deployments, using, e.g., dnsviz-grok(1) and
dnsviz-graph(1).
Domain names to be processed may be passed either as command-line
arguments or in a file (using the -f option). When the -r option is
used, then the domain names can simply be implied using the
diagnostic query input.
Domain names are extracted from the diagnostic query input in
conjunction with -r only when -f is not used and no domain names are
supplied on the command line. If the -f option is used, then names
may not be specified on the command line.
The domain names passed as input are fully-qualified domain names,
such as example.com, www.example.com, _443._tcp.example.com,
1.2.0.192.in-addr.arpa, or 8.b.d.0.1.0.0.2.ip6.arpa. Because it is
implied that specified domain names are fully qualified, no trailing
dot is necessary.
OPTIONS
-f, --names-file filename
Read names from a file (one name per line), instead of from
command line.
If this option is used, then names may not be specified on the
command line.
-d, --debug level
Set debug level to a value from 0 to 3, with increasing
verbosity. The default is "2" (informational-level output).
-r, --input-file filename
Read diagnostic query input from the specified file, instead
of querying servers. Specify "-" to read from standard input.
-t, --threads threads
Issue diagnostic queries for different names in parallel using
the specified number of threads. The default is to execute
diagnostic queries of names serially.
-4, --ipv4
Use IPv4 only.
-6, --ipv6
Use IPv6 only.
-b, --source-ip address
Use the specified source IPv4 or IPv6 address for queries,
rather than detecting it.
This option can be used more than once to supply both an IPv4
and an IPv6 address.
The use of this option is sometimes necessary when using a
dual-homed machine, and it is desirable to use the non-default
interface for queries.
-u, --looking-glass-url url
Issue queries through the DNS looking glass at the specified
URL (HTTP(S) or SSH). The queries will appear to come from
the looking glass rather than from the local machine.
Examples:
Issue DNS queries from www.example.com using the
cgi script dnsviz-lg.cgi:
http://www.example.com/cgi-bin/dnsviz-lg.cgi
Same, but use HTTP Basic authentication:
http://username:password@www.example.com/cgi-
bin/dnsviz-lg.cgi
Issue DNS queries from host.example.com on which
DNSViz is also installed.
ssh://username@host.example.com
Note that a looking glass that uses https is only supported
when using python version 2.7.9 or greater.
-k, --insecure
Do not verify the server-side TLS certificate for a HTTPS-
based DNS looking glass that was specified using -u.
-a, --ancestor ancestor
Issue diagnostic queries of each domain name through the
specified ancestor. The default for recursive mode is "."
(i.e., issue queries all the way to the root). The default
for authoritative mode (i.e., with -A) is the domain name
itself.
-R, --rr-types type[,type...]
Issue diagnostic queries for only the specified type(s) (e.g.,
A, AAAA). The default is to pick query types based on the
nature of the name (e.g., the number of labels, whether it is
a subdomain of .arpa, labels indicating association to TLSA or
SRV records, etc.) and whether there are NS records detected
(i.e., it is a zone).
-s, --recursive-servers server[,server...]
Query the specified recursive resolver(s), rather than using
those specified in /etc/resolv.conf.
Each server specified may either be an address (IPv4 or IPv6),
a domain name (which will be resolved to an address using the
standard resolution process), or both, using the syntax
name=address. Note that when both a name and an address are
specified (name=address), the name is only used for
identification purposes, and it doesn't matter whether the
name resolves to the corresponding address (or at all, for
that matter). IPv6 addresses must be wrapped in square
brackets, e.g., "[2001:db8::1]".
Each server value may optionally be suffixed with a numeric
port on which the server should be contacted. If not
specified, the standard DNS port, 53, is used.
The following are example server values:
ns1.example.com
ns1.example.com:5333
ns1.example.com=192.0.2.1
ns1.example.com=[2001:db8::1]
ns1.example.com=[2001:db8::1]:5333
192.0.2.1
This option cannot be used in conjunction with -A.
-A, --authoritative-analysis
Query authoritative servers, rather than (the default)
recursive servers.
-x, --authoritative-servers domain[+]:server[,server...]
Treat the specified servers as authoritative for a domain,
rather than learning authoritative servers by following
delegations. This option dictates which servers will be
queried for a domain, but the servers specified will not be
used to check NS or glue record consistency with the child;
for that behavior, see -N.
The default behavior is to identify and query servers
authoritative for ancestors of the specified domain, if other
options so dictate. However, if the domain ends in "+", then
queries aren't issued for servers authoritative for ancestor
domains of the domain. For example, with the following
command:
dnsviz probe -A -x example.com:ns1.example.com
example.com
the com servers will be queried for DS records for
example.com. However, if the following is used:
dnsviz probe -A -x example.com+:ns1.example.com
example.com
no queries are performed at com servers or above, including DS
records for example.com.
See -s for the syntax used for designating servers. However,
unlike the -s option, a zone file may be specified in lieu of
a server name and/or address, in which case an instance of
named(8) is started, the zone is served from that instance,
and queries for the domain are directed to the local instance
of named(8) serving that zone. For example, if
example.com.zone is a file containing the contents of the
example.com zone, the following command could be used to
specify that the zone file should be used:
dnsviz probe -A -x example.com:example.com.zone
example.com
This option may be used multiple times on the command line.
This option can only be used in conjunction with -A.
-N, --delegation-information domain:server[,server...]
Use the specified delegation information for a domain, i.e.,
the NS and glue records for the domain, which would be served
by the domain's parent. This is used for testing new
delegations or testing a potential change to a delegation.
This option has similar usage to that of the -x option. The
major difference is that the server names supplied comprise
the NS record set, and the addresses supplied represent glue
records. Thus if there are discrepancies between the
authoritative responses for the NS RRset and glue and what is
supplied on the command line, an error will be reported when
the output is subsequently assessed, e.g., using dnsviz-
grok(1).
In lieu of specifying the record data itself on the command
line, a file may be specified, which contains the delegation
NS and glue records for the domain.
-D, --ds domain:ds[,ds...]
Use the specified delegation signer (DS) records for a domain.
This is used in conjunction with the -N option for testing the
introduction or change of DS records.
The DS records themselves are specified using the textual
representation of their record data. For example the
following DS records for example.com:
31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE
31589 8 2
CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
E576343C
would be specified by passing this value to -D:
"31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE,
31589 8 2
CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03
E576343C"
In lieu of specifying the record data itself on the command
line, a file may be specified, which contains the DS records.
For example:
dnsviz probe -D example.com:dsset-example.com.
This option must be used in conjunction with the -N option.
-n, --nsid
Use the NSID EDNS option with every DNS query issued.
-e, --client-subnet subnet[:prefix_len]
Use the EDNS Client Subnet option with every DNS query issued,
using the specified subnet and prefix_len as values. If
prefix is not specified, the prefix is the length of the
entire address.
-c, --cookie cookie
Send the specified DNS client cookie with every DNS query
issued. The value specified is for a client cookie only and
thus should be exactly 64 bits long. The value for the cookie
is specified using hexadecimal representation, e.g.,
deadbeef1580f00d.
If the -c option is not used, the default behavior is for a
DNS client cookie to be generated randomly to be sent with
queries. If an empty string is specified, then DNS cookies
are disabled.
-E, --edns
Issue queries to check EDNS compatibility of servers.
If this option is used, each server probed will be queried
with "future" EDNS settings, the respective responses can
later be assessed for proper behavior. These settings include
future EDNS versions (i.e., > 0), unknown options, and unknown
flags.
-o, --output-file filename
Write the output to the specified file instead of to standard
output, which is the default.
-p, --pretty-output
Output "pretty" instead of minimal JSON output, i.e., using
indentation and newlines. Note that this is the default when
the output is a TTY.
-h Display the usage and exit.
EXIT CODES
The exit codes are:
0 Program terminated normally.
1 Incorrect usage.
2 The network was unavailable for diagnostic queries.
3 There was an error processing the input or saving the output.
4 Program execution was interrupted, or an unknown error
occurred.
5 No recursive resolvers found in resolv.conf nor given on
command line.
SEE ALSO
dnsviz(1), dnsviz-grok(1), dnsviz-graph(1), dnsviz-print(1),
dnsviz-query(1)
0.11.1 21 April 2025 dnsviz-probe(1)