323 lines
11 KiB
Groff
323 lines
11 KiB
Groff
|
.\"
|
||
|
|
.\" Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
|
||
|
|
.\" All rights reserved.
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\"
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
||
|
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
||
|
|
.\" derived from this software without specific prior written permission.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
|
||
|
|
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
||
|
|
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
|
||
|
|
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
||
|
|
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
||
|
|
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
|
||
|
|
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
|
||
|
|
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
|
||
|
|
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
|
||
|
|
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
.\"
|
||
|
|
.Dd October 7, 2006
|
||
|
|
.Dt EVDNS 3
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm evdns_init
|
||
|
|
.Nm evdns_shutdown
|
||
|
|
.Nm evdns_err_to_string
|
||
|
|
.Nm evdns_nameserver_add
|
||
|
|
.Nm evdns_count_nameservers
|
||
|
|
.Nm evdns_clear_nameservers_and_suspend
|
||
|
|
.Nm evdns_resume
|
||
|
|
.Nm evdns_nameserver_ip_add
|
||
|
|
.Nm evdns_resolve_ipv4
|
||
|
|
.Nm evdns_resolve_reverse
|
||
|
|
.Nm evdns_resolv_conf_parse
|
||
|
|
.Nm evdns_config_windows_nameservers
|
||
|
|
.Nm evdns_search_clear
|
||
|
|
.Nm evdns_search_add
|
||
|
|
.Nm evdns_search_ndots_set
|
||
|
|
.Nm evdns_set_log_fn
|
||
|
|
.Nd asynchronous functions for DNS resolution.
|
||
|
|
.Sh SYNOPSIS
|
||
|
|
.Fd #include <sys/time.h>
|
||
|
|
.Fd #include <event.h>
|
||
|
|
.Fd #include <evdns.h>
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_init
|
||
|
|
.Ft void
|
||
|
|
.Fn evdns_shutdown "int fail_requests"
|
||
|
|
.Ft "const char *"
|
||
|
|
.Fn evdns_err_to_string "int err"
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_nameserver_add "unsigned long int address"
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_count_nameservers
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_clear_nameservers_and_suspend
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_resume
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_nameserver_ip_add(const char *ip_as_string);
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_resolve_ipv4 "const char *name" "int flags" "evdns_callback_type callback" "void *ptr"
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_resolve_reverse "struct in_addr *in" "int flags" "evdns_callback_type callback" "void *ptr"
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_resolv_conf_parse "int flags" "const char *"
|
||
|
|
.Ft void
|
||
|
|
.Fn evdns_search_clear
|
||
|
|
.Ft void
|
||
|
|
.Fn evdns_search_add "const char *domain"
|
||
|
|
.Ft void
|
||
|
|
.Fn evdns_search_ndots_set "const int ndots"
|
||
|
|
.Ft void
|
||
|
|
.Fn evdns_set_log_fn "evdns_debug_log_fn_type fn"
|
||
|
|
.Ft int
|
||
|
|
.Fn evdns_config_windows_nameservers
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
Welcome, gentle reader
|
||
|
|
.Pp
|
||
|
|
Async DNS lookups are really a whole lot harder than they should be,
|
||
|
|
mostly stemming from the fact that the libc resolver has never been
|
||
|
|
very good at them. Before you use this library you should see if libc
|
||
|
|
can do the job for you with the modern async call getaddrinfo_a
|
||
|
|
(see http://www.imperialviolet.org/page25.html#e498). Otherwise,
|
||
|
|
please continue.
|
||
|
|
.Pp
|
||
|
|
This code is based on libevent and you must call event_init before
|
||
|
|
any of the APIs in this file. You must also seed the OpenSSL random
|
||
|
|
source if you are using OpenSSL for ids (see below).
|
||
|
|
.Pp
|
||
|
|
This library is designed to be included and shipped with your source
|
||
|
|
code. You statically link with it. You should also test for the
|
||
|
|
existence of strtok_r and define HAVE_STRTOK_R if you have it.
|
||
|
|
.Pp
|
||
|
|
The DNS protocol requires a good source of id numbers and these
|
||
|
|
numbers should be unpredictable for spoofing reasons. There are
|
||
|
|
three methods for generating them here and you must define exactly
|
||
|
|
one of them. In increasing order of preference:
|
||
|
|
.Pp
|
||
|
|
.Bl -tag -width "DNS_USE_GETTIMEOFDAY_FOR_ID" -compact -offset indent
|
||
|
|
.It DNS_USE_GETTIMEOFDAY_FOR_ID
|
||
|
|
Using the bottom 16 bits of the usec result from gettimeofday. This
|
||
|
|
is a pretty poor solution but should work anywhere.
|
||
|
|
.It DNS_USE_CPU_CLOCK_FOR_ID
|
||
|
|
Using the bottom 16 bits of the nsec result from the CPU's time
|
||
|
|
counter. This is better, but may not work everywhere. Requires
|
||
|
|
POSIX realtime support and you'll need to link against -lrt on
|
||
|
|
glibc systems at least.
|
||
|
|
.It DNS_USE_OPENSSL_FOR_ID
|
||
|
|
Uses the OpenSSL RAND_bytes call to generate the data. You must
|
||
|
|
have seeded the pool before making any calls to this library.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
The library keeps track of the state of nameservers and will avoid
|
||
|
|
them when they go down. Otherwise it will round robin between them.
|
||
|
|
.Pp
|
||
|
|
Quick start guide:
|
||
|
|
#include "evdns.h"
|
||
|
|
void callback(int result, char type, int count, int ttl,
|
||
|
|
void *addresses, void *arg);
|
||
|
|
evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
|
||
|
|
evdns_resolve("www.hostname.com", 0, callback, NULL);
|
||
|
|
.Pp
|
||
|
|
When the lookup is complete the callback function is called. The
|
||
|
|
first argument will be one of the DNS_ERR_* defines in evdns.h.
|
||
|
|
Hopefully it will be DNS_ERR_NONE, in which case type will be
|
||
|
|
DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
|
||
|
|
which the data can be cached for (in seconds), addresses will point
|
||
|
|
to an array of uint32_t's and arg will be whatever you passed to
|
||
|
|
evdns_resolve.
|
||
|
|
.Pp
|
||
|
|
Searching:
|
||
|
|
.Pp
|
||
|
|
In order for this library to be a good replacement for glibc's resolver it
|
||
|
|
supports searching. This involves setting a list of default domains, in
|
||
|
|
which names will be queried for. The number of dots in the query name
|
||
|
|
determines the order in which this list is used.
|
||
|
|
.Pp
|
||
|
|
Searching appears to be a single lookup from the point of view of the API,
|
||
|
|
although many DNS queries may be generated from a single call to
|
||
|
|
evdns_resolve. Searching can also drastically slow down the resolution
|
||
|
|
of names.
|
||
|
|
.Pp
|
||
|
|
To disable searching:
|
||
|
|
.Bl -enum -compact -offset indent
|
||
|
|
.It
|
||
|
|
Never set it up. If you never call
|
||
|
|
.Fn evdns_resolv_conf_parse,
|
||
|
|
.Fn evdns_init,
|
||
|
|
or
|
||
|
|
.Fn evdns_search_add
|
||
|
|
then no searching will occur.
|
||
|
|
.It
|
||
|
|
If you do call
|
||
|
|
.Fn evdns_resolv_conf_parse
|
||
|
|
then don't pass
|
||
|
|
.Va DNS_OPTION_SEARCH
|
||
|
|
(or
|
||
|
|
.Va DNS_OPTIONS_ALL,
|
||
|
|
which implies it).
|
||
|
|
.It
|
||
|
|
When calling
|
||
|
|
.Fn evdns_resolve,
|
||
|
|
pass the
|
||
|
|
.Va DNS_QUERY_NO_SEARCH
|
||
|
|
flag.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
The order of searches depends on the number of dots in the name. If the
|
||
|
|
number is greater than the ndots setting then the names is first tried
|
||
|
|
globally. Otherwise each search domain is appended in turn.
|
||
|
|
.Pp
|
||
|
|
The ndots setting can either be set from a resolv.conf, or by calling
|
||
|
|
evdns_search_ndots_set.
|
||
|
|
.Pp
|
||
|
|
For example, with ndots set to 1 (the default) and a search domain list of
|
||
|
|
["myhome.net"]:
|
||
|
|
Query: www
|
||
|
|
Order: www.myhome.net, www.
|
||
|
|
.Pp
|
||
|
|
Query: www.abc
|
||
|
|
Order: www.abc., www.abc.myhome.net
|
||
|
|
.Pp
|
||
|
|
.Sh API reference
|
||
|
|
.Pp
|
||
|
|
.Bl -tag -width 0123456
|
||
|
|
.It Ft int Fn evdns_init
|
||
|
|
Initializes support for non-blocking name resolution by calling
|
||
|
|
.Fn evdns_resolv_conf_parse
|
||
|
|
on UNIX and
|
||
|
|
.Fn evdns_config_windows_nameservers
|
||
|
|
on Windows.
|
||
|
|
.It Ft int Fn evdns_nameserver_add "unsigned long int address"
|
||
|
|
Add a nameserver. The address should be an IP address in
|
||
|
|
network byte order. The type of address is chosen so that
|
||
|
|
it matches in_addr.s_addr.
|
||
|
|
Returns non-zero on error.
|
||
|
|
.It Ft int Fn evdns_nameserver_ip_add "const char *ip_as_string"
|
||
|
|
This wraps the above function by parsing a string as an IP
|
||
|
|
address and adds it as a nameserver.
|
||
|
|
Returns non-zero on error
|
||
|
|
.It Ft int Fn evdns_resolve "const char *name" "int flags" "evdns_callback_type callback" "void *ptr"
|
||
|
|
Resolve a name. The name parameter should be a DNS name.
|
||
|
|
The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
|
||
|
|
which disables searching for this query. (see defn of
|
||
|
|
searching above).
|
||
|
|
.Pp
|
||
|
|
The callback argument is a function which is called when
|
||
|
|
this query completes and ptr is an argument which is passed
|
||
|
|
to that callback function.
|
||
|
|
.Pp
|
||
|
|
Returns non-zero on error
|
||
|
|
.It Ft void Fn evdns_search_clear
|
||
|
|
Clears the list of search domains
|
||
|
|
.It Ft void Fn evdns_search_add "const char *domain"
|
||
|
|
Add a domain to the list of search domains
|
||
|
|
.It Ft void Fn evdns_search_ndots_set "int ndots"
|
||
|
|
Set the number of dots which, when found in a name, causes
|
||
|
|
the first query to be without any search domain.
|
||
|
|
.It Ft int Fn evdns_count_nameservers "void"
|
||
|
|
Return the number of configured nameservers (not necessarily the
|
||
|
|
number of running nameservers). This is useful for double-checking
|
||
|
|
whether our calls to the various nameserver configuration functions
|
||
|
|
have been successful.
|
||
|
|
.It Ft int Fn evdns_clear_nameservers_and_suspend "void"
|
||
|
|
Remove all currently configured nameservers, and suspend all pending
|
||
|
|
resolves. Resolves will not necessarily be re-attempted until
|
||
|
|
evdns_resume() is called.
|
||
|
|
.It Ft int Fn evdns_resume "void"
|
||
|
|
Re-attempt resolves left in limbo after an earlier call to
|
||
|
|
evdns_clear_nameservers_and_suspend().
|
||
|
|
.It Ft int Fn evdns_config_windows_nameservers "void"
|
||
|
|
Attempt to configure a set of nameservers based on platform settings on
|
||
|
|
a win32 host. Preferentially tries to use GetNetworkParams; if that fails,
|
||
|
|
looks in the registry. Returns 0 on success, nonzero on failure.
|
||
|
|
.It Ft int Fn evdns_resolv_conf_parse "int flags" "const char *filename"
|
||
|
|
Parse a resolv.conf like file from the given filename.
|
||
|
|
.Pp
|
||
|
|
See the man page for resolv.conf for the format of this file.
|
||
|
|
The flags argument determines what information is parsed from
|
||
|
|
this file:
|
||
|
|
.Bl -tag -width "DNS_OPTION_NAMESERVERS" -offset indent -compact -nested
|
||
|
|
.It DNS_OPTION_SEARCH
|
||
|
|
domain, search and ndots options
|
||
|
|
.It DNS_OPTION_NAMESERVERS
|
||
|
|
nameserver lines
|
||
|
|
.It DNS_OPTION_MISC
|
||
|
|
timeout and attempts options
|
||
|
|
.It DNS_OPTIONS_ALL
|
||
|
|
all of the above
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
The following directives are not parsed from the file:
|
||
|
|
sortlist, rotate, no-check-names, inet6, debug
|
||
|
|
.Pp
|
||
|
|
Returns non-zero on error:
|
||
|
|
.Bl -tag -width "0" -offset indent -compact -nested
|
||
|
|
.It 0
|
||
|
|
no errors
|
||
|
|
.It 1
|
||
|
|
failed to open file
|
||
|
|
.It 2
|
||
|
|
failed to stat file
|
||
|
|
.It 3
|
||
|
|
file too large
|
||
|
|
.It 4
|
||
|
|
out of memory
|
||
|
|
.It 5
|
||
|
|
short read from file
|
||
|
|
.El
|
||
|
|
.El
|
||
|
|
.Sh Internals:
|
||
|
|
Requests are kept in two queues. The first is the inflight queue. In
|
||
|
|
this queue requests have an allocated transaction id and nameserver.
|
||
|
|
They will soon be transmitted if they haven't already been.
|
||
|
|
.Pp
|
||
|
|
The second is the waiting queue. The size of the inflight ring is
|
||
|
|
limited and all other requests wait in waiting queue for space. This
|
||
|
|
bounds the number of concurrent requests so that we don't flood the
|
||
|
|
nameserver. Several algorithms require a full walk of the inflight
|
||
|
|
queue and so bounding its size keeps thing going nicely under huge
|
||
|
|
(many thousands of requests) loads.
|
||
|
|
.Pp
|
||
|
|
If a nameserver loses too many requests it is considered down and we
|
||
|
|
try not to use it. After a while we send a probe to that nameserver
|
||
|
|
(a lookup for google.com) and, if it replies, we consider it working
|
||
|
|
again. If the nameserver fails a probe we wait longer to try again
|
||
|
|
with the next probe.
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr event 3 ,
|
||
|
|
.Xr gethostbyname 3 ,
|
||
|
|
.Xr resolv.conf 5
|
||
|
|
.Sh HISTORY
|
||
|
|
The
|
||
|
|
.Nm evdns
|
||
|
|
API was developed by Adam Langley on top of the
|
||
|
|
.Nm libevent
|
||
|
|
API.
|
||
|
|
The code was integrate into
|
||
|
|
.Nm Tor
|
||
|
|
by Nick Mathewson and finally put into
|
||
|
|
.Nm libevent
|
||
|
|
itself by Niels Provos.
|
||
|
|
.Sh AUTHORS
|
||
|
|
The
|
||
|
|
.Nm evdns
|
||
|
|
API and code was written by Adam Langley with significant
|
||
|
|
contributions by Nick Mathewson.
|
||
|
|
.Sh BUGS
|
||
|
|
This documentation is neither complete nor authoritative.
|
||
|
|
If you are in doubt about the usage of this API then
|
||
|
|
check the source code to find out how it works, write
|
||
|
|
up the missing piece of documentation and send it to
|
||
|
|
me for inclusion in this man page.
|