contrib/bind9/bin/dig/host.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) 2004, 2005, 2007  Internet Systems Consortium, Inc. ("ISC")
   6  - Copyright (C) 2000-2002  Internet Software Consortium.
   7  -
   8  - Permission to use, copy, modify, and/or distribute this software for any
   9  - purpose with or without fee is hereby granted, provided that the above
  10  - copyright notice and this permission notice appear in all copies.
  11  -
  12  - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  13  - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  14  - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  15  - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  16  - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  17  - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  18  - PERFORMANCE OF THIS SOFTWARE.
  19 -->
  20
  21 <!-- $Id: host.docbook,v 1.5.18.11 2007/08/28 07:19:55 tbox Exp $ -->
  22 <refentry id="man.host">
  23
  24   <refentryinfo>
  25     <date>Jun 30, 2000</date>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>host</refentrytitle>
  30     <manvolnum>1</manvolnum>
  31     <refmiscinfo>BIND9</refmiscinfo>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>host</refname>
  36     <refpurpose>DNS lookup utility</refpurpose>
  37   </refnamediv>
  38
  39   <docinfo>
  40     <copyright>
  41       <year>2004</year>
  42       <year>2005</year>
  43       <year>2007</year>
  44       <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
  45     </copyright>
  46     <copyright>
  47       <year>2000</year>
  48       <year>2001</year>
  49       <year>2002</year>
  50       <holder>Internet Software Consortium.</holder>
  51     </copyright>
  52   </docinfo>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>host</command>
  57       <arg><option>-aCdlnrsTwv</option></arg>
  58       <arg><option>-c <replaceable class="parameter">class</replaceable></option></arg>
  59       <arg><option>-N <replaceable class="parameter">ndots</replaceable></option></arg>
  60       <arg><option>-R <replaceable class="parameter">number</replaceable></option></arg>
  61       <arg><option>-t <replaceable class="parameter">type</replaceable></option></arg>
  62       <arg><option>-W <replaceable class="parameter">wait</replaceable></option></arg>
  63       <arg><option>-m <replaceable class="parameter">flag</replaceable></option></arg>
  64       <arg><option>-4</option></arg>
  65       <arg><option>-6</option></arg>
  66       <arg choice="req">name</arg>
  67       <arg choice="opt">server</arg>
  68     </cmdsynopsis>
  69   </refsynopsisdiv>
  70
  71   <refsect1>
  72     <title>DESCRIPTION</title>
  73
  74     <para><command>host</command>
  75       is a simple utility for performing DNS lookups.
  76       It is normally used to convert names to IP addresses and vice versa.
  77       When no arguments or options are given,
  78       <command>host</command>
  79       prints a short summary of its command line arguments and options.
  80     </para>
  81
  82     <para><parameter>name</parameter> is the domain name that is to be
  83       looked
  84       up.  It can also be a dotted-decimal IPv4 address or a colon-delimited
  85       IPv6 address, in which case <command>host</command> will by
  86       default
  87       perform a reverse lookup for that address.
  88       <parameter>server</parameter> is an optional argument which
  89       is either
  90       the name or IP address of the name server that <command>host</command>
  91       should query instead of the server or servers listed in
  92       <filename>/etc/resolv.conf</filename>.
  93     </para>
  94
  95     <para>
  96       The <option>-a</option> (all) option is equivalent to setting the
  97       <option>-v</option> option and asking <command>host</command> to make
  98       a query of type ANY.
  99     </para>
 100
 101     <para>
 102       When the <option>-C</option> option is used, <command>host</command>
 103       will attempt to display the SOA records for zone
 104       <parameter>name</parameter> from all the listed
 105       authoritative name
 106       servers for that zone.  The list of name servers is defined by the NS
 107       records that are found for the zone.
 108     </para>
 109
 110     <para>
 111       The <option>-c</option> option instructs to make a DNS query of class
 112       <parameter>class</parameter>.  This can be used to lookup
 113       Hesiod or
 114       Chaosnet class resource records.  The default class is IN (Internet).
 115     </para>
 116
 117     <para>
 118       Verbose output is generated by <command>host</command> when
 119       the
 120       <option>-d</option> or <option>-v</option> option is used.  The two
 121       options are equivalent.  They have been provided for backwards
 122       compatibility.  In previous versions, the <option>-d</option> option
 123       switched on debugging traces and <option>-v</option> enabled verbose
 124       output.
 125     </para>
 126
 127     <para>
 128       List mode is selected by the <option>-l</option> option.  This makes
 129       <command>host</command> perform a zone transfer for zone
 130       <parameter>name</parameter>.  Transfer the zone printing out
 131       the NS, PTR
 132       and address records (A/AAAA).  If combined with <option>-a</option>
 133       all records will be printed.
 134     </para>
 135
 136     <para>
 137       The <option>-i</option>
 138       option specifies that reverse lookups of IPv6 addresses should
 139       use the IP6.INT domain as defined in RFC1886.
 140       The default is to use IP6.ARPA.
 141     </para>
 142
 143     <para>
 144       The <option>-N</option> option sets the number of dots that have to be
 145       in <parameter>name</parameter> for it to be considered
 146       absolute.  The
 147       default value is that defined using the ndots statement in
 148       <filename>/etc/resolv.conf</filename>, or 1 if no ndots
 149       statement is
 150       present.  Names with fewer dots are interpreted as relative names and
 151       will be searched for in the domains listed in the <type>search</type>
 152       or <type>domain</type> directive in
 153       <filename>/etc/resolv.conf</filename>.
 154     </para>
 155
 156     <para>
 157       The number of UDP retries for a lookup can be changed with the
 158       <option>-R</option> option.  <parameter>number</parameter>
 159       indicates
 160       how many times <command>host</command> will repeat a query
 161       that does
 162       not get answered.  The default number of retries is 1.  If
 163       <parameter>number</parameter> is negative or zero, the
 164       number of
 165       retries will default to 1.
 166     </para>
 167
 168     <para>
 169       Non-recursive queries can be made via the <option>-r</option> option.
 170       Setting this option clears the <type>RD</type> &mdash; recursion
 171       desired &mdash; bit in the query which <command>host</command> makes.
 172       This should mean that the name server receiving the query will not
 173       attempt to resolve <parameter>name</parameter>.  The
 174       <option>-r</option> option enables <command>host</command>
 175       to mimic
 176       the behavior of a name server by making non-recursive queries and
 177       expecting to receive answers to those queries that are usually
 178       referrals to other name servers.
 179     </para>
 180
 181     <para>
 182       By default <command>host</command> uses UDP when making
 183       queries.  The
 184       <option>-T</option> option makes it use a TCP connection when querying
 185       the name server.  TCP will be automatically selected for queries that
 186       require it, such as zone transfer (AXFR) requests.
 187     </para>
 188
 189     <para>
 190       The <option>-4</option> option forces <command>host</command> to only
 191       use IPv4 query transport.  The <option>-6</option> option forces
 192       <command>host</command> to only use IPv6 query transport.
 193     </para>
 194
 195     <para>
 196       The <option>-t</option> option is used to select the query type.
 197       <parameter>type</parameter> can be any recognized query
 198       type: CNAME,
 199       NS, SOA, SIG, KEY, AXFR, etc.  When no query type is specified,
 200       <command>host</command> automatically selects an appropriate
 201       query
 202       type.  By default it looks for A records, but if the
 203       <option>-C</option> option was given, queries will be made for SOA
 204       records, and if <parameter>name</parameter> is a
 205       dotted-decimal IPv4
 206       address or colon-delimited IPv6 address, <command>host</command> will
 207       query for PTR records.  If a query type of IXFR is chosen the starting
 208       serial number can be specified by appending an equal followed by the
 209       starting serial number (e.g. -t IXFR=12345678).
 210     </para>
 211
 212     <para>
 213       The time to wait for a reply can be controlled through the
 214       <option>-W</option> and <option>-w</option> options.  The
 215       <option>-W</option> option makes <command>host</command>
 216       wait for
 217       <parameter>wait</parameter> seconds.  If <parameter>wait</parameter>
 218       is less than one, the wait interval is set to one second.  When the
 219       <option>-w</option> option is used, <command>host</command>
 220       will
 221       effectively wait forever for a reply.  The time to wait for a response
 222       will be set to the number of seconds given by the hardware's maximum
 223       value for an integer quantity.
 224     </para>
 225
 226     <para>
 227       The <option>-s</option> option tells <command>host</command>
 228       <emphasis>not</emphasis> to send the query to the next nameserver
 229       if any server responds with a SERVFAIL response, which is the
 230       reverse of normal stub resolver behavior.
 231     </para>
 232
 233     <para>
 234       The <option>-m</option> can be used to set the memory usage debugging
 235       flags
 236       <parameter>record</parameter>, <parameter>usage</parameter> and
 237       <parameter>trace</parameter>.
 238     </para>
 239   </refsect1>
 240
 241   <refsect1>
 242     <title>IDN SUPPORT</title>
 243     <para>
 244       If <command>host</command> has been built with IDN (internationalized
 245       domain name) support, it can accept and display non-ASCII domain names.
 246       <command>host</command> appropriately converts character encoding of
 247       domain name before sending a request to DNS server or displaying a
 248       reply from the server.
 249       If you'd like to turn off the IDN support for some reason, defines
 250       the <envar>IDN_DISABLE</envar> environment variable.
 251       The IDN support is disabled if the variable is set when
 252       <command>host</command> runs.
 253     </para>
 254   </refsect1>
 255
 256   <refsect1>
 257     <title>FILES</title>
 258     <para><filename>/etc/resolv.conf</filename>
 259     </para>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>SEE ALSO</title>
 264     <para><citerefentry>
 265         <refentrytitle>dig</refentrytitle><manvolnum>1</manvolnum>
 266       </citerefentry>,
 267       <citerefentry>
 268         <refentrytitle>named</refentrytitle><manvolnum>8</manvolnum>
 269       </citerefentry>.
 270     </para>
 271
 272   </refsect1>
 273 </refentry><!--
 274  - Local variables:
 275  - mode: sgml
 276  - End:
 277 -->