src/idnlookup.1

   1 .\"
   2 .\" Copyright (c) 2005 Fredrik Tolf <fredrik@dolda2000.com>
   3 .\"
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, write to the Free
  21 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  22 .\" USA.
  23 .\"
  24 .TH IDNLOOKUP 1 "12 Jan 2006" "icmpdn 0.3" "ICMP Hostname Manual"
  25 .SH NAME
  26 idnlookup \- ICMP domain name resolver
  27 .SH SYNOPSIS
  28 .B idnlookup
  29 [ \fB-ahT\fP ] [ \fB-t\fP \fItimeout\fP ] \fIhostname\fP
  30 .SH DESCRIPTION
  31 \fBidnlookup\fP is a utility to ask an Internet host for its fully
  32 qualified domain name over ICMP. If successful, it will print the
  33 host's domain name to standard output.
  34 .P
  35 \fIhostname\fP is the address of the Internet host to query. It can be
  36 either a symbolic hostname, an IPv4 address in decimal notation, or an
  37 IPv6 address in hexadecimal notation. If a symbolic hostname is
  38 specified, all its addresses are looked up and tried in order.
  39 .P
  40 The remote host must be running software which can respond to the
  41 requests for hostname. To the knowledge of the author, current
  42 BSD-based systems can do this in the kernel. Linux systems must, as of
  43 this writing, be running \fBicmpdnd\fP(8).
  44 .SH EXIT STATUS
  45 \fBidnlookup\fP will return 0 if the specified host was succesfully
  46 queried. If illegal arguments were given, or if the host could, for
  47 any reason, not be queried, or if another error occurred, it will
  48 return 1.
  49 .SH OPTIONS
  50 .TP
  51 .B -a
  52 Normally, \fBidnlookup\fP will only print the first name that the host
  53 returns. This option will cause all names to be printed, one per
  54 line.
  55 .TP
  56 .B -h
  57 Print a brief usage message and exit.
  58 .TP
  59 .B -T
  60 Write the time-to-live in seconds that the remote host suggests on the
  61 first line, before any names.
  62 .TP
  63 .B -t
  64 Print an error message and exit if the remote host does not reply in
  65 \fItimeout\fP milliseconds. The default is 3 seconds. Note that this
  66 timeout will apply to all addresses, in case a symbolic hostname
  67 resolves to more than one address.
  68 .SH SECURITY
  69 Since \fBidnlookup\fP uses ICMP, it needs to run as root. Normally, it
  70 should be installed set-uid root in order for any user to be able to
  71 ask hosts for their names. Although the author believes
  72 \fBidnlookup\fP to be safe to install as set-uid root, he makes no
  73 guarantees.
  74 .SH BUGS
  75 \fBidnlookup\fP does not yet implement domain name decompression, and
  76 as such will scream and die at the sight of such names. This is
  77 because the author is not sure from which point in the ICMP datagrams
  78 the offsets specified in compressed domain names is to be counted. If
  79 you have information on this, please mail the author. Until then, this
  80 bug will hopefully not pose any large problems, since probably only
  81 very few hosts will return more than one name, and then there is
  82 little chance to compress it.
  83 .P
  84 Some GNU/Linux distributions still ship with a GNU C library
  85 implementation that has a bug in the implementation of
  86 \fBgetaddrinfo\fP(3), which may cause addresses resolved from a
  87 symbolic hostname to be returned in the wrong order (i.e. not
  88 consistent with RFC 3484). This will in turn cause \fBidnlookup\fP to
  89 try addresses in the wrong order, if the hostname in question triggers
  90 the \fBgetaddrinfo\fP(3) bug. This will normally not pose a problem,
  91 but not too uncommonly, this will cause IPv4 addresses to be sorted
  92 before IPv6 addresses. If the remote host listens for ICMP hostname
  93 requests only on IPv6 (or if the Internet service provider for the
  94 remote host blocks ICMP packets, which is wrong, but unfortunately not
  95 all too uncommon), \fBidnlookup\fP will have to time out on the IPv4
  96 address before being able to query the IPv6 address. This bug has been
  97 fixed since, but as of this writing, only a few systems run the fixed
  98 version of glibc.
  99 .SH AUTHOR
 100 Fredrik Tolf <fredrik@dolda2000.com>
 101 .SH SEE ALSO
 102 \fBicmpdnd\fP(8), \fBnss-icmp\fP(7), \fIRFC 1788\fP