external/bsd/bind/dist/bin/delv/delv.docbook

   1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   2                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
   3                [<!ENTITY mdash "&#8212;">]>
   4 <!--
   5  - Copyright (C) 2014  Internet Systems Consortium, Inc. ("ISC")
   6  -
   7  - Permission to use, copy, modify, and/or distribute this software for any
   8  - purpose with or without fee is hereby granted, provided that the above
   9  - copyright notice and this permission notice appear in all copies.
  10  -
  11  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  12  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  13  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  14  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  15  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  16  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  - PERFORMANCE OF THIS SOFTWARE.
  18 -->
  19
  20 <refentry id="man.delv">
  21
  22   <refentryinfo>
  23     <date>April 23, 2014</date>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle>delv</refentrytitle>
  28     <manvolnum>1</manvolnum>
  29     <refmiscinfo>BIND9</refmiscinfo>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname>delv</refname>
  34     <refpurpose>DNS lookup and validation utility</refpurpose>
  35   </refnamediv>
  36
  37   <docinfo>
  38     <copyright>
  39       <year>2014</year>
  40       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  41     </copyright>
  42   </docinfo>
  43
  44   <refsynopsisdiv>
  45     <cmdsynopsis>
  46       <command>delv</command>
  47       <arg choice="opt">@server</arg>
  48       <arg><option>-4</option></arg>
  49       <arg><option>-6</option></arg>
  50       <arg><option>-a <replaceable class="parameter">anchor-file</replaceable></option></arg>
  51       <arg><option>-b <replaceable class="parameter">address</replaceable></option></arg>
  52       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  53       <arg><option>-d <replaceable class="parameter">level</replaceable></option></arg>
  54       <arg><option>-i</option></arg>
  55       <arg><option>-m</option></arg>
  56       <arg><option>-p <replaceable class="parameter">port#</replaceable></option></arg>
  57       <arg><option>-q <replaceable class="parameter">name</replaceable></option></arg>
  58       <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
  59       <arg><option>-x <replaceable class="parameter">addr</replaceable></option></arg>
  60       <arg choice="opt">name</arg>
  61       <arg choice="opt">type</arg>
  62       <arg choice="opt">class</arg>
  63       <arg choice="opt" rep="repeat">queryopt</arg>
  64     </cmdsynopsis>
  65
  66     <cmdsynopsis>
  67       <command>delv</command>
  68       <arg><option>-h</option></arg>
  69     </cmdsynopsis>
  70
  71     <cmdsynopsis>
  72       <command>delv</command>
  73       <arg><option>-v</option></arg>
  74     </cmdsynopsis>
  75
  76     <cmdsynopsis>
  77       <command>delv</command>
  78       <arg choice="opt" rep="repeat">queryopt</arg>
  79       <arg choice="opt" rep="repeat">query</arg>
  80     </cmdsynopsis>
  81   </refsynopsisdiv>
  82
  83   <refsect1>
  84     <title>DESCRIPTION</title>
  85     <para><command>delv</command>
  86       (Domain Entity Lookup &amp; Validation) is a tool for sending
  87       DNS queries and validating the results, using the the same internal
  88       resolver and validator logic as <command>named</command>.
  89     </para>
  90     <para>
  91       <command>delv</command> will send to a specified name server all
  92       queries needed to fetch and validate the requested data; this
  93       includes the original requested query, subsequent queries to follow
  94       CNAME or DNAME chains, and queries for DNSKEY, DS and DLV records
  95       to establish a chain of trust for DNSSEC validation.
  96       It does not perform iterative resolution, but simulates the
  97       behavior of a name server configured for DNSSEC validating and
  98       forwarding.
  99     </para>
 100     <para>
 101       By default, responses are validated using built-in DNSSEC trust
 102       anchors for the root zone (".") and for the ISC DNSSEC lookaside
 103       validation zone ("dlv.isc.org").  Records returned by
 104       <command>delv</command> are either fully validated or
 105       were not signed.  If validation fails, an explanation of
 106       the failure is included in the output; the validation process
 107       can be traced in detail.  Because <command>delv</command> does
 108       not rely on an external server to carry out validation, it can
 109       be used to check the validity of DNS responses in environments
 110       where local name servers may not be trustworthy.
 111     </para>
 112     <para>
 113       Unless it is told to query a specific name server,
 114       <command>delv</command> will try each of the servers listed in
 115       <filename>/etc/resolv.conf</filename>. If no usable server
 116       addresses are found, <command>delv</command> will send
 117       queries to the localhost addresses (127.0.0.1 for IPv4, ::1
 118       for IPv6).
 119     </para>
 120     <para>
 121       When no command line arguments or options are given,
 122       <command>delv</command> will perform an NS query for "."
 123       (the root zone).
 124     </para>
 125   </refsect1>
 126
 127   <refsect1>
 128     <title>SIMPLE USAGE</title>
 129
 130     <para>
 131       A typical invocation of <command>delv</command> looks like:
 132       <programlisting> delv @server name type </programlisting>
 133       where:
 134
 135       <variablelist>
 136         <varlistentry>
 137           <term><constant>server</constant></term>
 138           <listitem>
 139             <para>
 140               is the name or IP address of the name server to query.  This
 141               can be an IPv4 address in dotted-decimal notation or an IPv6
 142               address in colon-delimited notation.  When the supplied
 143               <parameter>server</parameter> argument is a hostname,
 144               <command>delv</command> resolves that name before
 145               querying that name server (note, however, that this
 146               initial lookup is <emphasis>not</emphasis> validated
 147               by DNSSEC).
 148             </para>
 149             <para>
 150               If no <parameter>server</parameter> argument is
 151               provided, <command>delv</command> consults
 152               <filename>/etc/resolv.conf</filename>; if an
 153               address is found there, it queries the name server at
 154               that address. If either of the <option>-4</option> or
 155               <option>-6</option> options are in use, then
 156               only addresses for the corresponding transport
 157               will be tried.  If no usable addresses are found,
 158               <command>delv</command> will send queries to
 159               the localhost addresses (127.0.0.1 for IPv4,
 160               ::1 for IPv6).
 161             </para>
 162           </listitem>
 163         </varlistentry>
 164
 165         <varlistentry>
 166           <term><constant>name</constant></term>
 167           <listitem>
 168             <para>
 169               is the domain name to be looked up.
 170             </para>
 171           </listitem>
 172         </varlistentry>
 173
 174         <varlistentry>
 175           <term><constant>type</constant></term>
 176           <listitem>
 177             <para>
 178               indicates what type of query is required &mdash;
 179               ANY, A, MX, etc.
 180               <parameter>type</parameter> can be any valid query
 181               type.  If no
 182               <parameter>type</parameter> argument is supplied,
 183               <command>delv</command> will perform a lookup for an
 184               A record.
 185             </para>
 186           </listitem>
 187         </varlistentry>
 188
 189       </variablelist>
 190     </para>
 191
 192   </refsect1>
 193
 194   <refsect1>
 195     <title>OPTIONS</title>
 196     <variablelist>
 197
 198       <varlistentry>
 199         <term>-a <replaceable class="parameter">anchor-file</replaceable></term>
 200         <listitem>
 201           <para>
 202             Specifies a file from which to read DNSSEC trust anchors.
 203             The default is <filename>/etc/bind.keys</filename>, which
 204             is included with <acronym>BIND</acronym> 9 and contains
 205             trust anchors for the root zone (".") and for the ISC
 206             DNSSEC lookaside validation zone ("dlv.isc.org").
 207           </para>
 208           <para>
 209             Keys that do not match the root or DLV trust-anchor
 210             names are ignored; these key names can be overridden
 211             using the <option>+dlv=NAME</option> or
 212             <option>+root=NAME</option> options.
 213           </para>
 214           <para>
 215             Note: When reading the trust anchor file,
 216             <command>delv</command> treats <option>managed-keys</option>
 217             statements and <option>trusted-keys</option> statements
 218             identically.  That is, for a managed key, it is the
 219             <emphasis>initial</emphasis> key that is trusted; RFC 5011
 220             key management is not supported. <command>delv</command>
 221             will not consult the managed-keys database maintained by
 222             <command>named</command>. This means that if either of the
 223             keys in <filename>/etc/bind.keys</filename> is revoked
 224             and rolled over, it will be necessary to update
 225             <filename>/etc/bind.keys</filename> to use DNSSEC
 226             validation in <command>delv</command>.
 227           </para>
 228         </listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term>-b  <replaceable class="parameter">address</replaceable></term>
 233         <listitem>
 234           <para>
 235             Sets the source IP address of the query to
 236             <parameter>address</parameter>.  This must be a valid address
 237             on one of the host's network interfaces or "0.0.0.0" or "::".
 238             An optional source port may be specified by appending
 239             "#&lt;port&gt;"
 240           </para>
 241         </listitem>
 242       </varlistentry>
 243
 244       <varlistentry>
 245         <term>-c <replaceable class="parameter">class</replaceable></term>
 246         <listitem>
 247           <para>
 248             Sets the query class for the requested data. Currently,
 249             only class "IN" is supported in <command>delv</command>
 250             and any other value is ignored.
 251           </para>
 252         </listitem>
 253       </varlistentry>
 254
 255       <varlistentry>
 256         <term>-d <replaceable class="parameter">level</replaceable></term>
 257         <listitem>
 258           <para>
 259             Set the systemwide debug level to <option>level</option>.
 260             The allowed range is from 0 to 99.
 261             The default is 0 (no debugging).
 262             Debugging traces from <command>delv</command> become
 263             more verbose as the debug level increases.
 264             See the <option>+mtrace</option>, <option>+rtrace</option>,
 265             and <option>+vtrace</option> options below for additional
 266             debugging details.
 267           </para>
 268         </listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term>-h</term>
 273         <listitem>
 274           <para>
 275             Display the <command>delv</command> help usage output and exit.
 276           </para>
 277         </listitem>
 278       </varlistentry>
 279
 280       <varlistentry>
 281         <term>-i</term>
 282         <listitem>
 283           <para>
 284             Insecure mode. This disables internal DNSSEC validation.
 285             (Note, however, this does not set the CD bit on upstream
 286             queries. If the server being queried is performing DNSSEC
 287             validation, then it will not return invalid data; this
 288             can cause <command>delv</command> to time out. When it
 289             is necessary to examine invalid data to debug a DNSSEC
 290             problem, use <command>dig +cd</command>.)
 291           </para>
 292         </listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term>-m</term>
 297         <listitem>
 298           <para>
 299             Enables memory usage debugging.
 300           </para>
 301         </listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term>-p <replaceable class="parameter">port#</replaceable></term>
 306         <listitem>
 307           <para>
 308             Specifies a destination port to use for queries instead of
 309             the standard DNS port number 53.  This option would be used
 310             with a name server that has been configured to listen
 311             for queries on a non-standard port number.
 312           </para>
 313         </listitem>
 314       </varlistentry>
 315
 316       <varlistentry>
 317         <term>-q <replaceable class="parameter">name</replaceable></term>
 318         <listitem>
 319           <para>
 320             Sets the query name to <parameter>name</parameter>.
 321             While the query name can be specified without using the
 322             <option>-q</option>, it is sometimes necessary to disambiguate
 323             names from types or classes (for example, when looking up the
 324             name "ns", which could be misinterpreted as the type NS,
 325             or "ch", which could be misinterpreted as class CH).
 326           </para>
 327         </listitem>
 328       </varlistentry>
 329
 330       <varlistentry>
 331         <term>-t <replaceable class="parameter">type</replaceable></term>
 332         <listitem>
 333           <para>
 334             Sets the query type to <parameter>type</parameter>, which
 335             can be any valid query type supported in BIND 9 except
 336             for zone transfer types AXFR and IXFR. As with
 337             <option>-q</option>, this is useful to distinguish
 338             query name type or class when they are ambiguous.
 339             it is sometimes necessary to disambiguate names from types.
 340           </para>
 341           <para>
 342             The default query type is "A", unless the <option>-x</option>
 343             option is supplied to indicate a reverse lookup, in which case
 344             it is "PTR".
 345           </para>
 346         </listitem>
 347       </varlistentry>
 348
 349       <varlistentry>
 350         <term>-v</term>
 351         <listitem>
 352           <para>
 353             Print the <command>delv</command> version and exit.
 354           </para>
 355         </listitem>
 356       </varlistentry>
 357
 358       <varlistentry>
 359         <term>-x <replaceable class="parameter">addr</replaceable></term>
 360         <listitem>
 361           <para>
 362             Performs a reverse lookup, mapping an addresses to
 363             a name.  <parameter>addr</parameter> is an IPv4 address in
 364             dotted-decimal notation, or a colon-delimited IPv6 address.
 365             When <option>-x</option> is used, there is no need to provide
 366             the <parameter>name</parameter> or <parameter>type</parameter>
 367             arguments.  <command>delv</command> automatically performs a
 368             lookup for a name like <literal>11.12.13.10.in-addr.arpa</literal>
 369             and sets the query type to PTR.  IPv6 addresses are looked up
 370             using nibble format under the IP6.ARPA domain.
 371           </para>
 372         </listitem>
 373       </varlistentry>
 374
 375       <varlistentry>
 376         <term>-4</term>
 377         <listitem>
 378           <para>
 379             Forces <command>delv</command> to only use IPv4.
 380           </para>
 381         </listitem>
 382       </varlistentry>
 383
 384       <varlistentry>
 385         <term>-6</term>
 386         <listitem>
 387           <para>
 388             Forces <command>delv</command> to only use IPv6.
 389           </para>
 390         </listitem>
 391       </varlistentry>
 392
 393     </variablelist>
 394   </refsect1>
 395
 396   <refsect1>
 397     <title>QUERY OPTIONS</title>
 398
 399     <para><command>delv</command>
 400       provides a number of query options which affect the way results are
 401       displayed, and in some cases the way lookups are performed.
 402     </para>
 403
 404     <para>
 405       Each query option is identified by a keyword preceded by a plus sign
 406       (<literal>+</literal>).  Some keywords set or reset an
 407       option.  These may be preceded by the string
 408       <literal>no</literal> to negate the meaning of that keyword.
 409       Other keywords assign values to options like the timeout interval.
 410       They have the form <option>+keyword=value</option>.
 411       The query options are:
 412
 413       <variablelist>
 414         <varlistentry>
 415           <term><option>+[no]cdflag</option></term>
 416           <listitem>
 417             <para>
 418               Controls whether to set the CD (checking disabled) bit in
 419               queries sent by <command>delv</command>. This may be useful
 420               when troubleshooting DNSSEC problems from behind a validating
 421               resolver. A validating resolver will block invalid responses,
 422               making it difficult to retrieve them for analysis. Setting
 423               the CD flag on queries will cause the resolver to return
 424               invalid responses, which <command>delv</command> can then
 425               validate internally and report the errors in detail.
 426             </para>
 427           </listitem>
 428         </varlistentry>
 429
 430         <varlistentry>
 431           <term><option>+[no]class</option></term>
 432           <listitem>
 433             <para>
 434               Controls whether to display the CLASS when printing
 435               a record. The default is to display the CLASS.
 436             </para>
 437           </listitem>
 438         </varlistentry>
 439
 440         <varlistentry>
 441           <term><option>+[no]ttl</option></term>
 442           <listitem>
 443             <para>
 444               Controls whether to display the TTL when printing
 445               a record. The default is to display the TTL.
 446             </para>
 447           </listitem>
 448         </varlistentry>
 449
 450         <varlistentry>
 451           <term><option>+[no]rtrace</option></term>
 452           <listitem>
 453             <para>
 454               Toggle resolver fetch logging. This reports the
 455               name and type of each query sent by <command>delv</command>
 456               in the process of carrying out the resolution and validation
 457               process: this includes including the original query and
 458               all subsequent queries to follow CNAMEs and to establish a
 459               chain of trust for DNSSEC validation.
 460             </para>
 461             <para>
 462               This is equivalent to setting the debug level to 1 in
 463               the "resolver" logging category. Setting the systemwide
 464               debug level to 1 using the <option>-d</option> option will
 465               product the same output (but will affect other logging
 466               categories as well).
 467             </para>
 468           </listitem>
 469         </varlistentry>
 470
 471         <varlistentry>
 472           <term><option>+[no]mtrace</option></term>
 473           <listitem>
 474             <para>
 475               Toggle message logging. This produces a detailed dump of
 476               the responses received by <command>delv</command> in the
 477               process of carrying out the resolution and validation process.
 478             </para>
 479             <para>
 480               This is equivalent to setting the debug level to 10
 481               for the the "packets" module of the "resolver" logging
 482               category. Setting the systemwide debug level to 10 using
 483               the <option>-d</option> option will produce the same output
 484               (but will affect other logging categories as well).
 485             </para>
 486           </listitem>
 487         </varlistentry>
 488
 489         <varlistentry>
 490           <term><option>+[no]vtrace</option></term>
 491           <listitem>
 492             <para>
 493               Toggle validation logging. This shows the internal
 494               process of the validator as it determines whether an
 495               answer is validly signed, unsigned, or invalid.
 496             </para>
 497             <para>
 498               This is equivalent to setting the debug level to 3
 499               for the the "validator" module of the "dnssec" logging
 500               category. Setting the systemwide debug level to 3 using
 501               the <option>-d</option> option will produce the same output
 502               (but will affect other logging categories as well).
 503             </para>
 504           </listitem>
 505         </varlistentry>
 506
 507         <varlistentry>
 508           <term><option>+[no]short</option></term>
 509           <listitem>
 510             <para>
 511               Provide a terse answer.  The default is to print the answer in a
 512               verbose form.
 513             </para>
 514           </listitem>
 515         </varlistentry>
 516
 517         <varlistentry>
 518           <term><option>+[no]comments</option></term>
 519           <listitem>
 520             <para>
 521               Toggle the display of comment lines in the output.  The default
 522               is to print comments.
 523             </para>
 524           </listitem>
 525         </varlistentry>
 526
 527         <varlistentry>
 528           <term><option>+[no]rrcomments</option></term>
 529           <listitem>
 530             <para>
 531               Toggle the display of per-record comments in the output (for
 532               example, human-readable key information about DNSKEY records).
 533               The default is to print per-record comments.
 534             </para>
 535           </listitem>
 536         </varlistentry>
 537
 538         <varlistentry>
 539           <term><option>+[no]crypto</option></term>
 540           <listitem>
 541             <para>
 542               Toggle the display of cryptographic fields in DNSSEC records.
 543               The contents of these field are unnecessary to debug most DNSSEC
 544               validation failures and removing them makes it easier to see
 545               the common failures.  The default is to display the fields.
 546               When omitted they are replaced by the string "[omitted]" or
 547               in the DNSKEY case the key id is displayed as the replacement,
 548               e.g. "[ key id = value ]".
 549             </para>
 550           </listitem>
 551         </varlistentry>
 552
 553         <varlistentry>
 554           <term><option>+[no]trust</option></term>
 555           <listitem>
 556             <para>
 557               Controls whether to display the trust level when printing
 558               a record. The default is to display the trust level.
 559             </para>
 560           </listitem>
 561         </varlistentry>
 562
 563         <varlistentry>
 564           <term><option>+[no]split[=W]</option></term>
 565           <listitem>
 566             <para>
 567               Split long hex- or base64-formatted fields in resource
 568               records into chunks of <parameter>W</parameter> characters
 569               (where <parameter>W</parameter> is rounded up to the nearest
 570               multiple of 4).
 571               <parameter>+nosplit</parameter> or
 572               <parameter>+split=0</parameter> causes fields not to be
 573               split at all.  The default is 56 characters, or 44 characters
 574               when multiline mode is active.
 575             </para>
 576           </listitem>
 577         </varlistentry>
 578
 579         <varlistentry>
 580           <term><option>+[no]all</option></term>
 581           <listitem>
 582             <para>
 583               Set or clear the display options
 584               <option>+[no]comments</option>,
 585               <option>+[no]rrcomments</option>, and
 586               <option>+[no]trust</option> as a group.
 587             </para>
 588           </listitem>
 589         </varlistentry>
 590
 591         <varlistentry>
 592           <term><option>+[no]multiline</option></term>
 593           <listitem>
 594             <para>
 595               Print long records (such as RRSIG, DNSKEY, and SOA records)
 596               in a verbose multi-line format with human-readable comments.
 597               The default is to print each record on a single line, to
 598               facilitate machine parsing of the <command>delv</command>
 599               output.
 600             </para>
 601           </listitem>
 602         </varlistentry>
 603
 604         <varlistentry>
 605           <term><option>+[no]dnssec</option></term>
 606           <listitem>
 607             <para>
 608               Indicates whether to display RRSIG records in the
 609               <command>delv</command> output.  The default is to
 610               do so.  Note that (unlike in <command>dig</command>)
 611               this does <emphasis>not</emphasis> control whether to
 612               request DNSSEC records or whether to validate them.
 613               DNSSEC records are always requested, and validation
 614               will always occur unless suppressed by the use of
 615               <option>-i</option> or <option>+noroot</option> and
 616               <option>+nodlv</option>.
 617             </para>
 618           </listitem>
 619         </varlistentry>
 620
 621         <varlistentry>
 622           <term><option>+[no]root[=ROOT]</option></term>
 623           <listitem>
 624             <para>
 625               Indicates whether to perform conventional (non-lookaside)
 626               DNSSEC validation, and if so, specifies the
 627               name of a trust anchor.  The default is to validate using
 628               a trust anchor of "." (the root zone), for which there is
 629               a built-in key.  If specifying a different trust anchor,
 630               then <option>-a</option> must be used to specify a file
 631               containing the key.
 632             </para>
 633           </listitem>
 634         </varlistentry>
 635
 636         <varlistentry>
 637           <term><option>+[no]dlv[=DLV]</option></term>
 638           <listitem>
 639             <para>
 640               Indicates whether to perform DNSSEC lookaside validation,
 641               and if so, specifies the name of the DLV trust anchor.
 642               The default is to perform lookaside validation using
 643               a trust anchor of "dlv.isc.org", for which there is a
 644               built-in key.  If specifying a different name, then
 645               <option>-a</option> must be used to specify a file
 646               containing the DLV key.
 647             </para>
 648           </listitem>
 649         </varlistentry>
 650       </variablelist>
 651
 652     </para>
 653   </refsect1>
 654
 655   <refsect1>
 656     <title>FILES</title>
 657     <para><filename>/etc/bind.keys</filename></para>
 658     <para><filename>/etc/resolv.conf</filename></para>
 659   </refsect1>
 660
 661   <refsect1>
 662     <title>SEE ALSO</title>
 663     <para><citerefentry>
 664         <refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
 665       </citerefentry>,
 666       <citerefentry>
 667         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 668       </citerefentry>,
 669       <citetitle>RFC4034</citetitle>,
 670       <citetitle>RFC4035</citetitle>,
 671       <citetitle>RFC4431</citetitle>,
 672       <citetitle>RFC5074</citetitle>,
 673       <citetitle>RFC5155</citetitle>.
 674     </para>
 675   </refsect1>
 676 </refentry><!--
 677  - Local variables:
 678  - mode: sgml
 679  - End:
 680 -->