1 .TH "libunbound" "3" "Dec 10, 2015" "NLnet Labs" "unbound 1.5.7"
3 .\" libunbound.3 -- unbound library functions manual
5 .\" Copyright (c) 2007, NLnet Labs. All rights reserved.
7 .\" See LICENSE for the license.
25 .B ub_ctx_add_ta_autr,
26 .B ub_ctx_add_ta_file,
27 .B ub_ctx_trustedkeys,
40 .B ub_ctx_print_local_zones,
42 .B ub_ctx_zone_remove,
45 \- Unbound DNS validating resolver 1.5.7 functions.
47 .B #include <unbound.h>
50 \fBub_ctx_create\fR(\fIvoid\fR);
53 \fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
56 \fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
59 \fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
62 \fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
65 \fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
68 \fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
71 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
74 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
77 \fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
80 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
83 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
86 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
89 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
92 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
95 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
98 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
101 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
104 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
107 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
109 \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
112 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
114 \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
116 \fIub_callback_t\fR callback, \fIint*\fR async_id);
119 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
122 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
125 \fBub_strerror\fR(\fIint\fR err);
128 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
131 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
134 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
137 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
140 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
143 is an implementation of a DNS resolver, that does caching and
144 DNSSEC validation. This is the library API, for using the \-lunbound library.
145 The server daemon is described in \fIunbound\fR(8).
146 The library can be used to convert hostnames to ip addresses, and back,
147 and obtain other information from the DNS. The library performs public\-key
148 validation of results with DNSSEC.
150 The library uses a variable of type \fIstruct ub_ctx\fR to keep context
151 between calls. The user must maintain it, creating it with
155 It can be created and deleted at any time. Creating it anew removes any
156 previous configuration (such as trusted keys) and clears any cached results.
158 The functions are thread\-safe, and a context an be used in a threaded (as
159 well as in a non\-threaded) environment. Also resolution (and validation)
160 can be performed blocking and non\-blocking (also called asynchronous).
161 The async method returns from the call immediately, so that processing
162 can go on, while the results become available later.
164 The functions are discussed in turn below.
168 Create a new context, initialised with defaults.
169 The information from /etc/resolv.conf and /etc/hosts is not utilised
175 Before you call this, use the openssl functions CRYPTO_set_id_callback and
176 CRYPTO_set_locking_callback to set up asyncronous operation if you use
177 lib openssl (the application calls these functions once for initialisation).
178 Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
181 Delete validation context and free associated resources.
182 Outstanding async queries are killed and callbacks are not called for them.
185 A power\-user interface that lets you specify one of the options from the
186 config file format, see \fIunbound.conf\fR(5). Not all options are
187 relevant. For some specific options, such as adding trust anchors, special
188 routines exist. Pass the option name with the trailing ':'.
191 A power\-user interface that gets an option value. Some options cannot be
192 gotten, and others return a newline separated list. Pass the option name
193 without trailing ':'. The returned value must be free(2)d by the caller.
196 A power\-user interface that lets you specify an unbound config file, see
197 \fIunbound.conf\fR(5), which is read for configuration. Not all options are
198 relevant. For some specific options, such as adding trust anchors, special
202 Set machine to forward DNS queries to, the caching resolver to use.
203 IP4 or IP6 address. Forwards all DNS requests to that machine, which
204 is expected to run a recursive resolver. If the proxy is not
205 DNSSEC capable, validation may fail. Can be called several times, in
206 that case the addresses are used as backup servers.
207 At this time it is only possible to set configuration before the
208 first resolve is done.
211 By default the root servers are queried and full resolver mode is used, but
212 you can use this call to read the list of nameservers to use from the
214 Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
215 If they do not support DNSSEC, validation may fail.
216 Only nameservers are picked up, the searchdomain, ndots and other
217 settings from \fIresolv.conf\fR(5) are ignored.
218 If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
219 the system\-wide configured nameserver is picked instead).
220 At this time it is only possible to set configuration before the
221 first resolve is done.
224 Read list of hosts from the filename given.
225 Usually "/etc/hosts". When queried for, these addresses are not marked
226 DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
227 (if on Windows, etc/hosts from WINDIR is picked instead).
228 At this time it is only possible to set configuration before the
229 first resolve is done.
233 Add a trust anchor to the given context.
234 At this time it is only possible to add trusted keys before the
235 first resolve is done.
236 The format is a string, similar to the zone\-file format,
237 [domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
239 .B ub_ctx_add_ta_autr
240 Add filename with automatically tracked trust anchor to the given context.
241 Pass name of a file with the managed trust anchor. You can create this
242 file with \fIunbound\-anchor\fR(8) for the root anchor. You can also
243 create it with an initial file with one line with a DNSKEY or DS record.
244 If the file is writable, it is updated when the trust anchor changes.
245 At this time it is only possible to add trusted keys before the
246 first resolve is done.
248 .B ub_ctx_add_ta_file
249 Add trust anchors to the given context.
250 Pass name of a file with DS and DNSKEY records in zone file format.
251 At this time it is only possible to add trusted keys before the
252 first resolve is done.
254 .B ub_ctx_trustedkeys
255 Add trust anchors to the given context.
256 Pass the name of a bind\-style config file with trusted\-keys{}.
257 At this time it is only possible to add trusted keys before the
258 first resolve is done.
261 Set debug and error log output to the given stream. Pass NULL to disable
262 output. Default is stderr. File\-names or using syslog can be enabled
263 using config options, this routine is for using your own stream.
266 Set debug verbosity for the context. Output is directed to stderr.
267 Higher debug level gives more output.
270 Set a context behaviour for asynchronous action.
271 if set to true, enables threading and a call to
273 creates a thread to handle work in the background.
274 If false, a process is forked to handle work in the background.
275 Changes to this setting after
277 calls have been made have no effect (delete and re\-create the context
281 Poll a context to see if it has any new results.
282 Do not poll in a loop, instead extract the fd below to poll for readiness,
283 and then check, or wait using the wait routine.
284 Returns 0 if nothing to read, or nonzero if a result is available.
290 Wait for a context to finish with results. Calls
292 after the wait for you. After the wait, there are no more outstanding
293 asynchronous queries.
296 Get file descriptor. Wait for it to become readable, at this point
297 answers are returned from the asynchronous validating resolver.
298 Then call the \fBub_process\fR to continue processing.
301 Call this routine to continue processing results from the validating
302 resolver (when the fd becomes readable).
303 Will perform necessary callbacks.
306 Perform resolution and validation of the target name.
307 The name is a domain name in a zero terminated text string.
308 The rrtype and rrclass are DNS type and class codes.
309 The result structure is newly allocated with the resulting data.
312 Perform asynchronous resolution and validation of the target name.
313 Arguments mean the same as for \fBub_resolve\fR except no
314 data is returned immediately, instead a callback is called later.
315 The callback receives a copy of the mydata pointer, that you can use to pass
316 information to the callback. The callback type is a function pointer to
317 a function declared as
319 void my_callback_function(void* my_arg, int err,
321 struct ub_result* result);
323 The async_id is returned so you can (at your option) decide to track it
324 and cancel the request if needed. If you pass a NULL pointer the async_id
328 Cancel an async query in progress. This may return an error if the query
329 does not exist, or the query is already being delivered, in that case you
330 may still get a callback for the query.
333 Free struct ub_result contents after use.
336 Convert error value from one of the unbound library functions
337 to a human readable string.
339 .B ub_ctx_print_local_zones
340 Debug printout the local authority information to debug output.
343 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
346 .B ub_ctx_zone_remove
347 Delete zone from local authority info.
350 Add resource record data to local authority info, like local\-data
351 \fIunbound.conf\fR(5) statement.
353 .B ub_ctx_data_remove
354 Delete local authority data from the name given.
355 .SH "RESULT DATA STRUCTURE"
356 The result of the DNS resolution and validation is returned as
357 \fIstruct ub_result\fR. The result structure contains the following entries.
361 char* qname; /* text string, original question */
362 int qtype; /* type code asked for */
363 int qclass; /* class code asked for */
364 char** data; /* array of rdata items, NULL terminated*/
365 int* len; /* array with lengths of rdata items */
366 char* canonname; /* canonical name of result */
367 int rcode; /* additional error code in case of no data */
368 void* answer_packet; /* full network format answer packet */
369 int answer_len; /* length of packet in octets */
370 int havedata; /* true if there is data */
371 int nxdomain; /* true if nodata because name does not exist */
372 int secure; /* true if result is secure */
373 int bogus; /* true if a security failure happened */
374 char* why_bogus; /* string with error if bogus */
375 int ttl; /* number of seconds the result is valid */
379 If both secure and bogus are false, security was not enabled for the
380 domain of the query. Else, they are not both true, one of them is true.
382 Many routines return an error code. The value 0 (zero) denotes no error
383 happened. Other values can be passed to
385 to obtain a readable error string.
387 returns a zero terminated string.
389 returns NULL on an error (a malloc failure).
391 returns true if some information may be available, false otherwise.
393 returns a file descriptor or \-1 on error.
395 \fIunbound.conf\fR(5),
399 developers are mentioned in the CREDITS file in the distribution.