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