1 .TH "libunbound" "3" "Jun 27, 2017" "NLnet Labs" "unbound 1.6.4"
3 .\" libunbound.3 -- unbound library functions manual
5 .\" Copyright (c) 2007, NLnet Labs. All rights reserved.
7 .\" See LICENSE for the license.
26 .B ub_ctx_add_ta_autr,
27 .B ub_ctx_add_ta_file,
28 .B ub_ctx_trustedkeys,
41 .B ub_ctx_print_local_zones,
43 .B ub_ctx_zone_remove,
46 \- Unbound DNS validating resolver 1.6.4 functions.
48 .B #include <unbound.h>
51 \fBub_ctx_create\fR(\fIvoid\fR);
54 \fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx);
57 \fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val);
60 \fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val);
63 \fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
66 \fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr);
69 \fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone,
75 \fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
78 \fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
81 \fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta);
84 \fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
87 \fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
90 \fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname);
93 \fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out);
96 \fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d);
99 \fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread);
102 \fBub_poll\fR(\fIstruct ub_ctx*\fR ctx);
105 \fBub_wait\fR(\fIstruct ub_ctx*\fR ctx);
108 \fBub_fd\fR(\fIstruct ub_ctx*\fR ctx);
111 \fBub_process\fR(\fIstruct ub_ctx*\fR ctx);
114 \fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
116 \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result);
119 \fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name,
121 \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata,
123 \fIub_callback_type\fR callback, \fIint*\fR async_id);
126 \fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id);
129 \fBub_resolve_free\fR(\fIstruct ub_result*\fR result);
132 \fBub_strerror\fR(\fIint\fR err);
135 \fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx);
138 \fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type);
141 \fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name);
144 \fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
147 \fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data);
150 is an implementation of a DNS resolver, that does caching and
151 DNSSEC validation. This is the library API, for using the \-lunbound library.
152 The server daemon is described in \fIunbound\fR(8).
153 The library can be used to convert hostnames to ip addresses, and back,
154 and obtain other information from the DNS. The library performs public\-key
155 validation of results with DNSSEC.
157 The library uses a variable of type \fIstruct ub_ctx\fR to keep context
158 between calls. The user must maintain it, creating it with
162 It can be created and deleted at any time. Creating it anew removes any
163 previous configuration (such as trusted keys) and clears any cached results.
165 The functions are thread\-safe, and a context an be used in a threaded (as
166 well as in a non\-threaded) environment. Also resolution (and validation)
167 can be performed blocking and non\-blocking (also called asynchronous).
168 The async method returns from the call immediately, so that processing
169 can go on, while the results become available later.
171 The functions are discussed in turn below.
175 Create a new context, initialised with defaults.
176 The information from /etc/resolv.conf and /etc/hosts is not utilised
182 Before you call this, use the openssl functions CRYPTO_set_id_callback and
183 CRYPTO_set_locking_callback to set up asynchronous operation if you use
184 lib openssl (the application calls these functions once for initialisation).
185 Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
188 Delete validation context and free associated resources.
189 Outstanding async queries are killed and callbacks are not called for them.
192 A power\-user interface that lets you specify one of the options from the
193 config file format, see \fIunbound.conf\fR(5). Not all options are
194 relevant. For some specific options, such as adding trust anchors, special
195 routines exist. Pass the option name with the trailing ':'.
198 A power\-user interface that gets an option value. Some options cannot be
199 gotten, and others return a newline separated list. Pass the option name
200 without trailing ':'. The returned value must be free(2)d by the caller.
203 A power\-user interface that lets you specify an unbound config file, see
204 \fIunbound.conf\fR(5), which is read for configuration. Not all options are
205 relevant. For some specific options, such as adding trust anchors, special
209 Set machine to forward DNS queries to, the caching resolver to use.
210 IP4 or IP6 address. Forwards all DNS requests to that machine, which
211 is expected to run a recursive resolver. If the proxy is not
212 DNSSEC capable, validation may fail. Can be called several times, in
213 that case the addresses are used as backup servers.
214 At this time it is only possible to set configuration before the
215 first resolve is done.
218 Set a stub zone, authoritative dns servers to use for a particular zone.
219 IP4 or IP6 address. If the address is NULL the stub entry is removed.
220 Set isprime true if you configure root hints with it. Otherwise similar to
221 the stub zone item from unbound's config file. Can be called several times,
222 for different zones, or to add multiple addresses for a particular zone.
223 At this time it is only possible to set configuration before the
224 first resolve is done.
227 By default the root servers are queried and full resolver mode is used, but
228 you can use this call to read the list of nameservers to use from the
230 Usually "/etc/resolv.conf". Uses those nameservers as caching proxies.
231 If they do not support DNSSEC, validation may fail.
232 Only nameservers are picked up, the searchdomain, ndots and other
233 settings from \fIresolv.conf\fR(5) are ignored.
234 If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows,
235 the system\-wide configured nameserver is picked instead).
236 At this time it is only possible to set configuration before the
237 first resolve is done.
240 Read list of hosts from the filename given.
241 Usually "/etc/hosts". When queried for, these addresses are not marked
242 DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used
243 (if on Windows, etc/hosts from WINDIR is picked instead).
244 At this time it is only possible to set configuration before the
245 first resolve is done.
249 Add a trust anchor to the given context.
250 At this time it is only possible to add trusted keys before the
251 first resolve is done.
252 The format is a string, similar to the zone\-file format,
253 [domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted.
255 .B ub_ctx_add_ta_autr
256 Add filename with automatically tracked trust anchor to the given context.
257 Pass name of a file with the managed trust anchor. You can create this
258 file with \fIunbound\-anchor\fR(8) for the root anchor. You can also
259 create it with an initial file with one line with a DNSKEY or DS record.
260 If the file is writable, it is updated when the trust anchor changes.
261 At this time it is only possible to add trusted keys before the
262 first resolve is done.
264 .B ub_ctx_add_ta_file
265 Add trust anchors to the given context.
266 Pass name of a file with DS and DNSKEY records in zone file format.
267 At this time it is only possible to add trusted keys before the
268 first resolve is done.
270 .B ub_ctx_trustedkeys
271 Add trust anchors to the given context.
272 Pass the name of a bind\-style config file with trusted\-keys{}.
273 At this time it is only possible to add trusted keys before the
274 first resolve is done.
277 Set debug and error log output to the given stream. Pass NULL to disable
278 output. Default is stderr. File\-names or using syslog can be enabled
279 using config options, this routine is for using your own stream.
282 Set debug verbosity for the context. Output is directed to stderr.
283 Higher debug level gives more output.
286 Set a context behaviour for asynchronous action.
287 if set to true, enables threading and a call to
289 creates a thread to handle work in the background.
290 If false, a process is forked to handle work in the background.
291 Changes to this setting after
293 calls have been made have no effect (delete and re\-create the context
297 Poll a context to see if it has any new results.
298 Do not poll in a loop, instead extract the fd below to poll for readiness,
299 and then check, or wait using the wait routine.
300 Returns 0 if nothing to read, or nonzero if a result is available.
306 Wait for a context to finish with results. Calls
308 after the wait for you. After the wait, there are no more outstanding
309 asynchronous queries.
312 Get file descriptor. Wait for it to become readable, at this point
313 answers are returned from the asynchronous validating resolver.
314 Then call the \fBub_process\fR to continue processing.
317 Call this routine to continue processing results from the validating
318 resolver (when the fd becomes readable).
319 Will perform necessary callbacks.
322 Perform resolution and validation of the target name.
323 The name is a domain name in a zero terminated text string.
324 The rrtype and rrclass are DNS type and class codes.
325 The result structure is newly allocated with the resulting data.
328 Perform asynchronous resolution and validation of the target name.
329 Arguments mean the same as for \fBub_resolve\fR except no
330 data is returned immediately, instead a callback is called later.
331 The callback receives a copy of the mydata pointer, that you can use to pass
332 information to the callback. The callback type is a function pointer to
333 a function declared as
335 void my_callback_function(void* my_arg, int err,
337 struct ub_result* result);
339 The async_id is returned so you can (at your option) decide to track it
340 and cancel the request if needed. If you pass a NULL pointer the async_id
344 Cancel an async query in progress. This may return an error if the query
345 does not exist, or the query is already being delivered, in that case you
346 may still get a callback for the query.
349 Free struct ub_result contents after use.
352 Convert error value from one of the unbound library functions
353 to a human readable string.
355 .B ub_ctx_print_local_zones
356 Debug printout the local authority information to debug output.
359 Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5)
362 .B ub_ctx_zone_remove
363 Delete zone from local authority info.
366 Add resource record data to local authority info, like local\-data
367 \fIunbound.conf\fR(5) statement.
369 .B ub_ctx_data_remove
370 Delete local authority data from the name given.
371 .SH "RESULT DATA STRUCTURE"
372 The result of the DNS resolution and validation is returned as
373 \fIstruct ub_result\fR. The result structure contains the following entries.
377 char* qname; /* text string, original question */
378 int qtype; /* type code asked for */
379 int qclass; /* class code asked for */
380 char** data; /* array of rdata items, NULL terminated*/
381 int* len; /* array with lengths of rdata items */
382 char* canonname; /* canonical name of result */
383 int rcode; /* additional error code in case of no data */
384 void* answer_packet; /* full network format answer packet */
385 int answer_len; /* length of packet in octets */
386 int havedata; /* true if there is data */
387 int nxdomain; /* true if nodata because name does not exist */
388 int secure; /* true if result is secure */
389 int bogus; /* true if a security failure happened */
390 char* why_bogus; /* string with error if bogus */
391 int ttl; /* number of seconds the result is valid */
395 If both secure and bogus are false, security was not enabled for the
396 domain of the query. Else, they are not both true, one of them is true.
398 Many routines return an error code. The value 0 (zero) denotes no error
399 happened. Other values can be passed to
401 to obtain a readable error string.
403 returns a zero terminated string.
405 returns NULL on an error (a malloc failure).
407 returns true if some information may be available, false otherwise.
409 returns a file descriptor or \-1 on error.
411 \fIunbound.conf\fR(5),
415 developers are mentioned in the CREDITS file in the distribution.