diff options
Diffstat (limited to 'README.html')
| -rw-r--r-- | README.html | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/README.html b/README.html new file mode 100644 index 0000000..3d7c06e --- /dev/null +++ b/README.html @@ -0,0 +1,232 @@ +<html><head><title>adns - advanced, alternative, asynchronous resolver</title> +<link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk"> +<meta name="keywords" content="adns"> +</head> +<body> +<h1>GNU adns</h1> + +<strong>Advanced, easy to use, asynchronous-capable DNS client +library and utilities.</strong> + +<!-- Note: this file must contain portable HTML ! --> +<!-- --> +<!-- It is served on the GNU site and also from my own system, --> +<!-- under the URL http://www.chiark.greenend.org.uk/adns/ --> +<!-- Please ensure that all links continine to be correct --> +<!-- both for www.gnu.org and chiark. --> +<!-- --> + +<p> + +adns is a resolver library for C (and C++) programs, and a collection +of useful DNS resolver utilities. + + +<h2>C library</h2> + +In contrast with the standard interfaces, gethostbyname et al and +libresolv, it has the following features: + +<ul> + +<li>It is reasonably easy to use for simple programs which just want +to translate names to addresses, look up MX records, etc. + +<li>It can be used in an asynchronous, non-blocking, manner. Many +queries can be handled simultaneously. + +<li>Responses are decoded automatically into a natural representation +for a C program - there is no need to deal with DNS packet and RRDATA +formats. + +<li>Sanity checking (eg, name syntax checking, reverse/forward +correspondence, CNAME pointing to CNAME) is performed automatically +by default. + +<li>Time-to-live, CNAME and other similar information is returned in +an easy-to-use form, without getting in the way. + +<li>There is no global state in the library; resolver state is an +opaque data structure which the client creates explicitly. A program +can have several instances of the resolver. + +<li>Errors are reported to the application in a way that distinguishes +the various causes of failure properly. + +<li>adns understands conventional resolv.conf, but this can overridden +by environment variables. + +<li>Flexibility. For example, the application can tell adns to: +ignore environment variables (for setuid programs), disable hostname +syntax sanity checks to return arbitrary data, override or ignore +resolv.conf in favour of supplied configuration, etc. + +<li>Believed to be correct ! For example, will correctly back off to +TCP in case of long replies or queries, or to other nameservers if +several are available. It has sensible handling of bad responses etc. + +</ul> + +<h2>DNS utility programs</h2> + +adns also comes with a number of utility programs for use from the +command line and in scripts: + +<ul> + +<li><code>adnslogres</code> is a much faster version of Apache's +logresolv program. + +<li><code>adnsresfilter</code> is a filter which copies its input to +its output, replacing IP addresses by the corresponding names, without +unduly delaying the output. For example, you can usefully pipe the +output of netstat -n, tcpdump -ln, and the like, into it. + +<li><code>adnshost</code> is a general-purpose DNS lookup utility +which can be used easily in from the command line and from shell +scripts to do simple lookups. In a more advanced mode it can be used +as a general-purpose DNS helper program for scripting languages which +can invoke and communicate with subprocesses. See the +<A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adnshost.txt">adnshost +usage message</A> for a summary of its capabilities. + +</ul> + +<h2>Documentation</h2> + +I'm afraid there is no manual yet. However, competent C programmers +should be able to use the library based on the +<A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adns.h.txt">commented +adns.h header file</A>, and the usage messages for the programs should +be sufficient. + +<h2>Feedback</h2> + +I'd be pleased if you would let me know if you're using my library in +your project, and what you think of it. + +<p> + +Bug reports should be reported to the +<a href="http://debbugs.gnu.org/">GNU Debbugs</a>. Send an email +to <code>submit@debbugs.gnu.org</code> and at the top of your email, +in a paragraph of its own, write the single line +<pre> +Package: adns +</pre> +Your bug report will be published via to the adns-discuss list. + +<p> + +Feedback and discussion takes place on the <code>adns-discuss</code> +list. You can mail me privately +at <code>ijackson@chiark.greenend.org.uk</code>. + +<h2>Mailinglists</h2> + +I have set up mailinglists <code>adns-announce</code> and +<code>adns-discuss</code>. The announcements list is moderated and +will contain only announcements of important bugs, new versions, etc. + +<p> + +There are +<A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives +and subscription web pages</A>, or you can subscribe by sending mail +containing the word `subscribe' to +<code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or +<code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>. + +<h2>Documentation</h2> + +<ul> +<li><A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adns.h.txt">adns.h + API header file with documentation comments</A> +<li><A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adnshost.txt">usage + message for adnshost</A> +</ul> + +<h2>Download and source code</h2> + +<ul> +<li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current + release</A> as a gzipped tarfile. +<li><A href="http://www.chiark.greenend.org.uk/~ian/adns/ftp/">Previous + versions</A> and other files (including OpenPGP signatures). +<li><A href="http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/adns.git/">master + git (version control) repository browser</a>. +</ul> + +adns is also available from the +<A href="http://www.gnu.org/">GNU Project</A> FTP servers and their +<A href="http://www.gnu.org/order/ftp.html">mirrors</A>. + +<h2>Installation note</h2> + +adns requires a real nameserver like BIND running on the same system +or a nearby one, which must be willing to provide `recursive service'. +I.e., adns is a `stub resolver'. + +<p> +adns requires that your real nameserver is on the same machine, or +connected via a secure network, so that an attacker cannot fake the +replies to adns's queries. + +<h2>References and related projects</h2> + +<ul> +<li><a href="http://code.google.com/p/adns-python">Python bindings</a> + by Andy Dustman. +<!-- <li><a href="http://cryp.to/hsdns/">Haskell bindings</a> + by Peter Simons. --> +<li><a href="http://www.lysator.liu.se/liboop/">liboop event loop library</a> + has a built-in binding for adns. +<li><a href="http://adns.jgaa.com/">port to MS Visual Studio 6 C++</a> + by Jarle Aase. +</ul> + +<h2>Copyright and licensing</h2> + +<kbd>adns</kbd> is Copyright 1997-2000,2003,2006,2014 Ian Jackson, +Copyright 2014 Mark Wooding, Copyright 1999-2000,2003,2006 Tony Finch, +and Copyright (C) 1991 Massachusetts Institute of Technology. + +<p> + +<kbd>adns</kbd> is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 3 of the License, or (at +your option) any later version. + +<p> + +This program and documentation is distributed in the hope that it will +be useful, but <em>without any warranty</em>; without even the implied +warranty of <em>merchantability</em> or <em>fitness for a particular +purpose</em>. See the +<A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/COPYING.txt">GNU +General Public License</A> for more details. + +<p> + +You should have received a copy of the GNU General Public License +along with <kbd>adns</kbd>, or one should be available above; if not, +write to the <A href="http://www.fsf.org/">Free Software Foundation</A> +or email <code>ijackson@chiark.greenend.org.uk</code>. + +<p> + +<hr> +Ian Jackson / <tt>ijackson@chiark.greenend.org.uk</tt>. +<p> + +<A href="http://www.gnu.org/">GNU home page</A>; +<A href="http://www.chiark.greenend.org.uk/">chiark home page</A>; +<A href="/">site or mirror home page</A> +<p> + +This web page is Copyright (C)1996-2005,2014 Ian Jackson. See the +<A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>. + +</body> +</html> |