Adding upstream version 1:9.16.44.upstream/1%9.16.44upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 326 insertions, 0 deletions

diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst
new file mode 100644
index 0000000..0936236
--- /dev/null
+++ b/bin/delv/delv.rst
@@ -0,0 +1,326 @@
+.. 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
+
+.. _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
+~~~~~~~~~~~
+
+``delv`` is a tool for sending DNS queries and validating the results,
+using the same internal resolver and validator logic as ``named``.
+
+``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 ``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 ``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, ``delv`` tries
+each of the servers listed in ``/etc/resolv.conf``. If no usable server
+addresses are found, ``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, ``delv``
+performs an NS query for "." (the root zone).
+
+Simple Usage
+~~~~~~~~~~~~
+
+A typical invocation of ``delv`` looks like:
+
+::
+
+    delv @server name type
+
+where:
+
+``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, ``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, ``delv`` consults
+   ``/etc/resolv.conf``; if an address is found there, it queries the
+   name server at that address. If either of the ``-4`` or ``-6``
+   options is in use, then only addresses for the corresponding
+   transport are tried. If no usable addresses are found, ``delv``
+   sends queries to the localhost addresses (127.0.0.1 for IPv4, ::1
+   for IPv6).
+
+``name``
+   is the domain name to be looked up.
+
+``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, ``delv`` performs a lookup for an A record.
+
+Options
+~~~~~~~
+
+``-a anchor-file``
+   This option specifies a file from which to read DNSSEC trust anchors. The default
+   is ``/etc/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 ``+root=NAME`` options.
+
+   Note: When reading the trust anchor file, ``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. ``delv`` does not consult the managed-keys database maintained by
+   ``named``, which means that if either of the keys in ``/etc/bind.keys`` is
+   revoked and rolled over, ``/etc/bind.keys`` must be updated to
+   use DNSSEC validation in ``delv``.
+
+``-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>``
+
+``-c class``
+   This option sets the query class for the requested data. Currently, only class
+   "IN" is supported in ``delv`` and any other value is ignored.
+
+``-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
+   ``delv`` become more verbose as the debug level increases. See the
+   ``+mtrace``, ``+rtrace``, and ``+vtrace`` options below for
+   additional debugging details.
+
+``-h``
+   This option displays the ``delv`` help usage output and exits.
+
+``-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 ``delv`` to time out. When it
+   is necessary to examine invalid data to debug a DNSSEC problem, use
+   ``dig +cd``.)
+
+``-m``
+   This option enables memory usage debugging.
+
+``-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.
+
+``-q name``
+   This option sets the query name to ``name``. While the query name can be
+   specified without using the ``-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).
+
+``-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 ``-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 ``-x`` option is supplied
+   to indicate a reverse lookup, in which case it is "PTR".
+
+``-v``
+   This option prints the ``delv`` version and exits.
+
+``-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 ``-x`` is used, there is no need to provide the
+   ``name`` or ``type`` arguments; ``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.
+
+``-4``
+   This option forces ``delv`` to only use IPv4.
+
+``-6``
+   This option forces ``delv`` to only use IPv6.
+
+Query Options
+~~~~~~~~~~~~~
+
+``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:
+
+``+[no]cdflag``
+   This option controls whether to set the CD (checking disabled) bit in queries
+   sent by ``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 ``delv`` can then validate
+   internally and report the errors in detail.
+
+``+[no]class``
+   This option controls whether to display the CLASS when printing a record. The
+   default is to display the CLASS.
+
+``+[no]ttl``
+   This option controls whether to display the TTL when printing a record. The
+   default is to display the TTL.
+
+``+[no]rtrace``
+   This option toggles resolver fetch logging. This reports the name and type of each
+   query sent by ``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
+   ``-d`` option produces the same output, but affects other
+   logging categories as well.
+
+``+[no]mtrace``
+   This option toggles message logging. This produces a detailed dump of the
+   responses received by ``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 ``-d`` option produces the same
+   output, but affects other logging categories as well.
+
+``+[no]vtrace``
+   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 ``-d`` option produces the
+   same output, but affects other logging categories as well.
+
+``+[no]short``
+   This option toggles between verbose and terse answers. The default is to print the answer in a
+   verbose form.
+
+``+[no]comments``
+   This option toggles the display of comment lines in the output. The default is to
+   print comments.
+
+``+[no]rrcomments``
+   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.
+
+``+[no]crypto``
+   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 ]``.
+
+``+[no]trust``
+   This option controls whether to display the trust level when printing a record.
+   The default is to display the trust level.
+
+``+[no]split[=W]``
+   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.
+
+``+[no]all``
+   This option sets or clears the display options ``+[no]comments``,
+   ``+[no]rrcomments``, and ``+[no]trust`` as a group.
+
+``+[no]multiline``
+   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 ``delv`` output.
+
+``+[no]dnssec``
+   This option indicates whether to display RRSIG records in the ``delv`` output.
+   The default is to do so. Note that (unlike in ``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 ``-i`` or
+   ``+noroot``.
+
+``+[no]root[=ROOT]``
+   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 ``-a`` must be used to specify a
+   file containing the key.
+
+``+[no]tcp``
+   This option controls whether to use TCP when sending queries. The default is to
+   use UDP unless a truncated response has been received.
+
+``+[no]unknownformat``
+   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.
+
+``+[no]yaml``
+   This option prints response data in YAML format.
+
+Files
+~~~~~
+
+``/etc/bind.keys``
+
+``/etc/resolv.conf``
+
+See Also
+~~~~~~~~
+
+:manpage:`dig(1)`, :manpage:`named(8)`, :rfc:`4034`, :rfc:`4035`, :rfc:`4431`, :rfc:`5074`, :rfc:`5155`.