path: root/doc/man/dnsviz-probe.1

.\"
.\" This file is a part of DNSViz, a tool suite for DNS/DNSSEC monitoring,
.\" analysis, and visualization.
.\" Created by Casey Deccio (casey@deccio.net)
.\"
.\" Copyright 2015-2016 VeriSign, Inc.
.\"
.\" Copyright 2016-2019 Casey Deccio
.\"
.\" DNSViz is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" DNSViz is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with DNSViz.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsviz-probe 1 "25 Jan 2019" "0.8.1"
.SH NAME
dnsviz-probe \- issue diagnostic DNS queries
.SH SYNOPSIS
.B dnsviz
\fBprobe\fR
[ \fIoptions\fR ]
[ \fIdomain_name...\fR ]
.SH 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., \fBdnsviz-grok(1)\fR and \fBdnsviz-graph(1)\fR.

Domain names to be processed may be passed either as command-line arguments or
in a file (using the \fB-f\fR option).  When the \fB-r\fR 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
\fB-r\fR only when \fB-f\fR is not used and no domain names are supplied on the
command line.  If the \fB-f\fR 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.

.SH OPTIONS
.TP
.B -f, --names-file \fIfilename\fR
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.
.TP
.B -d, --debug \fIlevel\fR
Set debug level to a value from 0 to 3, with increasing verbosity.  The default
is "2" (informational-level output).
.TP
.B -r, --input-file \fIfilename\fR
Read diagnostic query input from the specified file, instead of querying
servers.  Specify "-" to read from standard input.
.TP
.B -t, --threads \fIthreads\fR
Issue diagnostic queries for different names in parallel using the specified
number of threads.  The default is to execute diagnostic queries of names
serially.
.TP
.B -4, --ipv4
Use IPv4 only.
.TP
.B -6, --ipv6
Use IPv6 only.
.TP
.B -b, --source-ip \fIaddress\fR
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.
.TP
.B -u, --looking-glass-url \fIurl\fR
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.

.RS
.RS
Examples:
.RS
.P
.PD 0
Issue DNS queries from www.example.com using the cgi script dnsviz-lg.cgi:
.P
http://www.example.com/cgi-bin/dnsviz-lg.cgi
.PD
.P
.PD 0
Same, but use HTTP Basic authentication:
.P
http://username:password@www.example.com/cgi-bin/dnsviz-lg.cgi
.PD
.P
.PD 0
Issue DNS queries from host.example.com on which DNSViz is also installed.
.P
ssh://username@host.example.com
.PD
.RE
.P
.RE
Note that a looking glass that uses https is only supported when using python
version 2.7.9 or greater.
.RE

.TP
.B -k, --insecure
Do not verify the server-side TLS certificate for a HTTPS-based DNS looking
glass that was specified using \fB-u\fR.
.TP
.B -a, --ancestor \fIancestor\fR
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 \fB-A\fR) is the domain
name itself.
.TP
.B -R, --rr-types \fItype\fR[,\fItype...\fR]
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).
.TP
.B -s, --recursive-servers \fIserver\fR[,\fIserver...\fR]
Query the specified recursive resolver(s), rather than using those specified in
\fI/etc/resolv.conf\fR.

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 \fIname\fR\fB=\fR\fIaddress\fR.  Note that when both a name and an
address are specified (\fIname\fR\fB=\fR\fIaddress\fR), 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:

.RS
.RS
.P
.PD 0
ns1.example.com
.P
ns1.example.com:5333
.P
ns1.example.com=192.0.2.1
.P
ns1.example.com=[2001:db8::1]
.P
ns1.example.com=[2001:db8::1]:5333
.P
192.0.2.1
.PD
.RE

This option cannot be used in conjunction with \fB-A\fR.
.RE

.TP
.B -A, --authoritative-analysis
Query authoritative servers, rather than (the default) recursive servers.
.TP
.B -x, --authoritative-servers \fIdomain\fR[\fB+\fR]\fB:\fR\fIserver\fR[,\fIserver...\fR]
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 \fB-N\fR.

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:

.RS
.RS
dnsviz probe -A -x example.com:ns1.example.com example.com
.RE

the com servers will be queried for DS records for example.com.  However, if
the following is used:

.RS
dnsviz probe -A -x example.com+:ns1.example.com example.com
.RE

no queries are performed at com servers or above, including DS records for
example.com.

See \fB-s\fR for the syntax used for designating servers.  However, unlike the
\fB-s\fR option, a zone file may be specified in lieu of a server name and/or
address, in which case an instance of \fBnamed(8)\fR is started, the zone is
served from that instance, and queries for the domain are directed to the local
instance of \fBnamed(8)\fR 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:

.RS
dnsviz probe -A -x example.com:example.com.zone example.com
.RE

This option may be used multiple times on the command line.

This option can only be used in conjunction with \fB-A\fR.
.RE
.TP
.B -N, --delegation-information \fIdomain\fR\fB:\fR\fIserver\fR[,\fIserver...\fR]
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 \fB-x\fR 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 \fBdnsviz-grok(1)\fR.

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.
.TP
.B -D, --ds \fIdomain\fR\fB:\fR\fIds\fR[,\fIds...\fR]
Use the specified delegation signer (DS) records for a domain.  This is used
in conjunction with the \fB-N\fR 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:

.RS
.RS
.P
.PD 0
31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE
.P
31589 8 2 CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03 E576343C
.PD
.RE

would be specified by passing this value to \fB-D\fR:

.RS
.PD 0
"31589 8 1 3490A6806D47F17A34C29E2CE80E8A999FFBE4BE,
.P
   31589 8 2 CDE0D742D6998AA554A92D890F8184C698CFAC8A26FA59875A990C03 E576343C"
.PD
.RE

In lieu of specifying the record data itself on the command line, a file may be
specified, which contains the DS records.  For example:

.RS
dnsviz probe -D example.com:dsset-example.com.
.RE

This option must be used in conjunction with the \fB-N\fR option.
.RE
.TP
.B -n, --nsid
Use the NSID EDNS option with every DNS query issued.
.TP
.B -e, --client-subnet \fIsubnet\fR[\fB:\fR\fIprefix_len\fR]
Use the EDNS Client Subnet option with every DNS query issued, using the
specified \fIsubnet\fR and \fIprefix_len\fR as values.  If \fIprefix\fR is not
specified, the prefix is the length of the entire address.
.TP
.B -c, --cookie \fIcookie\fR
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 \fB-c\fR 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.
.TP
.B -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.
.TP
.B -o, --output-file \fIfilename\fR
Write the output to the specified file instead of to standard output, which
is the default.
.TP
.B -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.
.TP
.B -h
Display the usage and exit.

.SH EXIT CODES
The exit codes are:
.IP 0
Program terminated normally.
.IP 1
Incorrect usage.
.IP 2
The network was unavailable for diagnostic queries.
.IP 3
There was an error processing the input or saving the output.
.IP 4
Program execution was interrupted, or an unknown error occurred.
.SH SEE ALSO
.BR dnsviz(1),
.BR dnsviz-grok(1),
.BR dnsviz-graph(1),
.BR dnsviz-print(1),
.BR dnsviz-query(1)