| 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 NOTES |
| 100 | The ICMP hostname tools also ship with a nameswitch module for ICMP |
| 101 | hostname lookups, which can be used to automatically look up hostnames |
| 102 | over ICMP when a program calls \fBgethostbyaddr\fP(3) or any related |
| 103 | function. See the \fBnss-icmp\fP(7) man page for more information. |
| 104 | .SH AUTHOR |
| 105 | Fredrik Tolf <fredrik@dolda2000.com> |
| 106 | .SH SEE ALSO |
| 107 | \fBicmpdnd\fP(8), \fBnss-icmp\fP(7), \fIRFC 1788\fP |