.\"
.\" 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-2021 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-query 1 "11 Mar 2021" "0.9.3"
.SH NAME
dnsviz-query \- assess a DNS query
.SH SYNOPSIS
.B dnsviz
\fBquery\fR
[ \fB@\fR\fIserver\fR ]
[ \fB-b\fR \fIaddress\fR ]
[ \fB-c\fR \fIclass\fR ]
[ \fB-q\fR \fIname\fR ]
[ \fB-t\fR \fItype\fR ]
[ \fB-x\fR \fIaddr\fR ]
[ \fB-4\fR ] [ \fB-6\fR ]
[ \fIname\fR ]
[ \fItype\fR ]
[ \fIclass\fR ]
[ \fIqueryopt...\fR ]
.HP 4
\fBdnsviz query\fR [ \fB-h\fR ]
.HP 4
\fBdnsviz query\fR [ \fIglobal\-queryopt...\fR ] [ \fIquery...\fR ]
.SH DESCRIPTION
Issue queries for the names and types specified on the command line to DNS
servers, process the output, and present it to the user.  \fBdnsviz-query\fR
adopts a subset of the command-line options used by ISC's \fBdig(1)\fR but uses
\fBdnsviz-probe(1)\fR and \fBdnsviz-print(1)\fR to issue queries and assess the
results.  It is meant to be a shortcut for quickly assessing DNS queries and
diagnosing problems by invoking \fBdnsviz-probe(1)\fR and \fBdnsviz-print(1)\fR
with their most commonly used options and with a usage familiar similar to (but
not equal to) \fBdig(1)\fR.  For a more detailed analysis, revealing the nature
of errors, the user should use \fBdnsviz-probe(1)\fR, \fBdnsviz-grok(1)\fR,
\fBdnsviz-print(1)\fR, and \fBdnsviz-graph(1)\fR directly.

By default diagnostic queries are sent to recursive servers.  If no servers are
specified with "@", then the first server in /etc/resolv.conf is selected.
Note that unlike \fBdig(1)\fR \fBdnsviz-query(1)\fR only tries one server.

If \fB+trace\fR is used, the behavior changes, and the root authoritative
servers are first queried and referrals are followed downwards to the name(s)
in question.

To simplify usage a default root trusted key if none is specified on the
command line with \fB+trusted-key\fR.

.SH OPTIONS
.TP
.B -x \fIaddress\fR
Specify and IPv4 or IPv6 address for a reverse DNS (i.e., PTR) lookup.
.TP
.B -b \fIaddress\fR
Specify a 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 -q \fIname\fR
Specify a query name.
.TP
.B -t \fItype\fR
Specify a query type.
.TP
.B -c \fIclass\fR
Specify a query class (currently, only IN is supported; all other classes are ignored).
.TP
.B -4
Use IPv4 only.  If this is specified, then queries over IPv6 are not
attempted, unless \fB-6\fR is also specified.
.TP
.B -6
Use IPv6 only.  If this is specified, then queries over IPv4 are not
attempted, unless \fB-4\fR is also specified.

.SH QUERY OPTIONS
.TP
.B +[no]trace
Query authoritative servers, beginning at the DNS root, and follow referrals
downwards.  The default is to query a recursive server instead.
.TP
.B +trusted-key\fR=\fIfilename\fI
Specify a file that contains trusted keys for processing diagnostic queries.

The format of this file is master zone file format and should contain DNSKEY
records that correspond to one more trusted keys for one or more DNS zones.
.SH EXIT CODES
The exit codes are:
.IP 0
Program terminated normally.
.IP 1
Program execution was interrupted, or an unknown error occurred.
.SH SEE ALSO
.BR dnsviz(1),
.BR dnsviz-probe(1),
.BR dnsviz-grok(1),
.BR dnsviz-graph(1),
.BR dnsviz-print(1)