[adns] / README.html

<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.                            -->
<!--                                                              -->
<!--  $Id$    -->   

<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>
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>
630bf698	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
2a9e6abd IJ	41	formats.
630bf698	42
630bf698	43	<li>Sanity checking (eg, name syntax checking, reverse/forward
2a9e6abd IJ	44	correspondence, CNAME pointing to CNAME) is performed automatically
2a9e6abd IJ	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
2a9e6abd IJ	58	by environment variables.
630bf698	59
630bf698	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>
8e5a4960	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
8e5a4960	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>
630bf698	149
2a9e6abd IJ	150	<h2>Download and source code</h2>
2a9e6abd IJ	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
2a9e6abd IJ	158	git (version control) repository browser</a>.
ea5ac657	159	</ul>
ea5ac657	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>
4fde3e92	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>
630bf698	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>
2a9e6abd IJ	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>