evdns.3 (11563B)
1 .\" 2 .\" Copyright (c) 2006 Niels Provos <provos@citi.umich.edu> 3 .\" All rights reserved. 4 .\" 5 .\" Redistribution and use in source and binary forms, with or without 6 .\" modification, are permitted provided that the following conditions 7 .\" are met: 8 .\" 9 .\" 1. Redistributions of source code must retain the above copyright 10 .\" notice, this list of conditions and the following disclaimer. 11 .\" 2. Redistributions in binary form must reproduce the above copyright 12 .\" notice, this list of conditions and the following disclaimer in the 13 .\" documentation and/or other materials provided with the distribution. 14 .\" 3. The name of the author may not be used to endorse or promote products 15 .\" derived from this software without specific prior written permission. 16 .\" 17 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 19 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 20 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 21 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 22 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 23 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 25 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 26 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 .\" 28 .Dd October 7, 2006 29 .Dt EVDNS 3 30 .Os 31 .Sh NAME 32 .Nm evdns_init 33 .Nm evdns_shutdown 34 .Nm evdns_err_to_string 35 .Nm evdns_nameserver_add 36 .Nm evdns_count_nameservers 37 .Nm evdns_clear_nameservers_and_suspend 38 .Nm evdns_resume 39 .Nm evdns_nameserver_ip_add 40 .Nm evdns_resolve_ipv4 41 .Nm evdns_resolve_reverse 42 .Nm evdns_resolv_conf_parse 43 .Nm evdns_config_windows_nameservers 44 .Nm evdns_search_clear 45 .Nm evdns_search_add 46 .Nm evdns_search_ndots_set 47 .Nm evdns_set_log_fn 48 .Nd asynchronous functions for DNS resolution. 49 .Sh SYNOPSIS 50 .Fd #include <sys/time.h> 51 .Fd #include <event.h> 52 .Fd #include <evdns.h> 53 .Ft int 54 .Fn evdns_init 55 .Ft void 56 .Fn evdns_shutdown "int fail_requests" 57 .Ft "const char *" 58 .Fn evdns_err_to_string "int err" 59 .Ft int 60 .Fn evdns_nameserver_add "unsigned long int address" 61 .Ft int 62 .Fn evdns_count_nameservers 63 .Ft int 64 .Fn evdns_clear_nameservers_and_suspend 65 .Ft int 66 .Fn evdns_resume 67 .Ft int 68 .Fn evdns_nameserver_ip_add(const char *ip_as_string); 69 .Ft int 70 .Fn evdns_resolve_ipv4 "const char *name" "int flags" "evdns_callback_type callback" "void *ptr" 71 .Ft int 72 .Fn evdns_resolve_reverse "struct in_addr *in" "int flags" "evdns_callback_type callback" "void *ptr" 73 .Ft int 74 .Fn evdns_resolv_conf_parse "int flags" "const char *" 75 .Ft void 76 .Fn evdns_search_clear 77 .Ft void 78 .Fn evdns_search_add "const char *domain" 79 .Ft void 80 .Fn evdns_search_ndots_set "const int ndots" 81 .Ft void 82 .Fn evdns_set_log_fn "evdns_debug_log_fn_type fn" 83 .Ft int 84 .Fn evdns_config_windows_nameservers 85 .Sh DESCRIPTION 86 Welcome, gentle reader 87 .Pp 88 Async DNS lookups are really a whole lot harder than they should be, 89 mostly stemming from the fact that the libc resolver has never been 90 very good at them. Before you use this library you should see if libc 91 can do the job for you with the modern async call getaddrinfo_a 92 (see http://www.imperialviolet.org/page25.html#e498). Otherwise, 93 please continue. 94 .Pp 95 This code is based on libevent and you must call event_init before 96 any of the APIs in this file. You must also seed the OpenSSL random 97 source if you are using OpenSSL for ids (see below). 98 .Pp 99 This library is designed to be included and shipped with your source 100 code. You statically link with it. You should also test for the 101 existence of strtok_r and define HAVE_STRTOK_R if you have it. 102 .Pp 103 The DNS protocol requires a good source of id numbers and these 104 numbers should be unpredictable for spoofing reasons. There are 105 three methods for generating them here and you must define exactly 106 one of them. In increasing order of preference: 107 .Pp 108 .Bl -tag -width "DNS_USE_GETTIMEOFDAY_FOR_ID" -compact -offset indent 109 .It DNS_USE_GETTIMEOFDAY_FOR_ID 110 Using the bottom 16 bits of the usec result from gettimeofday. This 111 is a pretty poor solution but should work anywhere. 112 .It DNS_USE_CPU_CLOCK_FOR_ID 113 Using the bottom 16 bits of the nsec result from the CPU's time 114 counter. This is better, but may not work everywhere. Requires 115 POSIX realtime support and you'll need to link against -lrt on 116 glibc systems at least. 117 .It DNS_USE_OPENSSL_FOR_ID 118 Uses the OpenSSL RAND_bytes call to generate the data. You must 119 have seeded the pool before making any calls to this library. 120 .El 121 .Pp 122 The library keeps track of the state of nameservers and will avoid 123 them when they go down. Otherwise it will round robin between them. 124 .Pp 125 Quick start guide: 126 #include "evdns.h" 127 void callback(int result, char type, int count, int ttl, 128 void *addresses, void *arg); 129 evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf"); 130 evdns_resolve("www.hostname.com", 0, callback, NULL); 131 .Pp 132 When the lookup is complete the callback function is called. The 133 first argument will be one of the DNS_ERR_* defines in evdns.h. 134 Hopefully it will be DNS_ERR_NONE, in which case type will be 135 DNS_IPv4_A, count will be the number of IP addresses, ttl is the time 136 which the data can be cached for (in seconds), addresses will point 137 to an array of uint32_t's and arg will be whatever you passed to 138 evdns_resolve. 139 .Pp 140 Searching: 141 .Pp 142 In order for this library to be a good replacement for glibc's resolver it 143 supports searching. This involves setting a list of default domains, in 144 which names will be queried for. The number of dots in the query name 145 determines the order in which this list is used. 146 .Pp 147 Searching appears to be a single lookup from the point of view of the API, 148 although many DNS queries may be generated from a single call to 149 evdns_resolve. Searching can also drastically slow down the resolution 150 of names. 151 .Pp 152 To disable searching: 153 .Bl -enum -compact -offset indent 154 .It 155 Never set it up. If you never call 156 .Fn evdns_resolv_conf_parse, 157 .Fn evdns_init, 158 or 159 .Fn evdns_search_add 160 then no searching will occur. 161 .It 162 If you do call 163 .Fn evdns_resolv_conf_parse 164 then don't pass 165 .Va DNS_OPTION_SEARCH 166 (or 167 .Va DNS_OPTIONS_ALL, 168 which implies it). 169 .It 170 When calling 171 .Fn evdns_resolve, 172 pass the 173 .Va DNS_QUERY_NO_SEARCH 174 flag. 175 .El 176 .Pp 177 The order of searches depends on the number of dots in the name. If the 178 number is greater than the ndots setting then the names is first tried 179 globally. Otherwise each search domain is appended in turn. 180 .Pp 181 The ndots setting can either be set from a resolv.conf, or by calling 182 evdns_search_ndots_set. 183 .Pp 184 For example, with ndots set to 1 (the default) and a search domain list of 185 ["myhome.net"]: 186 Query: www 187 Order: www.myhome.net, www. 188 .Pp 189 Query: www.abc 190 Order: www.abc., www.abc.myhome.net 191 .Pp 192 .Sh API reference 193 .Pp 194 .Bl -tag -width 0123456 195 .It Ft int Fn evdns_init 196 Initializes support for non-blocking name resolution by calling 197 .Fn evdns_resolv_conf_parse 198 on UNIX and 199 .Fn evdns_config_windows_nameservers 200 on Windows. 201 .It Ft int Fn evdns_nameserver_add "unsigned long int address" 202 Add a nameserver. The address should be an IP address in 203 network byte order. The type of address is chosen so that 204 it matches in_addr.s_addr. 205 Returns non-zero on error. 206 .It Ft int Fn evdns_nameserver_ip_add "const char *ip_as_string" 207 This wraps the above function by parsing a string as an IP 208 address and adds it as a nameserver. 209 Returns non-zero on error 210 .It Ft int Fn evdns_resolve "const char *name" "int flags" "evdns_callback_type callback" "void *ptr" 211 Resolve a name. The name parameter should be a DNS name. 212 The flags parameter should be 0, or DNS_QUERY_NO_SEARCH 213 which disables searching for this query. (see defn of 214 searching above). 215 .Pp 216 The callback argument is a function which is called when 217 this query completes and ptr is an argument which is passed 218 to that callback function. 219 .Pp 220 Returns non-zero on error 221 .It Ft void Fn evdns_search_clear 222 Clears the list of search domains 223 .It Ft void Fn evdns_search_add "const char *domain" 224 Add a domain to the list of search domains 225 .It Ft void Fn evdns_search_ndots_set "int ndots" 226 Set the number of dots which, when found in a name, causes 227 the first query to be without any search domain. 228 .It Ft int Fn evdns_count_nameservers "void" 229 Return the number of configured nameservers (not necessarily the 230 number of running nameservers). This is useful for double-checking 231 whether our calls to the various nameserver configuration functions 232 have been successful. 233 .It Ft int Fn evdns_clear_nameservers_and_suspend "void" 234 Remove all currently configured nameservers, and suspend all pending 235 resolves. Resolves will not necessarily be re-attempted until 236 evdns_resume() is called. 237 .It Ft int Fn evdns_resume "void" 238 Re-attempt resolves left in limbo after an earlier call to 239 evdns_clear_nameservers_and_suspend(). 240 .It Ft int Fn evdns_config_windows_nameservers "void" 241 Attempt to configure a set of nameservers based on platform settings on 242 a win32 host. Preferentially tries to use GetNetworkParams; if that fails, 243 looks in the registry. Returns 0 on success, nonzero on failure. 244 .It Ft int Fn evdns_resolv_conf_parse "int flags" "const char *filename" 245 Parse a resolv.conf like file from the given filename. 246 .Pp 247 See the man page for resolv.conf for the format of this file. 248 The flags argument determines what information is parsed from 249 this file: 250 .Bl -tag -width "DNS_OPTION_NAMESERVERS" -offset indent -compact -nested 251 .It DNS_OPTION_SEARCH 252 domain, search and ndots options 253 .It DNS_OPTION_NAMESERVERS 254 nameserver lines 255 .It DNS_OPTION_MISC 256 timeout and attempts options 257 .It DNS_OPTIONS_ALL 258 all of the above 259 .El 260 .Pp 261 The following directives are not parsed from the file: 262 sortlist, rotate, no-check-names, inet6, debug 263 .Pp 264 Returns non-zero on error: 265 .Bl -tag -width "0" -offset indent -compact -nested 266 .It 0 267 no errors 268 .It 1 269 failed to open file 270 .It 2 271 failed to stat file 272 .It 3 273 file too large 274 .It 4 275 out of memory 276 .It 5 277 short read from file 278 .El 279 .El 280 .Sh Internals: 281 Requests are kept in two queues. The first is the inflight queue. In 282 this queue requests have an allocated transaction id and nameserver. 283 They will soon be transmitted if they haven't already been. 284 .Pp 285 The second is the waiting queue. The size of the inflight ring is 286 limited and all other requests wait in waiting queue for space. This 287 bounds the number of concurrent requests so that we don't flood the 288 nameserver. Several algorithms require a full walk of the inflight 289 queue and so bounding its size keeps thing going nicely under huge 290 (many thousands of requests) loads. 291 .Pp 292 If a nameserver loses too many requests it is considered down and we 293 try not to use it. After a while we send a probe to that nameserver 294 (a lookup for google.com) and, if it replies, we consider it working 295 again. If the nameserver fails a probe we wait longer to try again 296 with the next probe. 297 .Sh SEE ALSO 298 .Xr event 3 , 299 .Xr gethostbyname 3 , 300 .Xr resolv.conf 5 301 .Sh HISTORY 302 The 303 .Nm evdns 304 API was developed by Adam Langley on top of the 305 .Nm libevent 306 API. 307 The code was integrate into 308 .Nm Tor 309 by Nick Mathewson and finally put into 310 .Nm libevent 311 itself by Niels Provos. 312 .Sh AUTHORS 313 The 314 .Nm evdns 315 API and code was written by Adam Langley with significant 316 contributions by Nick Mathewson. 317 .Sh BUGS 318 This documentation is neither complete nor authoritative. 319 If you are in doubt about the usage of this API then 320 check the source code to find out how it works, write 321 up the missing piece of documentation and send it to 322 me for inclusion in this man page.