/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-->