README.html

   1 <html><head><title>adns - advanced, alternative, asynchronous resolver</title>
   2 <link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk">
   3 <meta name="keywords" content="adns">
   4 </head>
   5 <body>
   6 <h1>GNU adns</h1>
   7
   8 <strong>Advanced, easy to use, asynchronous-capable DNS client
   9 library and utilities.</strong>
  10
  11 <!--      Note: this file must contain portable HTML !            -->
  12 <!--                                                              -->
  13 <!--  It is served on the GNU site and also from my own system,   -->
  14 <!--  under the URL http://www.chiark.greenend.org.uk/adns/       -->
  15 <!--  Please ensure that all links continine to be correct        -->
  16 <!--  both for www.gnu.org and chiark.                            -->
  17 <!--                                                              -->
  18 <!--  $Id$    -->
  19
  20 <p>
  21
  22 adns is a resolver library for C (and C++) programs, and a collection
  23 of useful DNS resolver utilities.
  24
  25
  26 <h2>C library</h2>
  27
  28 In contrast with the standard interfaces, gethostbyname et al and
  29 libresolv, it has the following features:
  30
  31 <ul>
  32
  33 <li>It is reasonably easy to use for simple programs which just want
  34 to translate names to addresses, look up MX records, etc.
  35
  36 <li>It can be used in an asynchronous, non-blocking, manner.  Many
  37 queries can be handled simultaneously.
  38
  39 <li>Responses are decoded automatically into a natural representation
  40 for a C program - there is no need to deal with DNS packet and RRDATA
  41 formats.
  42
  43 <li>Sanity checking (eg, name syntax checking, reverse/forward
  44 correspondence, CNAME pointing to CNAME) is performed automatically
  45 by default.
  46
  47 <li>Time-to-live, CNAME and other similar information is returned in
  48 an easy-to-use form, without getting in the way.
  49
  50 <li>There is no global state in the library; resolver state is an
  51 opaque data structure which the client creates explicitly.  A program
  52 can have several instances of the resolver.
  53
  54 <li>Errors are reported to the application in a way that distinguishes
  55 the various causes of failure properly.
  56
  57 <li>adns understands conventional resolv.conf, but this can overridden
  58 by environment variables.
  59
  60 <li>Flexibility.  For example, the application can tell adns to:
  61 ignore environment variables (for setuid programs), disable hostname
  62 syntax sanity checks to return arbitrary data, override or ignore
  63 resolv.conf in favour of supplied configuration, etc.
  64
  65 <li>Believed to be correct !  For example, will correctly back off to
  66 TCP in case of long replies or queries, or to other nameservers if
  67 several are available.  It has sensible handling of bad responses etc.
  68
  69 </ul>
  70
  71 <h2>DNS utility programs</h2>
  72
  73 adns also comes with a number of utility programs for use from the
  74 command line and in scripts:
  75
  76 <ul>
  77
  78 <li><code>adnslogres</code> is a much faster version of Apache's
  79 logresolv program.
  80
  81 <li><code>adnsresfilter</code> is a filter which copies its input to
  82 its output, replacing IP addresses by the corresponding names, without
  83 unduly delaying the output.  For example, you can usefully pipe the
  84 output of netstat -n, tcpdump -ln, and the like, into it.
  85
  86 <li><code>adnshost</code> is a general-purpose DNS lookup utility
  87 which can be used easily in from the command line and from shell
  88 scripts to do simple lookups.  In a more advanced mode it can be used
  89 as a general-purpose DNS helper program for scripting languages which
  90 can invoke and communicate with subprocesses.  See the
  91 <A href="http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt">adnshost
  92 usage message</A> for a summary of its capabilities.
  93
  94 </ul>
  95
  96 <h2>Documentation</h2>
  97
  98 I'm afraid there is no manual yet.  However, competent C programmers
  99 should be able to use the library based on the
 100 <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">commented
 101 adns.h header file</A>, and the usage messages for the programs should
 102 be sufficient.
 103
 104 <h2>Feedback</h2>
 105
 106 I'd be pleased if you would let me know if you're using my library in
 107 your project, and what you think of it.
 108
 109 <p>
 110
 111 Bug reports should be reported to the
 112 <a href="http://debbugs.gnu.org/">GNU Debbugs</a>.  Send an email
 113 to <code>submit@debbugs.gnu.org</code> and at the top of your email,
 114 in a paragraph of its own, write the single line
 115 <pre>
 116 Package: adns
 117 </pre>
 118 Your bug report will be published via to the adns-discuss list.
 119
 120 <p>
 121
 122 Feedback and discussion takes place on the <code>adns-discuss</code>
 123 list.  You can mail me privately
 124 at <code>ijackson@chiark.greenend.org.uk</code>.
 125
 126 <h2>Mailinglists</h2>
 127
 128 I have set up mailinglists <code>adns-announce</code> and
 129 <code>adns-discuss</code>.  The announcements list is moderated and
 130 will contain only announcements of important bugs, new versions, etc.
 131
 132 <p>
 133
 134 There are
 135 <A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives
 136 and subscription web pages</A>, or you can subscribe by sending mail
 137 containing the word `subscribe' to
 138 <code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or
 139 <code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>.
 140
 141 <h2>Documentation</h2>
 142
 143 <ul>
 144 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">adns.h
 145     API header file with documentation comments</A>
 146 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt">usage
 147     message for adnshost</A>
 148 </ul>
 149
 150 <h2>Download and source code</h2>
 151
 152 <ul>
 153 <li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current
 154     release</A> as a gzipped tarfile.
 155 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/ftp/">Previous
 156     versions</A>.
 157 <li><A href="http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/adns.git/">master
 158     git (version control) repository browser</a>.
 159 </ul>
 160
 161 adns is also available from the
 162 <A href="http://www.gnu.org/">GNU Project</A> FTP servers and their
 163 <A href="http://www.gnu.org/order/ftp.html">mirrors</A>.
 164
 165 <h2>Installation note</h2>
 166
 167 adns requires a real nameserver like
 168 <A href="http://www.isc.org/view.cgi?/products/BIND/index.phtml">BIND</A>
 169 running on
 170 the same system or a nearby one, which must be willing to provide
 171 `recursive service'.  I.e., adns is a `stub resolver'.
 172
 173 <p>
 174 adns requires that your real nameserver is on the same machine, or
 175 connected via a secure network, so that an attacker cannot fake the
 176 replies to adns's queries.
 177
 178 <h2>References and related projects</h2>
 179
 180 <ul>
 181 <li><a href="http://code.google.com/p/adns-python">Python bindings</a>
 182    by Andy Dustman.
 183 <!-- <li><a href="http://cryp.to/hsdns/">Haskell bindings</a>
 184    by Peter Simons. -->
 185 <li><a href="http://www.lysator.liu.se/liboop/">liboop event loop library</a>
 186    has a built-in binding for adns.
 187 <li><a href="http://adns.jgaa.com/">port to MS Visual Studio 6 C++</a>
 188    by Jarle Aase.
 189 </ul>
 190
 191 <h2>Copyright and licensing</h2>
 192
 193 <kbd>adns</kbd> is Copyright 1997-2000,2003,2006,2014 Ian Jackson,
 194 Copyright 2014 Mark Wooding, Copyright 1999-2000,2003,2006 Tony Finch,
 195 and Copyright (C) 1991 Massachusetts Institute of Technology.
 196
 197 <p>
 198
 199 <kbd>adns</kbd> is free software; you can redistribute it and/or modify
 200 it under the terms of the GNU General Public License as published by
 201 the Free Software Foundation; either version 3 of the License, or (at
 202 your option) any later version.
 203
 204 <p>
 205
 206 This program and documentation is distributed in the hope that it will
 207 be useful, but <em>without any warranty</em>; without even the implied
 208 warranty of <em>merchantability</em> or <em>fitness for a particular
 209 purpose</em>.  See the
 210 <A href="http://www.chiark.greenend.org.uk/~ian/COPYING.txt">GNU
 211 General Public License</A> for more details.
 212
 213 <p>
 214
 215 You should have received a copy of the GNU General Public License
 216 along with <kbd>adns</kbd>, or one should be available above; if not,
 217 write to the <A href="http://www.fsf.org/">Free Software Foundation</A>
 218 or email <code>ijackson@chiark.greenend.org.uk</code>.
 219
 220 <p>
 221
 222 <hr>
 223 Ian Jackson / <tt>ijackson@chiark.greenend.org.uk</tt>.
 224 <p>
 225
 226 <A href="http://www.gnu.org/">GNU home page</A>;
 227 <A href="http://www.chiark.greenend.org.uk/">chiark home page</A>;
 228 <A href="/">site or mirror home page</A>
 229 <p>
 230
 231 This web page is Copyright (C)1996-2005,2014 Ian Jackson.  See the
 232 <A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>.
 233
 234 </body>
 235 </html>