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