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