summaryrefslogtreecommitdiffstats
path: root/bin/delv/delv.rst
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--bin/delv/delv.rst364
1 files changed, 364 insertions, 0 deletions
diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst
new file mode 100644
index 0000000..bf6cce1
--- /dev/null
+++ b/bin/delv/delv.rst
@@ -0,0 +1,364 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0. If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. iscman:: delv
+.. program:: delv
+.. _man_delv:
+
+delv - DNS lookup and validation utility
+----------------------------------------
+
+Synopsis
+~~~~~~~~
+
+:program:`delv` [@server] [ [**-4**] | [**-6**] ] [**-a** anchor-file] [**-b** address] [**-c** class] [**-d** level] [**-i**] [**-m**] [**-p** port#] [**-q** name] [**-t** type] [**-x** addr] [name] [type] [class] [queryopt...]
+
+:program:`delv` [**-h**]
+
+:program:`delv` [**-v**]
+
+:program:`delv` [queryopt...] [query...]
+
+Description
+~~~~~~~~~~~
+
+:program:`delv` is a tool for sending DNS queries and validating the results,
+using the same internal resolver and validator logic as :iscman:`named`.
+
+:program:`delv` sends to a specified name server all queries needed to
+fetch and validate the requested data; this includes the original
+requested query, subsequent queries to follow CNAME or DNAME chains,
+queries for DNSKEY, and DS records to establish a chain of trust for
+DNSSEC validation. It does not perform iterative resolution, but
+simulates the behavior of a name server configured for DNSSEC validating
+and forwarding.
+
+By default, responses are validated using the built-in DNSSEC trust anchor
+for the root zone ("."). Records returned by :program:`delv` are either fully
+validated or were not signed. If validation fails, an explanation of the
+failure is included in the output; the validation process can be traced
+in detail. Because :program:`delv` does not rely on an external server to carry
+out validation, it can be used to check the validity of DNS responses in
+environments where local name servers may not be trustworthy.
+
+Unless it is told to query a specific name server, :program:`delv` tries
+each of the servers listed in ``/etc/resolv.conf``. If no usable server
+addresses are found, :program:`delv` sends queries to the localhost
+addresses (127.0.0.1 for IPv4, ::1 for IPv6).
+
+When no command-line arguments or options are given, :program:`delv`
+performs an NS query for "." (the root zone).
+
+Simple Usage
+~~~~~~~~~~~~
+
+A typical invocation of :program:`delv` looks like:
+
+::
+
+ delv @server name type
+
+where:
+
+.. option:: server
+
+ is the name or IP address of the name server to query. This can be an
+ IPv4 address in dotted-decimal notation or an IPv6 address in
+ colon-delimited notation. When the supplied ``server`` argument is a
+ hostname, :program:`delv` resolves that name before querying that name
+ server (note, however, that this initial lookup is *not* validated by
+ DNSSEC).
+
+ If no ``server`` argument is provided, :program:`delv` consults
+ ``/etc/resolv.conf``; if an address is found there, it queries the
+ name server at that address. If either of the :option:`-4` or :option:`-6`
+ options is in use, then only addresses for the corresponding
+ transport are tried. If no usable addresses are found, :program:`delv`
+ sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1
+ for IPv6).
+
+.. option:: name
+
+ is the domain name to be looked up.
+
+.. option:: type
+
+ indicates what type of query is required - ANY, A, MX, etc.
+ ``type`` can be any valid query type. If no ``type`` argument is
+ supplied, :program:`delv` performs a lookup for an A record.
+
+Options
+~~~~~~~
+
+.. option:: -a anchor-file
+
+ This option specifies a file from which to read DNSSEC trust anchors. The default
+ is |bind_keys|, which is included with BIND 9 and contains one
+ or more trust anchors for the root zone (".").
+
+ Keys that do not match the root zone name are ignored. An alternate
+ key name can be specified using the :option:`+root` option.
+
+ Note: When reading the trust anchor file, :program:`delv` treats ``trust-anchors``,
+ ``initial-key``, and ``static-key`` identically. That is, for a managed key,
+ it is the *initial* key that is trusted; :rfc:`5011` key management is not
+ supported. :program:`delv` does not consult the managed-keys database maintained by
+ :iscman:`named`, which means that if either of the keys in |bind_keys| is
+ revoked and rolled over, |bind_keys| must be updated to
+ use DNSSEC validation in :program:`delv`.
+
+.. option:: -b address
+
+ This option sets the source IP address of the query to ``address``. This must be
+ a valid address on one of the host's network interfaces, or ``0.0.0.0``,
+ or ``::``. An optional source port may be specified by appending
+ ``#<port>``
+
+.. option:: -c class
+
+ This option sets the query class for the requested data. Currently, only class
+ "IN" is supported in :program:`delv` and any other value is ignored.
+
+.. option:: -d level
+
+ This option sets the systemwide debug level to ``level``. The allowed range is
+ from 0 to 99. The default is 0 (no debugging). Debugging traces from
+ :program:`delv` become more verbose as the debug level increases. See the
+ :option:`+mtrace`, :option:`+rtrace`, and :option:`+vtrace` options below for
+ additional debugging details.
+
+.. option:: -h
+
+ This option displays the :program:`delv` help usage output and exits.
+
+.. option:: -i
+
+ This option sets insecure mode, which disables internal DNSSEC validation. (Note,
+ however, that this does not set the CD bit on upstream queries. If the
+ server being queried is performing DNSSEC validation, then it does
+ not return invalid data; this can cause :program:`delv` to time out. When it
+ is necessary to examine invalid data to debug a DNSSEC problem, use
+ :option:`dig +cd`.)
+
+.. option:: -m
+
+ This option enables memory usage debugging.
+
+.. option:: -p port#
+
+ This option specifies a destination port to use for queries, instead of the
+ standard DNS port number 53. This option is used with a name
+ server that has been configured to listen for queries on a
+ non-standard port number.
+
+.. option:: -q name
+
+ This option sets the query name to ``name``. While the query name can be
+ specified without using the :option:`-q` option, it is sometimes necessary to
+ disambiguate names from types or classes (for example, when looking
+ up the name "ns", which could be misinterpreted as the type NS, or
+ "ch", which could be misinterpreted as class CH).
+
+.. option:: -t type
+
+ This option sets the query type to ``type``, which can be any valid query type
+ supported in BIND 9 except for zone transfer types AXFR and IXFR. As
+ with :option:`-q`, this is useful to distinguish query-name types or classes
+ when they are ambiguous. It is sometimes necessary to disambiguate
+ names from types.
+
+ The default query type is "A", unless the :option:`-x` option is supplied
+ to indicate a reverse lookup, in which case it is "PTR".
+
+.. option:: -v
+
+ This option prints the :program:`delv` version and exits.
+
+.. option:: -x addr
+
+ This option performs a reverse lookup, mapping an address to a name. ``addr``
+ is an IPv4 address in dotted-decimal notation, or a colon-delimited
+ IPv6 address. When :option:`-x` is used, there is no need to provide the
+ ``name`` or ``type`` arguments; :program:`delv` automatically performs a
+ lookup for a name like ``11.12.13.10.in-addr.arpa`` and sets the
+ query type to PTR. IPv6 addresses are looked up using nibble format
+ under the IP6.ARPA domain.
+
+.. option:: -4
+
+ This option forces :program:`delv` to only use IPv4.
+
+.. option:: -6
+
+ This option forces :program:`delv` to only use IPv6.
+
+Query Options
+~~~~~~~~~~~~~
+
+:program:`delv` provides a number of query options which affect the way results
+are displayed, and in some cases the way lookups are performed.
+
+Each query option is identified by a keyword preceded by a plus sign
+(``+``). Some keywords set or reset an option. These may be preceded by
+the string ``no`` to negate the meaning of that keyword. Other keywords
+assign values to options like the timeout interval. They have the form
+``+keyword=value``. The query options are:
+
+.. option:: +cdflag, +nocdflag
+
+ This option controls whether to set the CD (checking disabled) bit in queries
+ sent by :program:`delv`. This may be useful when troubleshooting DNSSEC
+ problems from behind a validating resolver. A validating resolver
+ blocks invalid responses, making it difficult to retrieve them
+ for analysis. Setting the CD flag on queries causes the resolver
+ to return invalid responses, which :program:`delv` can then validate
+ internally and report the errors in detail.
+
+.. option:: +class, +noclass
+
+ This option controls whether to display the CLASS when printing a record. The
+ default is to display the CLASS.
+
+.. option:: +ttl, +nottl
+
+ This option controls whether to display the TTL when printing a record. The
+ default is to display the TTL.
+
+.. option:: +rtrace, +nortrace
+
+ This option toggles resolver fetch logging. This reports the name and type of each
+ query sent by :program:`delv` in the process of carrying out the resolution
+ and validation process, including the original query
+ and all subsequent queries to follow CNAMEs and to establish a chain
+ of trust for DNSSEC validation.
+
+ This is equivalent to setting the debug level to 1 in the "resolver"
+ logging category. Setting the systemwide debug level to 1 using the
+ :option:`-d` option produces the same output, but affects other
+ logging categories as well.
+
+.. option:: +mtrace, +nomtrace
+
+ This option toggles message logging. This produces a detailed dump of the
+ responses received by :program:`delv` in the process of carrying out the
+ resolution and validation process.
+
+ This is equivalent to setting the debug level to 10 for the "packets"
+ module of the "resolver" logging category. Setting the systemwide
+ debug level to 10 using the :option:`-d` option produces the same
+ output, but affects other logging categories as well.
+
+.. option:: +vtrace, +novtrace
+
+ This option toggles validation logging. This shows the internal process of the
+ validator as it determines whether an answer is validly signed,
+ unsigned, or invalid.
+
+ This is equivalent to setting the debug level to 3 for the
+ "validator" module of the "dnssec" logging category. Setting the
+ systemwide debug level to 3 using the :option:`-d` option produces the
+ same output, but affects other logging categories as well.
+
+.. option:: +short, +noshort
+
+ This option toggles between verbose and terse answers. The default is to print the answer in a
+ verbose form.
+
+.. option:: +comments, +nocomments
+
+ This option toggles the display of comment lines in the output. The default is to
+ print comments.
+
+.. option:: +rrcomments, +norrcomments
+
+ This option toggles the display of per-record comments in the output (for example,
+ human-readable key information about DNSKEY records). The default is
+ to print per-record comments.
+
+.. option:: +crypto, +nocrypto
+
+ This option toggles the display of cryptographic fields in DNSSEC records. The
+ contents of these fields are unnecessary to debug most DNSSEC
+ validation failures and removing them makes it easier to see the
+ common failures. The default is to display the fields. When omitted,
+ they are replaced by the string ``[omitted]`` or, in the DNSKEY case, the
+ key ID is displayed as the replacement, e.g. ``[ key id = value ]``.
+
+.. option:: +trust, +notrust
+
+ This option controls whether to display the trust level when printing a record.
+ The default is to display the trust level.
+
+.. option:: +split[=W], +nosplit
+
+ This option splits long hex- or base64-formatted fields in resource records into
+ chunks of ``W`` characters (where ``W`` is rounded up to the nearest
+ multiple of 4). ``+nosplit`` or ``+split=0`` causes fields not to be
+ split at all. The default is 56 characters, or 44 characters when
+ multiline mode is active.
+
+.. option:: +all, +noall
+
+ This option sets or clears the display options :option:`+comments`,
+ :option:`+rrcomments`, and :option:`+trust` as a group.
+
+.. option:: +multiline, +nomultiline
+
+ This option prints long records (such as RRSIG, DNSKEY, and SOA records) in a
+ verbose multi-line format with human-readable comments. The default
+ is to print each record on a single line, to facilitate machine
+ parsing of the :program:`delv` output.
+
+.. option:: +dnssec, +nodnssec
+
+ This option indicates whether to display RRSIG records in the :program:`delv` output.
+ The default is to do so. Note that (unlike in :iscman:`dig`) this does
+ *not* control whether to request DNSSEC records or to
+ validate them. DNSSEC records are always requested, and validation
+ always occurs unless suppressed by the use of :option:`-i` or
+ :option:`+noroot`.
+
+.. option:: +root[=ROOT], +noroot
+
+ This option indicates whether to perform conventional DNSSEC validation, and if so,
+ specifies the name of a trust anchor. The default is to validate using a
+ trust anchor of "." (the root zone), for which there is a built-in key. If
+ specifying a different trust anchor, then :option:`-a` must be used to specify a
+ file containing the key.
+
+.. option:: +tcp, +notcp
+
+ This option controls whether to use TCP when sending queries. The default is to
+ use UDP unless a truncated response has been received.
+
+.. option:: +unknownformat, +nounknownformat
+
+ This option prints all RDATA in unknown RR-type presentation format (:rfc:`3597`).
+ The default is to print RDATA for known types in the type's
+ presentation format.
+
+.. option:: +yaml, +noyaml
+
+ This option prints response data in YAML format.
+
+Files
+~~~~~
+
+|bind_keys|
+
+``/etc/resolv.conf``
+
+See Also
+~~~~~~~~
+
+:iscman:`dig(1) <dig>`, :iscman:`named(8) <named>`, :rfc:`4034`, :rfc:`4035`, :rfc:`4431`, :rfc:`5074`, :rfc:`5155`.