ea5ac657 |
1 | <html><head><title>adns - advanced, alternative, asynchronous resolver</title> |
630bf698 |
2 | <link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk"> |
3a68c787 |
3 | <meta name="keywords" content="adns"> |
630bf698 |
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 | |
ea5ac657 |
11 | <!-- Note: this file must contain portable HTML ! --> |
b6922f88 |
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 | <!-- --> |
ea5ac657 |
18 | <!-- $Id$ --> |
b6922f88 |
19 | |
630bf698 |
20 | <p> |
21 | |
8e5a4960 |
22 | adns is a resolver library for C (and C++) programs, and a collection |
b6922f88 |
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: |
630bf698 |
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 formats. |
41 | |
42 | <li>Sanity checking (eg, name syntax checking, reverse/forward |
43 | correspondence, CNAME pointing to CNAME) is performed automatically. |
44 | |
45 | <li>Time-to-live, CNAME and other similar information is returned in |
46 | an easy-to-use form, without getting in the way. |
47 | |
48 | <li>There is no global state in the library; resolver state is an |
49 | opaque data structure which the client creates explicitly. A program |
50 | can have several instances of the resolver. |
51 | |
52 | <li>Errors are reported to the application in a way that distinguishes |
53 | the various causes of failure properly. |
54 | |
55 | <li>Understands conventional resolv.conf, but this can overridden by |
56 | environment variables. |
57 | |
58 | <li>Flexibility. For example, the application can tell adns to: |
8e5a4960 |
59 | ignore environment variables (for setuid programs), disable hostname |
60 | syntax sanity checks to return arbitrary data, override or ignore |
61 | resolv.conf in favour of supplied configuration, etc. |
630bf698 |
62 | |
63 | <li>Believed to be correct ! For example, will correctly back off to |
64 | TCP in case of long replies or queries, or to other nameservers if |
65 | several are available. It has sensible handling of bad responses etc. |
66 | |
67 | </ul> |
68 | |
8e5a4960 |
69 | <h2>DNS utility programs</h2> |
70 | |
630bf698 |
71 | adns also comes with a number of utility programs for use from the |
72 | command line and in scripts: |
73 | |
74 | <ul> |
75 | |
76 | <li><code>adnslogres</code> is a much faster version of Apache's |
77 | logresolv program. |
78 | |
79 | <li><code>adnsresfilter</code> is a filter which copies its input to |
80 | its output, replacing IP addresses by the corresponding names, without |
81 | unduly delaying the output. For example, you can usefully pipe the |
82 | output of netstat -n, tcpdump -ln, and the like, into it. |
83 | |
84 | <li><code>adnshost</code> is a general-purpose DNS lookup utility |
8e5a4960 |
85 | which can be used easily in from the command line and from shell |
86 | scripts to do simple lookups. In a more advanced mode it can be used |
87 | as a general-purpose DNS helper program for scripting languages which |
88 | can invoke and communicate with subprocesses. See the |
b6922f88 |
89 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt">adnshost |
90 | usage message</A> for a summary of its capabilities. |
630bf698 |
91 | |
92 | </ul> |
93 | |
ea5ac657 |
94 | <h2>Forthcoming:</h2> |
95 | |
96 | I hope that future versions may also have the following features: |
97 | |
98 | <ul> |
99 | |
100 | <li>The library should be useable by threads in a multithreaded |
101 | program in a natural way. It should multiplex many threads' queries |
102 | through a single query socket. |
103 | |
104 | <li>IPv6 support. |
105 | |
106 | <li>Some kind of awareness of DNSSEC. |
107 | |
108 | <li>Possibly some very limited caching behaviour. |
109 | |
110 | <li>There was, at one point, a draft native Perl interface from Tony Finch. |
111 | |
112 | </ul> |
113 | |
630bf698 |
114 | <h2>Documentation</h2> |
115 | |
116 | I'm afraid there is no manual yet. However, competent C programmers |
117 | should be able to use the library based on the |
118 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">commented |
8e5a4960 |
119 | adns.h header file</A>, and the usage messages for the programs should |
120 | be sufficient. |
630bf698 |
121 | |
122 | <h2>Feedback</h2> |
123 | |
124 | I'd be pleased if you would let me know if you're using my library in |
125 | your project, and what you think of it. |
126 | |
127 | <p> |
128 | |
129 | If you are subscribed to <code>adns-discuss</code> please send |
130 | feedback, including bug reports, there; otherwise send mail to |
131 | <code>adns-bugreports@chiark.greenend.org.uk</code>. If you'd prefer |
132 | that your message wasn't forwarded to the <code>adns-bugreports</code> |
133 | list, send it to <code>adns-maint@chiark.greenend.org.uk</code>. |
134 | |
135 | <h2>Mailinglists</h2> |
136 | |
137 | I have set up mailinglists <code>adns-announce</code> and |
138 | <code>adns-discuss</code>. The announcements list is moderated and |
b6922f88 |
139 | will contain only announcements of important bugs, new versions, etc. |
630bf698 |
140 | The bug reports address mentioned above is also a mailing list; feel |
141 | free to subscribe to it. |
142 | |
143 | <p> |
144 | |
145 | There are |
146 | <A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives |
147 | and subscription web pages</A>, or you can subscribe by sending mail |
148 | containing the word `subscribe' to |
149 | <code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or |
150 | <code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>. |
151 | |
152 | <h2>Download</h2> |
153 | |
154 | Available for download from |
155 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/">chiark.greenend.org.uk</A> |
156 | are: |
157 | <ul> |
b6922f88 |
158 | <li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current |
159 | release</A> as a gzipped tarfile. |
630bf698 |
160 | <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">adns.h</A> |
b6922f88 |
161 | API header file with comments, and |
aa3ffb57 |
162 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt">usage |
b6922f88 |
163 | message for adnshost</A> (currently there is no manual, sorry). |
630bf698 |
164 | <li>All versions released so far are also available via |
165 | <A href="ftp://ftp.chiark.greenend.org.uk/users/ian/adns/">anonymous |
3a68c787 |
166 | FTP</A> and <A href="http://www.chiark.greenend.org.uk/~ian/adns/ftp/">HTTP</A>. |
630bf698 |
167 | </ul> |
168 | |
ea5ac657 |
169 | You can also access the project CVS repositories: |
170 | <ul> |
171 | <li>A mirror of the source code repository is available via rsync from |
172 | <code>rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns</code> |
173 | (use FTP first to find your way around), or via |
174 | <A href="http://www.chiark.greenend.org.uk/ucgi/~ijackson/cvsweb/adns/">cvsweb</A>. |
175 | <li>This web page is maintained in |
176 | <A href="http://savannah.gnu.org/">Savannah</A>, |
177 | where you can browse the |
178 | <A href="http://savannah.gnu.org/cgi-bin/viewcvs/software/adns/?cvsroot=www.gnu.org">webpage CVS</A>. |
179 | </ul> |
180 | |
630bf698 |
181 | adns is also available from the |
182 | <A href="http://www.gnu.org/">GNU Project</A> FTP servers and their |
183 | <A href="http://www.gnu.org/order/ftp.html">mirrors</A>. |
184 | |
b6922f88 |
185 | <h2>Technical note</h2> |
186 | |
187 | adns requires a real nameserver like |
188 | <A href="http://www.isc.org/view.cgi?/products/BIND/index.phtml">BIND</A> |
189 | or |
190 | <A href="http://www.dents.org/">Dents</A> running on |
191 | the same system or a nearby one, which must be willing to provide |
192 | `recursive service'. I.e., adns is a `stub resolver'. All properly |
193 | configured UN*X and GNU systems will already have such nameserver(s); |
194 | they are usually listed in /etc/resolv.conf. |
195 | |
4fde3e92 |
196 | <h2>References and related projects</h2> |
197 | |
4f85494a |
198 | <ul> |
1f2daabb |
199 | <li><a href="http://code.google.com/p/adns-python">Python bindings</a> |
4f85494a |
200 | by Andy Dustman. |
201 | <li><a href="http://cryp.to/hsdns/">Haskell bindings</a> |
217cfd38 |
202 | by Peter Simons. |
4f85494a |
203 | <li><a href="http://liboop.ofb.net/ref">liboop event loop library</a> |
204 | (by Dan Egnor) has a built-in binding for adns. |
205 | <li><a href="http://adns.jgaa.com/">port to MS Visual Studio 6 C++</a> |
217cfd38 |
206 | by Jarle Aase. |
4f85494a |
207 | </ul> |
4fde3e92 |
208 | |
630bf698 |
209 | <h2>Copyright and licensing</h2> |
210 | |
ae8cc977 |
211 | <kbd>adns</kbd> is Copyright 1997-2000,2003,2006 Ian Jackson, |
212 | Copyright 1999-2000,2003,2006 Tony Finch, and Copyright (C) 1991 |
213 | Massachusetts Institute of Technology. |
630bf698 |
214 | |
215 | <p> |
216 | |
217 | <kbd>adns</kbd> is free software; you can redistribute it and/or modify |
218 | it under the terms of the GNU General Public License as published by |
219 | the Free Software Foundation; either version 2 of the License, or (at |
220 | your option) any later version. |
221 | |
222 | <p> |
223 | |
224 | This program and documentation is distributed in the hope that it will |
225 | be useful, but <em>without any warranty</em>; without even the implied |
226 | warranty of <em>merchantability</em> or <em>fitness for a particular |
227 | purpose</em>. See the |
228 | <A href="http://www.chiark.greenend.org.uk/~ian/COPYING.txt">GNU |
229 | General Public License</A> for more details. |
230 | |
231 | <p> |
232 | |
233 | You should have received a copy of the GNU General Public License |
234 | along with <kbd>adns</kbd>, or one should be available above; if not, |
235 | write to the |
236 | <A href="http://www.fsf.org/">Free Software Foundation</A>, |
237 | 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, |
238 | or email <code>adns-maint@chiark.greenend.org.uk</code>. |
239 | |
240 | <p> |
241 | |
242 | <hr> |
243 | <A href="http://www.chiark.greenend.org.uk/">Ian Jackson</A> / |
244 | <A href="mailto:adns-maint@chiark.greenend.org.uk"><tt>adns-maint@chiark.greenend.org.uk</tt></A>; |
245 | more <A href="http://www.chiark.greenend.org.uk/~ian/software/">free |
246 | software</A> by me. |
247 | <p> |
248 | |
249 | <A href="http://www.gnu.org/">GNU home page</A>; |
250 | <A href="http://www.chiark.greenend.org.uk/">chiark home page</A>; |
251 | <A href="/">site or mirror home page</A> |
252 | <p> |
253 | |
849075a0 |
254 | This web page is Copyright (C)1996-2005 Ian Jackson. See the |
630bf698 |
255 | <A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>. |
256 | <p> |
257 | |
258 | Use any browser - |
259 | <A href="http://www.anybrowser.org/campaign/">Campaign for a non-browser-specific WWW</A> |
260 | |
261 | </body> |
262 | </html> |