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