Ubuntu Manpage: dnsviz-probe - issue diagnostic DNS queries

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 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 level
Set debug level to a value from 0 to 3, with increasing verbosity. The default is "2"
(informational-level output).

-r filename
Read diagnostic query input from the specified file, instead of querying servers. Specify "-" to
read from standard input.

-t 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 Use IPv4 only.

-6 Use IPv6 only.

-b 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 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 Do not verify the server-side TLS certificate for a HTTPS-based DNS looking glass that was
specified using -u.

-a 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 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 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 Query authoritative servers, rather than (the default) recursive servers.

-x 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 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 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 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 Use the NSID EDNS option with every DNS query issued.

-e 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
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 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 filename
Write the output to the specified file instead of to standard output, which is the default.

-p 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.

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXIT CODES

SEE ALSO