OLD | NEW |
| (Empty) |
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 callb
ack" "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. | |
OLD | NEW |