Commit | Line | Data |
---|---|---|
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 | |
2a9e6abd IJ |
40 | for a C program - there is no need to deal with DNS packet and RRDATA |
41 | formats. | |
630bf698 | 42 | |
43 | <li>Sanity checking (eg, name syntax checking, reverse/forward | |
2a9e6abd IJ |
44 | correspondence, CNAME pointing to CNAME) is performed automatically |
45 | by default. | |
630bf698 | 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 | ||
2a9e6abd IJ |
57 | <li>adns understands conventional resolv.conf, but this can overridden |
58 | by environment variables. | |
630bf698 | 59 | |
60 | <li>Flexibility. For example, the application can tell adns to: | |
8e5a4960 | 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. | |
630bf698 | 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 | ||
8e5a4960 | 71 | <h2>DNS utility programs</h2> |
72 | ||
630bf698 | 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 | |
8e5a4960 | 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 | |
5a111351 | 91 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adnshost.txt">adnshost |
b6922f88 | 92 | usage message</A> for a summary of its capabilities. |
630bf698 | 93 | |
94 | </ul> | |
95 | ||
630bf698 | 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 | |
5a111351 | 100 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adns.h.txt">commented |
8e5a4960 | 101 | adns.h header file</A>, and the usage messages for the programs should |
102 | be sufficient. | |
630bf698 | 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 | ||
2a9e6abd IJ |
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>. | |
630bf698 | 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 | |
b6922f88 | 130 | will contain only announcements of important bugs, new versions, etc. |
630bf698 | 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 | ||
2a9e6abd | 141 | <h2>Documentation</h2> |
630bf698 | 142 | |
630bf698 | 143 | <ul> |
5a111351 | 144 | <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adns.h.txt">adns.h |
2a9e6abd | 145 | API header file with documentation comments</A> |
5a111351 | 146 | <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adnshost.txt">usage |
2a9e6abd | 147 | message for adnshost</A> |
630bf698 | 148 | </ul> |
149 | ||
2a9e6abd IJ |
150 | <h2>Download and source code</h2> |
151 | ||
ea5ac657 | 152 | <ul> |
2a9e6abd IJ |
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 | |
827228ec | 156 | versions</A> and other files (including OpenPGP signatures). |
2a9e6abd IJ |
157 | <li><A href="http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/adns.git/">master |
158 | git (version control) repository browser</a>. | |
ea5ac657 | 159 | </ul> |
160 | ||
630bf698 | 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 | ||
2a9e6abd | 165 | <h2>Installation note</h2> |
b6922f88 | 166 | |
e86aa5ef IJ |
167 | adns requires a real nameserver like BIND running on the same system |
168 | or a nearby one, which must be willing to provide `recursive service'. | |
169 | I.e., adns is a `stub resolver'. | |
2a9e6abd IJ |
170 | |
171 | <p> | |
172 | adns requires that your real nameserver is on the same machine, or | |
173 | connected via a secure network, so that an attacker cannot fake the | |
174 | replies to adns's queries. | |
b6922f88 | 175 | |
4fde3e92 | 176 | <h2>References and related projects</h2> |
177 | ||
4f85494a | 178 | <ul> |
1f2daabb | 179 | <li><a href="http://code.google.com/p/adns-python">Python bindings</a> |
4f85494a | 180 | by Andy Dustman. |
2a9e6abd IJ |
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. | |
4f85494a | 185 | <li><a href="http://adns.jgaa.com/">port to MS Visual Studio 6 C++</a> |
217cfd38 | 186 | by Jarle Aase. |
4f85494a | 187 | </ul> |
4fde3e92 | 188 | |
630bf698 | 189 | <h2>Copyright and licensing</h2> |
190 | ||
2a9e6abd IJ |
191 | <kbd>adns</kbd> is Copyright 1997-2000,2003,2006,2014 Ian Jackson, |
192 | Copyright 2014 Mark Wooding, Copyright 1999-2000,2003,2006 Tony Finch, | |
193 | and Copyright (C) 1991 Massachusetts Institute of Technology. | |
630bf698 | 194 | |
195 | <p> | |
196 | ||
197 | <kbd>adns</kbd> is free software; you can redistribute it and/or modify | |
198 | it under the terms of the GNU General Public License as published by | |
2a9e6abd | 199 | the Free Software Foundation; either version 3 of the License, or (at |
630bf698 | 200 | your option) any later version. |
201 | ||
202 | <p> | |
203 | ||
204 | This program and documentation is distributed in the hope that it will | |
205 | be useful, but <em>without any warranty</em>; without even the implied | |
206 | warranty of <em>merchantability</em> or <em>fitness for a particular | |
207 | purpose</em>. See the | |
5a111351 | 208 | <A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/COPYING.txt">GNU |
630bf698 | 209 | General Public License</A> for more details. |
210 | ||
211 | <p> | |
212 | ||
213 | You should have received a copy of the GNU General Public License | |
214 | along with <kbd>adns</kbd>, or one should be available above; if not, | |
2a9e6abd IJ |
215 | write to the <A href="http://www.fsf.org/">Free Software Foundation</A> |
216 | or email <code>ijackson@chiark.greenend.org.uk</code>. | |
630bf698 | 217 | |
218 | <p> | |
219 | ||
220 | <hr> | |
2a9e6abd | 221 | Ian Jackson / <tt>ijackson@chiark.greenend.org.uk</tt>. |
630bf698 | 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 | ||
2a9e6abd | 229 | This web page is Copyright (C)1996-2005,2014 Ian Jackson. See the |
630bf698 | 230 | <A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>. |
630bf698 | 231 | |
232 | </body> | |
233 | </html> |